SaruWiki mwsaruwikidb https://www.saruman.biz/saruwiki/index.php/Main_Page MediaWiki 1.40.0 first-letter Media Special Talk User User talk SaruWiki SaruWiki talk File File talk MediaWiki MediaWiki talk Template Template talk Help Help talk Category Category talk Property Property talk Concept Concept talk smw/schema smw/schema talk Rule Rule talk 0 1 1 2008-04-19T19:08:00Z MediaWiki default 0 wikitext text/x-wiki <big>'''MediaWiki has been successfully installed.'''</big> Consult the [http://meta.wikimedia.org/wiki/Help:Contents User's Guide] for information on using the wiki software. == Getting started == * [http://www.mediawiki.org/wiki/Help:Configuration_settings Configuration settings list] * [http://www.mediawiki.org/wiki/Help:FAQ MediaWiki FAQ] * [http://mail.wikimedia.org/mailman/listinfo/mediawiki-announce MediaWiki release mailing list] 928e1deea259c70afc3513c66f29f3fcd740d8bf 1405 1 2008-04-19T22:00:13Z Saruman! 2 Protected "[[Main Page]]": Main page is a bit too important to leave unprotected... [edit=sysop:move=sysop] wikitext text/x-wiki <big>'''MediaWiki has been successfully installed.'''</big> Consult the [http://meta.wikimedia.org/wiki/Help:Contents User's Guide] for information on using the wiki software. == Getting started == * [http://www.mediawiki.org/wiki/Help:Configuration_settings Configuration settings list] * [http://www.mediawiki.org/wiki/Help:FAQ MediaWiki FAQ] * [http://mail.wikimedia.org/mailman/listinfo/mediawiki-announce MediaWiki release mailing list] 928e1deea259c70afc3513c66f29f3fcd740d8bf 1406 1405 2008-04-19T22:14:12Z Saruman! 2 First setup of the main page wikitext text/x-wiki <big>'''Welcome to SaruWiki.'''</big> This Wiki is intended to document bits and bobs about [http://www.kernel.org/ Linux] (and some Unix) in general, and [http://www.debian.org Debian] in particular. In it, [[SaruTeam|we]] wish to collect the tips and tricks of both [[SaruTeam|our own team of Linux admins]] and those of other interested users. Consult the [http://meta.wikimedia.org/wiki/Help:Contents User's Guide] for information on using this wiki's software. ---- <big>'''Main Content'''</big> * Setting up a [[Debian Etch base server]] is a howto on the installation of, well, really a base server under Etch. * Using ''md'' for [[software RAID]] contains our ideas and observations on redundancy. * [[Hardware monitoring]] is important for your server's health and reliability. * [[Database 101]] introduces you to MySQL. ---- '''Note''': the Wiki admins reserve the right to edit or remove any content they feel is not suitable for this site, not relevant, (too) inaccurate or otherwise not in line with the intentions and spirit of the admin team. 3b947ca2e07c751b359e0ab62d00294459189026 1409 1406 2008-04-20T10:45:41Z Saruman! 2 VMware link added wikitext text/x-wiki <big>'''Welcome to SaruWiki.'''</big> This Wiki is intended to document bits and bobs about [http://www.kernel.org/ Linux] (and some Unix) in general, and [http://www.debian.org Debian] in particular. In it, [[SaruTeam|we]] wish to collect the tips and tricks of both [[SaruTeam|our own team of Linux admins]] and those of other interested users. Consult the [http://meta.wikimedia.org/wiki/Help:Contents User's Guide] for information on using this wiki's software. ---- <big>'''Main Content'''</big> * Setting up a [[Debian Etch base server]] is a howto on the installation of, well, really a base server under Etch. * Using ''md'' for [[software RAID]] contains our ideas and observations on redundancy. * [[Hardware monitoring]] is important for your server's health and reliability. * [[Database 101]] introduces you to MySQL. * [[Vmware_server|VMware Server basics]] gives some pointers on how to install VMware Server on a Debian server box. ---- '''Note''': the Wiki admins reserve the right to edit or remove any content they feel is not suitable for this site, not relevant, (too) inaccurate or otherwise not in line with the intentions and spirit of the admin team. 8bc36562e890ab2bd5e4dd568c0d40af53b92120 1416 1409 2008-04-20T18:43:10Z Saruman! 2 VPNlink added wikitext text/x-wiki <big>'''Welcome to SaruWiki.'''</big> This Wiki is intended to document bits and bobs about [http://www.kernel.org/ Linux] (and some Unix) in general, and [http://www.debian.org Debian] in particular. In it, [[SaruTeam|we]] wish to collect the tips and tricks of both [[SaruTeam|our own team of Linux admins]] and those of other interested users. Consult the [http://meta.wikimedia.org/wiki/Help:Contents User's Guide] for information on using this wiki's software. ---- <big>'''Main Content'''</big> * Setting up a [[Debian Etch base server]] is a howto on the installation of, well, really a base server under Etch. * Using ''md'' for [[software RAID]] contains our ideas and observations on redundancy. * [[Hardware monitoring]] is important for your server's health and reliability. * [[Database 101]] introduces you to MySQL. * [[Vmware_server|VMware Server basics]] gives some pointers on how to install VMware Server on a Debian server box. * Make your server a [[Microsoft PPTP server | Microsoft client compatible VPN Server ]]. ---- '''Note''': the Wiki admins reserve the right to edit or remove any content they feel is not suitable for this site, not relevant, (too) inaccurate or otherwise not in line with the intentions and spirit of the admin team. b0645d73c6e9e1e7bd8999b6a4559883a1dfc4aa 1457 1416 2008-05-18T19:28:14Z Saruman! 2 Added kernel/firewall/ipsec wikitext text/x-wiki <big>'''Welcome to SaruWiki.'''</big> This Wiki is intended to document bits and bobs about [http://www.kernel.org/ Linux] (and some Unix) in general, and [http://www.debian.org Debian] in particular. In it, [[SaruTeam|we]] wish to collect the tips and tricks of both [[SaruTeam|our own team of Linux admins]] and those of other interested users. Consult the [http://meta.wikimedia.org/wiki/Help:Contents User's Guide] for information on using this wiki's software. ---- <big>'''Main Content'''</big> * Setting up a [[Debian Etch base server]] is a howto on the installation of, well, really a base server under Etch. * [[Roll your own kernel]] discusses the pros and cons of compiling your own kernel, and how to do it. * The [[Firewall section]] is where we discuss "IPtables" (netfilter) and how we use it for firewalling. * The [[native IPsec tunnel]] section describes how to configure an IPsec tunnel. * Using ''md'' for [[software RAID]] contains our ideas and observations on redundancy. * [[Hardware monitoring]] is important for your server's health and reliability. * [[Database 101]] introduces you to MySQL. * [[Vmware_server|VMware Server basics]] gives some pointers on how to install VMware Server on a Debian server box. * Make your server a [[Microsoft PPTP server | Microsoft client compatible VPN Server ]]. ---- '''Note''': the Wiki admins reserve the right to edit or remove any content they feel is not suitable for this site, not relevant, (too) inaccurate or otherwise not in line with the intentions and spirit of the admin team. 0d24ba12104e23e7c474801c6b692817a6fc4a6f 1458 1457 2008-05-18T19:30:49Z Saruman! 2 added APT wikitext text/x-wiki <big>'''Welcome to SaruWiki.'''</big> This Wiki is intended to document bits and bobs about [http://www.kernel.org/ Linux] (and some Unix) in general, and [http://www.debian.org Debian] in particular. In it, [[SaruTeam|we]] wish to collect the tips and tricks of both [[SaruTeam|our own team of Linux admins]] and those of other interested users. Consult the [http://meta.wikimedia.org/wiki/Help:Contents User's Guide] for information on using this wiki's software. ---- <big>'''Main Content'''</big> * Setting up a [[Debian Etch base server]] is a howto on the installation of, well, really a base server under Etch. * The use of [[APT and aptitude]] is crucial to the concept of a Debian machine. * [[Roll your own kernel]] discusses the pros and cons of compiling your own kernel, and how to do it. * The [[Firewall section]] is where we discuss "IPtables" (netfilter) and how we use it for firewalling. * The [[native IPsec tunnel]] section describes how to configure an IPsec tunnel. * Using ''md'' for [[software RAID]] contains our ideas and observations on redundancy. * [[Hardware monitoring]] is important for your server's health and reliability. * [[Database 101]] introduces you to MySQL. * [[Vmware_server|VMware Server basics]] gives some pointers on how to install VMware Server on a Debian server box. * Make your server a [[Microsoft PPTP server | Microsoft client compatible VPN Server ]]. ---- '''Note''': the Wiki admins reserve the right to edit or remove any content they feel is not suitable for this site, not relevant, (too) inaccurate or otherwise not in line with the intentions and spirit of the admin team. e197e5f436082293652c3d56fd9ba552e05f0b39 0 1405 1407 2008-04-20T10:31:45Z Insomnia 3 wikitext text/x-wiki Install the following packages libx11-dev x-window-system-core x-window-system xspecs libxtst6 psmisc build-essential Now download the software # cd /tmp # wget http://download3.vmware.com/software/vmserver/VMware-mui-1.0.5-80187.tar.gz # wget http://download3.vmware.com/software/vmserver/VMware-server-1.0.5-80187.tar.gz # wget http://knihovny.cvut.cz/ftp/pub/vmware/vmware-any-any-update115.tar.gz tar xvfz Vmware-server-1.0.5-80187.tar.gz tar xvfz Vmware-mui-1.0.5-80187.tar.gz tar xvfz vmware-any-any-update115.tar.gz Run het install script cd vmware-server-distrib/ ./vmware-install.pl I got a "Unable to build the vmmon module." So i need to run the vmware-any-any-update #cd vmware-any-any-update115 # ./runme.pl And for the User interface # cd Vmware-mui-1.0.5-80187 # ./nameinstallscript 89eef9ed4ed724e53233f7a2b0f27782d82ae8a4 0 1408 1411 2008-04-20T13:48:27Z Insomnia 3 wikitext text/x-wiki == '''LM sensors''' == turn on i2c support in your kernel -device drivers\i2c support -device drivers\hardware monitoring\ ite87 -Asus asb100 - amd athlon temp install the package - lm-sensors # sensors-detect -> wil give you a view of the found sensors b00a20c0f667c1d7316de71fc385d4162795e284 1412 1411 2008-04-20T13:49:27Z Insomnia 3 wikitext text/x-wiki == '''LM sensors''' == turn on i2c support in your kernel -device drivers\i2c support -device drivers\hardware monitoring\ ite87 -Asus asb100 - amd athlon temp install the package - lm-sensors # sensors-detect -> wil give you a view of the found sensors # sensors will give you the readout of the sensors 71b2dcefb4a21bcee55777b1721fa2376d8a6bc1 1413 1412 2008-04-20T13:50:38Z Insomnia 3 wikitext text/x-wiki == '''LM sensors''' == turn on i2c support in your kernel -device drivers\i2c support -device drivers\hardware monitoring\ ite87 -Asus asb100 - amd athlon temp install the package - lm-sensors ># sensors-detect -> wil give you a view of the found sensors (say YES to all questions) ># sensors will give you the readout of the sensors 308ece04224cb9fb1ab80b8d91e0b3f2eeb576ac 1429 1413 2008-05-12T14:00:23Z Insomnia 3 /* '''LM sensors''' */ wikitext text/x-wiki == '''LM sensors''' == turn on i2c support in your kernel -device drivers\i2c support -device drivers\hardware monitoring\ ite87 -Asus asb100 - amd athlon temp install the package - lm-sensors ># sensors-detect -> wil give you a view of the found sensors (say YES to all questions) Driver `eeprom' (should be inserted): Detects correctly: * Bus `SMBus PIIX4 adapter at 0b00' Busdriver `i2c-piix4', I2C address 0x50 Chip `eeprom' (confidence: 6) * Bus `SMBus PIIX4 adapter at 0b00' Busdriver `i2c-piix4', I2C address 0x51 Chip `eeprom' (confidence: 6) EEPROMs are *NOT* sensors! They are data storage chips commonly found on memory modules (SPD), in monitors (EDID), or in some laptops, for example. Driver `k8temp' (should be inserted): Detects correctly: * ISA bus, undetermined address (Busdriver `i2c-isa') Chip `AMD K8 thermal sensors' (confidence: 9) Driver `it87' (should be inserted): Detects correctly: * ISA bus address 0x0228 (Busdriver `i2c-isa') Chip `ITE IT8716F Super IO Sensors' (confidence: 9) The script will give you the appropiate line to insert in /etc/modules Make shure that the modules are configured in your kernel #----cut here---- # I2C adapter drivers i2c-piix4 # Chip drivers # Warning: the required module eeprom is not currently installed # on your system. For status of 2.6 kernel ports check # http://www.lm-sensors.org/wiki/Devices. If driver is built # into the kernel, or unavailable, comment out the following line. eeprom # Warning: the required module k8temp is not currently installed # on your system. For status of 2.6 kernel ports check # http://www.lm-sensors.org/wiki/Devices. If driver is built # into the kernel, or unavailable, comment out the following line. k8temp # Warning: the required module it87 is not currently installed # on your system. For status of 2.6 kernel ports check # http://www.lm-sensors.org/wiki/Devices. If driver is built # into the kernel, or unavailable, comment out the following line. it87 #----cut here---- ># sensors will give you the readout of the sensors it8716-isa-0228 Adapter: ISA adapter VCore: +1.01 V (min = +0.00 V, max = +4.08 V) VDDR: +3.38 V (min = +3.57 V, max = +4.08 V) ALARM +3.3V: +0.00 V (min = +0.00 V, max = +4.08 V) ALARM +5V: +4.89 V (min = +0.00 V, max = +6.80 V) +12V: +11.97 V (min = +0.00 V, max = +16.32 V) in5: +0.00 V (min = +0.00 V, max = +4.08 V) ALARM in6: +0.00 V (min = +0.00 V, max = +4.08 V) ALARM 5VSB: +4.89 V (min = +0.00 V, max = +6.85 V) VBat: +3.22 V fan1: 1588 RPM (min = 3245 RPM) fan2: 0 RPM (min = 3245 RPM) temp1: +27°C (low = -1°C, high = +127°C) sensor = diode temp2: +32°C (low = -17°C, high = +127°C) sensor = thermistor temp3: +25°C (low = -1°C, high = +127°C) sensor = thermistor vid: +1.550 V k8temp-pci-00c3 Adapter: PCI adapter Core0 Temp: +7°C Core0 Temp: -1°C Core1 Temp: +8°C Core1 Temp: +9°C The read out of the CPU temp is still an issue. As you can see it gives the wrong values 20d711c923d1c8976a46fd7538e83d351625b09b 1430 1429 2008-05-12T14:02:32Z Insomnia 3 /* '''LM sensors''' */ wikitext text/x-wiki == '''LM sensors''' == turn on i2c support in your kernel -device drivers\i2c support -device drivers\hardware monitoring\ ite87 -Asus asb100 - amd athlon temp install the package lm-sensors Apt-get install lm-sensors ># sensors-detect -> wil give you a view of the found sensors (say YES to all questions) Driver `eeprom' (should be inserted): Detects correctly: * Bus `SMBus PIIX4 adapter at 0b00' Busdriver `i2c-piix4', I2C address 0x50 Chip `eeprom' (confidence: 6) * Bus `SMBus PIIX4 adapter at 0b00' Busdriver `i2c-piix4', I2C address 0x51 Chip `eeprom' (confidence: 6) EEPROMs are *NOT* sensors! They are data storage chips commonly found on memory modules (SPD), in monitors (EDID), or in some laptops, for example. Driver `k8temp' (should be inserted): Detects correctly: * ISA bus, undetermined address (Busdriver `i2c-isa') Chip `AMD K8 thermal sensors' (confidence: 9) Driver `it87' (should be inserted): Detects correctly: * ISA bus address 0x0228 (Busdriver `i2c-isa') Chip `ITE IT8716F Super IO Sensors' (confidence: 9) The script will give you the appropiate line to insert in /etc/modules Make shure that the modules are configured in your kernel #----cut here---- # I2C adapter drivers i2c-piix4 # Chip drivers # Warning: the required module eeprom is not currently installed # on your system. For status of 2.6 kernel ports check # http://www.lm-sensors.org/wiki/Devices. If driver is built # into the kernel, or unavailable, comment out the following line. eeprom # Warning: the required module k8temp is not currently installed # on your system. For status of 2.6 kernel ports check # http://www.lm-sensors.org/wiki/Devices. If driver is built # into the kernel, or unavailable, comment out the following line. k8temp # Warning: the required module it87 is not currently installed # on your system. For status of 2.6 kernel ports check # http://www.lm-sensors.org/wiki/Devices. If driver is built # into the kernel, or unavailable, comment out the following line. it87 #----cut here---- ># sensors will give you the readout of the sensors it8716-isa-0228 Adapter: ISA adapter VCore: +1.01 V (min = +0.00 V, max = +4.08 V) VDDR: +3.38 V (min = +3.57 V, max = +4.08 V) ALARM +3.3V: +0.00 V (min = +0.00 V, max = +4.08 V) ALARM +5V: +4.89 V (min = +0.00 V, max = +6.80 V) +12V: +11.97 V (min = +0.00 V, max = +16.32 V) in5: +0.00 V (min = +0.00 V, max = +4.08 V) ALARM in6: +0.00 V (min = +0.00 V, max = +4.08 V) ALARM 5VSB: +4.89 V (min = +0.00 V, max = +6.85 V) VBat: +3.22 V fan1: 1588 RPM (min = 3245 RPM) fan2: 0 RPM (min = 3245 RPM) temp1: +27°C (low = -1°C, high = +127°C) sensor = diode temp2: +32°C (low = -17°C, high = +127°C) sensor = thermistor temp3: +25°C (low = -1°C, high = +127°C) sensor = thermistor vid: +1.550 V k8temp-pci-00c3 Adapter: PCI adapter Core0 Temp: +7°C Core0 Temp: -1°C Core1 Temp: +8°C Core1 Temp: +9°C The read out of the CPU temp is still an issue. As you can see it gives the wrong values b9fcf2d499ddfa2570c4a6da5f3ec3e682992042 1431 1430 2008-05-12T14:03:51Z Insomnia 3 /* '''LM sensors''' */ wikitext text/x-wiki == '''LM sensors''' == turn on i2c support in your kernel -device drivers\i2c support And turn on the appropiate device drivers in the kernel -device drivers\hardware monitoring\ ite87 -Asus asb100 - amd athlon temp install the package lm-sensors Apt-get install lm-sensors ># sensors-detect -> wil give you a view of the found sensors (say YES to all questions) Driver `eeprom' (should be inserted): Detects correctly: * Bus `SMBus PIIX4 adapter at 0b00' Busdriver `i2c-piix4', I2C address 0x50 Chip `eeprom' (confidence: 6) * Bus `SMBus PIIX4 adapter at 0b00' Busdriver `i2c-piix4', I2C address 0x51 Chip `eeprom' (confidence: 6) EEPROMs are *NOT* sensors! They are data storage chips commonly found on memory modules (SPD), in monitors (EDID), or in some laptops, for example. Driver `k8temp' (should be inserted): Detects correctly: * ISA bus, undetermined address (Busdriver `i2c-isa') Chip `AMD K8 thermal sensors' (confidence: 9) Driver `it87' (should be inserted): Detects correctly: * ISA bus address 0x0228 (Busdriver `i2c-isa') Chip `ITE IT8716F Super IO Sensors' (confidence: 9) The script will give you the appropiate line to insert in /etc/modules Make shure that the modules are configured in your kernel #----cut here---- # I2C adapter drivers i2c-piix4 # Chip drivers # Warning: the required module eeprom is not currently installed # on your system. For status of 2.6 kernel ports check # http://www.lm-sensors.org/wiki/Devices. If driver is built # into the kernel, or unavailable, comment out the following line. eeprom # Warning: the required module k8temp is not currently installed # on your system. For status of 2.6 kernel ports check # http://www.lm-sensors.org/wiki/Devices. If driver is built # into the kernel, or unavailable, comment out the following line. k8temp # Warning: the required module it87 is not currently installed # on your system. For status of 2.6 kernel ports check # http://www.lm-sensors.org/wiki/Devices. If driver is built # into the kernel, or unavailable, comment out the following line. it87 #----cut here---- ># sensors will give you the readout of the sensors it8716-isa-0228 Adapter: ISA adapter VCore: +1.01 V (min = +0.00 V, max = +4.08 V) VDDR: +3.38 V (min = +3.57 V, max = +4.08 V) ALARM +3.3V: +0.00 V (min = +0.00 V, max = +4.08 V) ALARM +5V: +4.89 V (min = +0.00 V, max = +6.80 V) +12V: +11.97 V (min = +0.00 V, max = +16.32 V) in5: +0.00 V (min = +0.00 V, max = +4.08 V) ALARM in6: +0.00 V (min = +0.00 V, max = +4.08 V) ALARM 5VSB: +4.89 V (min = +0.00 V, max = +6.85 V) VBat: +3.22 V fan1: 1588 RPM (min = 3245 RPM) fan2: 0 RPM (min = 3245 RPM) temp1: +27°C (low = -1°C, high = +127°C) sensor = diode temp2: +32°C (low = -17°C, high = +127°C) sensor = thermistor temp3: +25°C (low = -1°C, high = +127°C) sensor = thermistor vid: +1.550 V k8temp-pci-00c3 Adapter: PCI adapter Core0 Temp: +7°C Core0 Temp: -1°C Core1 Temp: +8°C Core1 Temp: +9°C The read out of the CPU temp is still an issue. As you can see it gives the wrong values 6fb3fb0f17ca906e735862ceaee1976224695044 1448 1431 2008-05-17T18:58:06Z Insomnia 3 wikitext text/x-wiki * [[LM Sensors]] * [[Smart Daemon]] d09f8ef9350ef3c546207bec578413e57b37bdc7 0 1409 1414 2008-04-20T15:43:30Z Saruman! 2 wikitext text/x-wiki <big>'''Debian Etch Base Server setup'''</big> ==Getting the hardware== Naturally, before we can begin to install the operating system, we need to obtain the necessary hardware. Which hardware you require depends on what you want the server for; a testserver on which you will test only a single feature for a short while does not need the same quality of hardware as does a server that's supposed to act as a homeserver for many tasks for a long time. We'll assume your server will be like ours: a home server that must perform many tasks with sufficient performance for a few users, that's reliable and will last for a couple of years. So build or obtain a server with at least the following hardware: * a spacious casing with big, quiet cooling fans, like the [http://www.coolermaster.com/products/product.php?act=detail&id=317 one we have]; * an efficient, heavy-duty power supply that's rated high enough for your devices, and has a decent efficiency. For example, a [http://www.corsair.com/products/power_supplies.aspx Corsair HX520] power supply; * a server class motherboard, e.g. an [http://www.intel.com/products/server/index.htm?iid=home+hdr_nav2_server Intel] or [http://uk.asus.com/products.aspx?l1=9&l2=39&l3=263 AMD] based single-processor motherboard. DO NOT go for the cheapest motherboard you can find: if you pay peanuts, that's what you get. Server class motherboards have the quality, stability and durability you'll need from it, and usually also most of the needed peripherals, like multiple ethernet network cards on-board. Usually a Linux server doesn not require much in the way of video performance (and the screen will be used rarely, if ever), so any old integrated graphics will do. * a matching CPU - or multiple, if you think you need the power and the selected motherboard has the sockets. * a CD-ROM- or DVD-player * ''multiple'' harddisks - you'll want redundancy, because every harddisk fails at some time. The drive with your data on it will fail fatally when it is most inconvenient to you, and any data on it that you consider valuable will likely be lost forever. To make Murphy's work somewhat harder for him, we're going to store our data redundantly, so that if any drive in the server fails, we'll not lose our data or our server. Thus, get yourself at least two harddisks for your operating system, at least 40GiB in size (don't think you'll be able to buy smaller ones nowadays), and spanking new (NEVER use old harddisks for your production server, new ones are just too cheap to run that risk!). * (multipe) network card(s) (NICs) if your motherboard does not have enough NICs integrated on-board. You'll want a NIC for your network, and another one for your Internet connection; and possible a third one for the wireless segment of your network. Now build a machine out of the above, or have someone build it for you. ==Preparation of the hardware== 5f2532dd5c41defc41f1a034e1b72e97a77a4287 1418 1414 2008-04-27T14:53:01Z Saruman! 2 Partitioning table added wikitext text/x-wiki <big>'''Debian Etch Base Server setup'''</big> ==Getting the hardware== Naturally, before we can begin to install the operating system, we need to obtain the necessary hardware. Which hardware you require depends on what you want the server for; a testserver on which you will test only a single feature for a short while does not need the same quality of hardware as does a server that's supposed to act as a homeserver for many tasks for a long time. We'll assume your server will be like ours: a home server that must perform many tasks with sufficient performance for a few users, that's reliable and will last for a couple of years. So build or obtain a server with at least the following hardware: * a spacious casing with big, quiet cooling fans, like the [http://www.coolermaster.com/products/product.php?act=detail&id=317 one we have]; * an efficient, heavy-duty power supply that's rated high enough for your devices, and has a decent efficiency. For example, a [http://www.corsair.com/products/power_supplies.aspx Corsair HX520] power supply; * a server class motherboard, e.g. an [http://www.intel.com/products/server/index.htm?iid=home+hdr_nav2_server Intel] or [http://uk.asus.com/products.aspx?l1=9&l2=39&l3=263 AMD] based single-processor motherboard. DO NOT go for the cheapest motherboard you can find: if you pay peanuts, that's what you get. Server class motherboards have the quality, stability and durability you'll need from it, and usually also most of the needed peripherals, like multiple ethernet network cards on-board. Usually a Linux server doesn not require much in the way of video performance (and the screen will be used rarely, if ever), so any old integrated graphics will do. * a matching CPU - or multiple, if you think you need the power and the selected motherboard has the sockets. * a CD-ROM- or DVD-player * ''multiple'' harddisks - you'll want redundancy, because every harddisk fails at some time. The drive with your data on it will fail fatally when it is most inconvenient to you, and any data on it that you consider valuable will likely be lost forever. To make Murphy's work somewhat harder for him, we're going to store our data redundantly, so that if any drive in the server fails, we'll not lose our data or our server. Thus, get yourself at least two harddisks for your operating system, at least 40GiB in size (don't think you'll be able to buy smaller ones nowadays), and spanking new (NEVER use old harddisks for your production server, new ones are just too cheap to run that risk!). * (multipe) network card(s) (NICs) if your motherboard does not have enough NICs integrated on-board. You'll want a NIC for your network, and another one for your Internet connection; and possible a third one for the wireless segment of your network. Now build a machine out of the above, or have someone build it for you. ==Preparation of the hardware== ==Partitioning== This is a tricky subject, but we have put together a recommended standard partitioning scheme. The basis is this: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !Partition !MD !LVG !LV-name !Size (physical machine) !Size (VM) !File System !Mount point |- | 1 | /dev/md0 | x | x | 100MiB | 100MiB | ext3 | /boot |- | 2 | /dev/md1 | x | x | 3GiB | 1GiB | ext3 | / |- | 3 | /dev/md2 | system | swap | 1GiB(+) | 256MiB(+) | swap | x |- | 3 | /dev/md2 | system | var | 2GiB | 1GiB | ext3 | /var |- | 3 | /dev/md2 | system | appslog | 3GiB | x | ext3 | /var/appslog |- | 3 | /dev/md2 | system | home | 1GiB(++) | 512MiB(++) | ext3 | /home |- | 3 | /dev/md2 | system | usr | 3GiB | 3GiB | ext3 | /usr |- | 3 | /dev/md2 | system | tmp | 1GiB | 512MiB | ext3 | /tmp |- | 3 | /dev/md2 | system | opt | 1GiB | x | ext3 | /opt |- ! colspan="4" style="text-align:right"| Total ! 18.1GiB ! 6.9GiB ! colspan="2" | |- } 4f1c98b216bf9a0697a1f1bc8ae0f700b881d706 1419 1418 2008-04-27T16:18:27Z Saruman! 2 /* Partitioning */ wikitext text/x-wiki <big>'''Debian Etch Base Server setup'''</big> ==Getting the hardware== Naturally, before we can begin to install the operating system, we need to obtain the necessary hardware. Which hardware you require depends on what you want the server for; a testserver on which you will test only a single feature for a short while does not need the same quality of hardware as does a server that's supposed to act as a homeserver for many tasks for a long time. We'll assume your server will be like ours: a home server that must perform many tasks with sufficient performance for a few users, that's reliable and will last for a couple of years. So build or obtain a server with at least the following hardware: * a spacious casing with big, quiet cooling fans, like the [http://www.coolermaster.com/products/product.php?act=detail&id=317 one we have]; * an efficient, heavy-duty power supply that's rated high enough for your devices, and has a decent efficiency. For example, a [http://www.corsair.com/products/power_supplies.aspx Corsair HX520] power supply; * a server class motherboard, e.g. an [http://www.intel.com/products/server/index.htm?iid=home+hdr_nav2_server Intel] or [http://uk.asus.com/products.aspx?l1=9&l2=39&l3=263 AMD] based single-processor motherboard. DO NOT go for the cheapest motherboard you can find: if you pay peanuts, that's what you get. Server class motherboards have the quality, stability and durability you'll need from it, and usually also most of the needed peripherals, like multiple ethernet network cards on-board. Usually a Linux server doesn not require much in the way of video performance (and the screen will be used rarely, if ever), so any old integrated graphics will do. * a matching CPU - or multiple, if you think you need the power and the selected motherboard has the sockets. * a CD-ROM- or DVD-player * ''multiple'' harddisks - you'll want redundancy, because every harddisk fails at some time. The drive with your data on it will fail fatally when it is most inconvenient to you, and any data on it that you consider valuable will likely be lost forever. To make Murphy's work somewhat harder for him, we're going to store our data redundantly, so that if any drive in the server fails, we'll not lose our data or our server. Thus, get yourself at least two harddisks for your operating system, at least 40GiB in size (don't think you'll be able to buy smaller ones nowadays), and spanking new (NEVER use old harddisks for your production server, new ones are just too cheap to run that risk!). * (multipe) network card(s) (NICs) if your motherboard does not have enough NICs integrated on-board. You'll want a NIC for your network, and another one for your Internet connection; and possible a third one for the wireless segment of your network. Now build a machine out of the above, or have someone build it for you. ==Preparation of the hardware== ==Partitioning== This is a tricky subject, but we have put together a recommended standard partitioning scheme. The basis is this: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Partition !style="background:#ffdead;"|MD !style="background:#ffdead;"|LVG !style="background:#ffdead;"|LV-name !style="background:#ffdead;"|Size <br> (physical machine) !style="background:#ffdead;"|Size (VM) !style="background:#ffdead;"|File System !style="background:#ffdead;"|Mount point |- | 1 | /dev/md0 | &nbsp; | &nbsp; | 100MiB | 100MiB | ext3 | /boot |- | 2 | /dev/md1 | &nbsp; | &nbsp; | 3GiB | 1GiB | ext3 | / |- | rowspan="7" valign="top" | 3 | rowspan="7" valign="top" | /dev/md2 | rowspan="7" valign="top" style="background:lightgrey"| system | style="background:lightgrey" | swap | 1GiB<ref name=swap>Rule of thumb: twice the size of the machine's RAM, but no less than 256MiB and no more than 2GiB</ref> | 256MiB<ref name=swap/> | swap | &nbsp; |- | style="background:lightgrey" | var | 2GiB | 1GiB | ext3 | /var |- | style="background:lightgrey" | appslog | 3GiB | - | ext3 | /var/appslog |- | style="background:lightgrey" | home | 1GiB<ref name=home>Note that this heavily depends on the purpose of the machine; if it is not to house any users, then (almost) no space is needed for /home. But on the other hand if e.g. a virtual user is to be used for keeping mailstores, or other service users need home space, then /home needs to be big enough for that.</ref> | 512MiB<ref name=home/> | ext3 | /home |- | style="background:lightgrey" | usr | 3GiB | 3GiB | ext3 | /usr |- | style="background:lightgrey" | tmp | 1GiB | 512MiB | ext3 | /tmp |- | style="background:lightgrey" | opt | 1GiB | - | ext3 | /opt |- ! colspan="4" style="text-align:right"| Total ! 18.1GiB ! 6.9GiB ! colspan="2" | |- |} (+)Rule of thumb: twice the size of the machine's RAM, but no less than 256MiB and no more than 2GiB<br> (++) Note that this heavily depends on the purpose of the machine; if it is not to house any users, then (almost) no space is needed for /home. But on the other hand if e.g. a virtual user is to be used for keeping mailstores, or other service users need home space, then /home needs to be big enough for that. <references/> 390bad4f2b90ecc8748b063f9067a186d8b570b3 1420 1419 2008-04-27T16:43:52Z Saruman! 2 /* Partitioning */ wikitext text/x-wiki <big>'''Debian Etch Base Server setup'''</big> ==Getting the hardware== Naturally, before we can begin to install the operating system, we need to obtain the necessary hardware. Which hardware you require depends on what you want the server for; a testserver on which you will test only a single feature for a short while does not need the same quality of hardware as does a server that's supposed to act as a homeserver for many tasks for a long time. We'll assume your server will be like ours: a home server that must perform many tasks with sufficient performance for a few users, that's reliable and will last for a couple of years. So build or obtain a server with at least the following hardware: * a spacious casing with big, quiet cooling fans, like the [http://www.coolermaster.com/products/product.php?act=detail&id=317 one we have]; * an efficient, heavy-duty power supply that's rated high enough for your devices, and has a decent efficiency. For example, a [http://www.corsair.com/products/power_supplies.aspx Corsair HX520] power supply; * a server class motherboard, e.g. an [http://www.intel.com/products/server/index.htm?iid=home+hdr_nav2_server Intel] or [http://uk.asus.com/products.aspx?l1=9&l2=39&l3=263 AMD] based single-processor motherboard. DO NOT go for the cheapest motherboard you can find: if you pay peanuts, that's what you get. Server class motherboards have the quality, stability and durability you'll need from it, and usually also most of the needed peripherals, like multiple ethernet network cards on-board. Usually a Linux server doesn not require much in the way of video performance (and the screen will be used rarely, if ever), so any old integrated graphics will do. * a matching CPU - or multiple, if you think you need the power and the selected motherboard has the sockets. * a CD-ROM- or DVD-player * ''multiple'' harddisks - you'll want redundancy, because every harddisk fails at some time. The drive with your data on it will fail fatally when it is most inconvenient to you, and any data on it that you consider valuable will likely be lost forever. To make Murphy's work somewhat harder for him, we're going to store our data redundantly, so that if any drive in the server fails, we'll not lose our data or our server. Thus, get yourself at least two harddisks for your operating system, at least 40GiB in size (don't think you'll be able to buy smaller ones nowadays), and spanking new (NEVER use old harddisks for your production server, new ones are just too cheap to run that risk!). * (multipe) network card(s) (NICs) if your motherboard does not have enough NICs integrated on-board. You'll want a NIC for your network, and another one for your Internet connection; and possible a third one for the wireless segment of your network. Now build a machine out of the above, or have someone build it for you. ==Preparation of the hardware== ==Partitioning== This is a tricky subject, but we have put together a recommended standard partitioning scheme. The basis is this: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Partition !style="background:#ffdead;"|MD !style="background:#ffdead;"|LVG !style="background:#ffdead;"|LV-name !style="background:#ffdead;"|Size <br> (physical machine) !style="background:#ffdead;"|Size (VM) !style="background:#ffdead;"|File System !style="background:#ffdead;"|Mount point |- | 1 | /dev/md0 | &nbsp; | &nbsp; | 100MiB | 100MiB | ext3 | /boot |- | 2 | /dev/md1 | &nbsp; | &nbsp; | 3GiB | 1GiB | ext3 | / |- | rowspan="7" valign="top" | 3 | rowspan="7" valign="top" | /dev/md2 | rowspan="7" valign="top" style="background:lightgrey"| system | style="background:lightgrey" | swap | 1GiB<ref name="swap">Rule of thumb: twice the size of the machine's RAM, but no less than 256MiB and no more than 2GiB</ref> | 256MiB<ref name="swap"/> | swap | &nbsp; |- | style="background:lightgrey" | var | 2GiB | 1GiB | ext3 | /var |- | style="background:lightgrey" | appslog | 3GiB | - | ext3 | /var/appslog |- | style="background:lightgrey" | home | 1GiB<ref name="home">Note that this heavily depends on the purpose of the machine; if it is not to house any users, then (almost) no space is needed for /home. But on the other hand if e.g. a virtual user is to be used for keeping mailstores, or other service users need home space, then /home needs to be big enough for that.</ref> | 512MiB<ref name="home"/> | ext3 | /home |- | style="background:lightgrey" | usr | 3GiB | 3GiB | ext3 | /usr |- | style="background:lightgrey" | tmp | 1GiB | 512MiB | ext3 | /tmp |- | style="background:lightgrey" | opt | 1GiB | - | ext3 | /opt |- ! colspan="4" style="text-align:right"| Total ! 18.1GiB ! 6.9GiB ! colspan="2" | |- |} <references/> 63b1c991ef0f0dff88013bf79c6800b328ef5aee 1421 1420 2008-04-27T20:02:27Z 212.238.151.172 0 Preparation of the hardware wikitext text/x-wiki <big>'''Debian Etch Base Server setup'''</big> ==Getting the hardware== Naturally, before we can begin to install the operating system, we need to obtain the necessary hardware. Which hardware you require depends on what you want the server for; a testserver on which you will test only a single feature for a short while does not need the same quality of hardware as does a server that's supposed to act as a homeserver for many tasks for a long time. We'll assume your server will be like ours: a home server that must perform many tasks with sufficient performance for a few users, that's reliable and will last for a couple of years. So build or obtain a server with at least the following hardware: * a spacious casing with big, quiet cooling fans, like the [http://www.coolermaster.com/products/product.php?act=detail&id=317 one we have]; * an efficient, heavy-duty power supply that's rated high enough for your devices, and has a decent efficiency. For example, a [http://www.corsair.com/products/power_supplies.aspx Corsair HX520] power supply; * a server class motherboard, e.g. an [http://www.intel.com/products/server/index.htm?iid=home+hdr_nav2_server Intel] or [http://uk.asus.com/products.aspx?l1=9&l2=39&l3=263 AMD] based single-processor motherboard. DO NOT go for the cheapest motherboard you can find: if you pay peanuts, that's what you get. Server class motherboards have the quality, stability and durability you'll need from it, and usually also most of the needed peripherals, like multiple ethernet network cards on-board. Usually a Linux server doesn not require much in the way of video performance (and the screen will be used rarely, if ever), so any old integrated graphics will do. * a matching CPU - or multiple, if you think you need the power and the selected motherboard has the sockets. * a CD-ROM- or DVD-player * ''multiple'' harddisks - you'll want redundancy, because every harddisk fails at some time. The drive with your data on it will fail fatally when it is most inconvenient to you, and any data on it that you consider valuable will likely be lost forever. To make Murphy's work somewhat harder for him, we're going to store our data redundantly, so that if any drive in the server fails, we'll not lose our data or our server. Thus, get yourself at least two harddisks for your operating system, at least 40GiB in size (don't think you'll be able to buy smaller ones nowadays), and spanking new (NEVER use old harddisks for your production server, new ones are just too cheap to run that risk!). * (multipe) network card(s) (NICs) if your motherboard does not have enough NICs integrated on-board. You'll want a NIC for your network, and another one for your Internet connection; and possible a third one for the wireless segment of your network. Now build a machine out of the above, or have someone build it for you. ==Preparation of the hardware== (Note: in the following we're again assuming you're running an x86/x64 type of machine. Hardware requirements and preparation for other platforms, e.g. IBM's Series p or HP 9000, can differ significantly) Next, check the assembled hardware: * is the configuration complete? * are all components connected properly (memory DIMMs seated correctly in their sockets, AGP card inserted correctly into the AGP slot, et cetera) and are all cable connections made (multiple power cables to the motherboard, one power cable plus one data cable to each hard disk, etcetera)? Following this, you may hook up the machine. It's going to need power, and you will need at least a keyboard and a monitor attached. And if you want to use a Graphic User Interface to install, a mouse is required also. When you've ensured that everything is safe, you can turn on the machine, and continue to check it: * do all fans start to run when you turn on the machine? (if not, then '''quickly''' turn off your machine and correct the problem!) * does/do the hard disk(s) spin up? * do the power button and reset button operate correctly? * are the power led, HDD led and other display gadgetry functional? * when you let the machine power up, does it emit a single beep? And does it then show a Power-On Self Test screen (POST)? * Does it show the correct amount of memory in the POST screen? The correct number & speed of the CPU(s)? * Does the machine recognise all controller cards (SCSI, S-ATA etc)? And all attached DVD-drives and hard disks? * are all BIOSes/firmwares up to date? * does the machine attempt to boot from at least the hard disk? ...et cetera. If there is any problem, or you want to update the BIOS or firmwares, it's best to do it before the operating system is installed. This Wiki, however, is not the place (yet) to get the information on how to accomplish these type of tasks. The last step in the preparation of the hardware, is to ensure that the machine can boot from CD/DVD, so that you can start installing Debian from it. It is possible to install Debian over the network, but that requires setting up a [http://www.debian-administration.org/articles/478 PXE Boot server] which is (currently) outside the scope of this wiki. By now the system should be all ready to receive it's Operating System. ==Partitioning== This is a tricky subject, but we have put together a recommended standard partitioning scheme. The basis is this: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Partition !style="background:#ffdead;"|MD !style="background:#ffdead;"|LVG !style="background:#ffdead;"|LV-name !style="background:#ffdead;"|Size <br> (physical machine) !style="background:#ffdead;"|Size (VM) !style="background:#ffdead;"|File System !style="background:#ffdead;"|Mount point |- | 1 | /dev/md0 | &nbsp; | &nbsp; | 100MiB | 100MiB | ext3 | /boot |- | 2 | /dev/md1 | &nbsp; | &nbsp; | 3GiB | 1GiB | ext3 | / |- | rowspan="7" valign="top" | 3 | rowspan="7" valign="top" | /dev/md2 | rowspan="7" valign="top" style="background:lightgrey"| system | style="background:lightgrey" | swap | 1GiB<ref name="swap">Rule of thumb: twice the size of the machine's RAM, but no less than 256MiB and no more than 2GiB</ref> | 256MiB<ref name="swap"/> | swap | &nbsp; |- | style="background:lightgrey" | var | 2GiB | 1GiB | ext3 | /var |- | style="background:lightgrey" | appslog | 3GiB | - | ext3 | /var/appslog |- | style="background:lightgrey" | home | 1GiB<ref name="home">Note that this heavily depends on the purpose of the machine; if it is not to house any users, then (almost) no space is needed for /home. But on the other hand if e.g. a virtual user is to be used for keeping mailstores, or other service users need home space, then /home needs to be big enough for that.</ref> | 512MiB<ref name="home"/> | ext3 | /home |- | style="background:lightgrey" | usr | 3GiB | 3GiB | ext3 | /usr |- | style="background:lightgrey" | tmp | 1GiB | 512MiB | ext3 | /tmp |- | style="background:lightgrey" | opt | 1GiB | - | ext3 | /opt |- ! colspan="4" style="text-align:right"| Total ! 18.1GiB ! 6.9GiB ! colspan="2" | |- |} <references/> ba84ba0928b32f919687ebc09853030676a9b8e0 1422 1421 2008-04-27T20:18:12Z 212.238.151.172 0 wikitext text/x-wiki <big>'''Debian Etch Base Server setup'''</big> ==Getting the hardware== {| class="wikitable" border="1" |- |Note: in the following we're assuming you'll be assembling an x86 or x64 type of machine, as it has about the best price/performance ratio you could wish. Hardware costs for other platforms, e.g. IBM's Series p or HP 9000, can be much higher, while platforms like ARM are just not very powerful. Also, the availability of components and of help can be less than with the ubiquietous x86/x64 platforms. |} Naturally, before we can begin to install the operating system, we need to obtain the necessary hardware. Which hardware you require depends on what you want the server for; a testserver on which you will test only a single feature for a short while does not need the same quality of hardware as does a server that's supposed to act as a homeserver for many tasks for a long time. We'll assume your server will be like ours: a home server that must perform many tasks with sufficient performance for a few users, that's reliable and will last for a couple of years. So build or obtain a server with at least the following hardware: * a spacious casing with big, quiet cooling fans, like the [http://www.coolermaster.com/products/product.php?act=detail&id=317 one we have]; * an efficient, heavy-duty power supply that's rated high enough for your devices, and has a decent efficiency. For example, a [http://www.corsair.com/products/power_supplies.aspx Corsair HX520] power supply; * a server class motherboard, e.g. an [http://www.intel.com/products/server/index.htm?iid=home+hdr_nav2_server Intel] or [http://uk.asus.com/products.aspx?l1=9&l2=39&l3=263 AMD] based single-processor motherboard. DO NOT go for the cheapest motherboard you can find: if you pay peanuts, that's what you get. Server class motherboards have the quality, stability and durability you'll need from it, and usually also most of the needed peripherals, like multiple ethernet network cards on-board. Usually a Linux server doesn not require much in the way of video performance (and the screen will be used rarely, if ever), so any old integrated graphics will do. * a matching CPU - or multiple, if you think you need the power and the selected motherboard has the sockets. * a CD-ROM- or DVD-player * ''multiple'' harddisks - you'll want redundancy, because every harddisk fails at some time. The drive with your data on it will fail fatally when it is most inconvenient to you, and any data on it that you consider valuable will likely be lost forever. To make Murphy's work somewhat harder for him, we're going to store our data redundantly, so that if any drive in the server fails, we'll not lose our data or our server. Thus, get yourself at least two harddisks for your operating system, at least 40GiB in size (don't think you'll be able to buy smaller ones nowadays), and spanking new (NEVER use old harddisks for your production server, new ones are just too cheap to run that risk!). * (multipe) network card(s) (NICs) if your motherboard does not have enough NICs integrated on-board. You'll want a NIC for your network, and another one for your Internet connection; and possible a third one for the wireless segment of your network. Now build a machine out of the above, or have someone build it for you. ==Preparation of the hardware== (Note: in the following we're again assuming you're running an x86/x64 type of machine. Hardware requirements and preparation for other platforms, e.g. IBM's Series p or HP 9000, can differ significantly) Next, check the assembled hardware: * is the configuration complete? * are all components connected properly (memory DIMMs seated correctly in their sockets, AGP card inserted correctly into the AGP slot, et cetera) and are all cable connections made (multiple power cables to the motherboard, one power cable plus one data cable to each hard disk, etcetera)? Following this, you may hook up the machine. It's going to need power, and you will need at least a keyboard and a monitor attached. And if you want to use a Graphic User Interface to install, a mouse is required also. When you've ensured that everything is safe, you can turn on the machine, and continue to check it: * do all fans start to run when you turn on the machine? (if not, then '''quickly''' turn off your machine and correct the problem!) * does/do the hard disk(s) spin up? * do the power button and reset button operate correctly? * are the power led, HDD led and other display gadgetry functional? * when you let the machine power up, does it emit a single beep? And does it then show a Power-On Self Test screen (POST)? * Does it show the correct amount of memory in the POST screen? The correct number & speed of the CPU(s)? * Does the machine recognise all controller cards (SCSI, S-ATA etc)? And all attached DVD-drives and hard disks? * are all BIOSes/firmwares up to date? * does the machine attempt to boot from at least the hard disk? ...et cetera. If there is any problem, or you want to update the BIOS or firmwares, it's best to do it before the operating system is installed. This Wiki, however, is not the place (yet) to get the information on how to accomplish these type of tasks. The last step in the preparation of the hardware, is to ensure that the machine can boot from CD/DVD, so that you can start installing Debian from it. It is possible to install Debian over the network, but that requires setting up a [http://www.debian-administration.org/articles/478 PXE Boot server] which is (currently) outside the scope of this wiki. By now the system should be all ready to receive it's Operating System. ==Partitioning== This is a tricky subject, but we have put together a recommended standard partitioning scheme. The basis is this: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Partition !style="background:#ffdead;"|MD !style="background:#ffdead;"|LVG !style="background:#ffdead;"|LV-name !style="background:#ffdead;"|Size <br> (physical machine) !style="background:#ffdead;"|Size (VM) !style="background:#ffdead;"|File System !style="background:#ffdead;"|Mount point |- | 1 | /dev/md0 | &nbsp; | &nbsp; | 100MiB | 100MiB | ext3 | /boot |- | 2 | /dev/md1 | &nbsp; | &nbsp; | 3GiB | 1GiB | ext3 | / |- | rowspan="7" valign="top" | 3 | rowspan="7" valign="top" | /dev/md2 | rowspan="7" valign="top" style="background:lightgrey"| system | style="background:lightgrey" | swap | 1GiB<ref name="swap">Rule of thumb: twice the size of the machine's RAM, but no less than 256MiB and no more than 2GiB</ref> | 256MiB<ref name="swap"/> | swap | &nbsp; |- | style="background:lightgrey" | var | 2GiB | 1GiB | ext3 | /var |- | style="background:lightgrey" | appslog | 3GiB | - | ext3 | /var/appslog |- | style="background:lightgrey" | home | 1GiB<ref name="home">Note that this heavily depends on the purpose of the machine; if it is not to house any users, then (almost) no space is needed for /home. But on the other hand if e.g. a virtual user is to be used for keeping mailstores, or other service users need home space, then /home needs to be big enough for that.</ref> | 512MiB<ref name="home"/> | ext3 | /home |- | style="background:lightgrey" | usr | 3GiB | 3GiB | ext3 | /usr |- | style="background:lightgrey" | tmp | 1GiB | 512MiB | ext3 | /tmp |- | style="background:lightgrey" | opt | 1GiB | - | ext3 | /opt |- ! colspan="4" style="text-align:right"| Total ! 18.1GiB ! 6.9GiB ! colspan="2" | |- |} <references/> 577f5acb99d7ab3c93bbb268ffd9f01b9c68dd00 1423 1422 2008-04-27T21:48:30Z Saruman! 2 /* Preparation of the hardware */ remark on external DVD added wikitext text/x-wiki <big>'''Debian Etch Base Server setup'''</big> ==Getting the hardware== {| class="wikitable" border="1" |- |Note: in the following we're assuming you'll be assembling an x86 or x64 type of machine, as it has about the best price/performance ratio you could wish. Hardware costs for other platforms, e.g. IBM's Series p or HP 9000, can be much higher, while platforms like ARM are just not very powerful. Also, the availability of components and of help can be less than with the ubiquietous x86/x64 platforms. |} Naturally, before we can begin to install the operating system, we need to obtain the necessary hardware. Which hardware you require depends on what you want the server for; a testserver on which you will test only a single feature for a short while does not need the same quality of hardware as does a server that's supposed to act as a homeserver for many tasks for a long time. We'll assume your server will be like ours: a home server that must perform many tasks with sufficient performance for a few users, that's reliable and will last for a couple of years. So build or obtain a server with at least the following hardware: * a spacious casing with big, quiet cooling fans, like the [http://www.coolermaster.com/products/product.php?act=detail&id=317 one we have]; * an efficient, heavy-duty power supply that's rated high enough for your devices, and has a decent efficiency. For example, a [http://www.corsair.com/products/power_supplies.aspx Corsair HX520] power supply; * a server class motherboard, e.g. an [http://www.intel.com/products/server/index.htm?iid=home+hdr_nav2_server Intel] or [http://uk.asus.com/products.aspx?l1=9&l2=39&l3=263 AMD] based single-processor motherboard. DO NOT go for the cheapest motherboard you can find: if you pay peanuts, that's what you get. Server class motherboards have the quality, stability and durability you'll need from it, and usually also most of the needed peripherals, like multiple ethernet network cards on-board. Usually a Linux server doesn not require much in the way of video performance (and the screen will be used rarely, if ever), so any old integrated graphics will do. * a matching CPU - or multiple, if you think you need the power and the selected motherboard has the sockets. * a CD-ROM- or DVD-player * ''multiple'' harddisks - you'll want redundancy, because every harddisk fails at some time. The drive with your data on it will fail fatally when it is most inconvenient to you, and any data on it that you consider valuable will likely be lost forever. To make Murphy's work somewhat harder for him, we're going to store our data redundantly, so that if any drive in the server fails, we'll not lose our data or our server. Thus, get yourself at least two harddisks for your operating system, at least 40GiB in size (don't think you'll be able to buy smaller ones nowadays), and spanking new (NEVER use old harddisks for your production server, new ones are just too cheap to run that risk!). * (multipe) network card(s) (NICs) if your motherboard does not have enough NICs integrated on-board. You'll want a NIC for your network, and another one for your Internet connection; and possible a third one for the wireless segment of your network. Now build a machine out of the above, or have someone build it for you. ==Preparation of the hardware== (Note: in the following we're again assuming you're running an x86/x64 type of machine. Hardware requirements and preparation for other platforms, e.g. IBM's Series p or HP 9000, can differ significantly) Next, check the assembled hardware: * is the configuration complete? If it does not have a CD/DVDplayer from which it can boot, then installing the software gets more difficult - at least get an USB external DVDdrive or something like that. * are all components connected properly (memory DIMMs seated correctly in their sockets, AGP card inserted correctly into the AGP slot, et cetera) and are all cable connections made (multiple power cables to the motherboard, one power cable plus one data cable to each hard disk, etcetera)? Following this, you may hook up the machine. It's going to need power, and you will need at least a keyboard and a monitor attached. And if you want to use a Graphic User Interface to install, a mouse is required also. When you've ensured that everything is safe, you can turn on the machine, and continue to check it: * do all fans start to run when you turn on the machine? (if not, then '''quickly''' turn off your machine and correct the problem!) * does/do the hard disk(s) spin up? * do the power button and reset button operate correctly? * are the power led, HDD led and other display gadgetry functional? * when you let the machine power up, does it emit a single beep? And does it then show a Power-On Self Test screen (POST)? * Does it show the correct amount of memory in the POST screen? The correct number & speed of the CPU(s)? * Does the machine recognise all controller cards (SCSI, S-ATA etc)? And all attached DVD-drives and hard disks? * are all BIOSes/firmwares up to date? * does the machine attempt to boot from at least the hard disk? ...et cetera. If there is any problem, or you want to update the BIOS or firmwares, it's best to do it before the operating system is installed. This Wiki, however, is not the place (yet) to get the information on how to accomplish these type of tasks. The last step in the preparation of the hardware, is to ensure that the machine can boot from CD/DVD, so that you can start installing Debian from it. It is possible to install Debian over the network, but that requires setting up a [http://www.debian-administration.org/articles/478 PXE Boot server] which is (currently) outside the scope of this wiki. By now the system should be all ready to receive it's Operating System. ==Partitioning== This is a tricky subject, but we have put together a recommended standard partitioning scheme. The basis is this: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Partition !style="background:#ffdead;"|MD !style="background:#ffdead;"|LVG !style="background:#ffdead;"|LV-name !style="background:#ffdead;"|Size <br> (physical machine) !style="background:#ffdead;"|Size (VM) !style="background:#ffdead;"|File System !style="background:#ffdead;"|Mount point |- | 1 | /dev/md0 | &nbsp; | &nbsp; | 100MiB | 100MiB | ext3 | /boot |- | 2 | /dev/md1 | &nbsp; | &nbsp; | 3GiB | 1GiB | ext3 | / |- | rowspan="7" valign="top" | 3 | rowspan="7" valign="top" | /dev/md2 | rowspan="7" valign="top" style="background:lightgrey"| system | style="background:lightgrey" | swap | 1GiB<ref name="swap">Rule of thumb: twice the size of the machine's RAM, but no less than 256MiB and no more than 2GiB</ref> | 256MiB<ref name="swap"/> | swap | &nbsp; |- | style="background:lightgrey" | var | 2GiB | 1GiB | ext3 | /var |- | style="background:lightgrey" | appslog | 3GiB | - | ext3 | /var/appslog |- | style="background:lightgrey" | home | 1GiB<ref name="home">Note that this heavily depends on the purpose of the machine; if it is not to house any users, then (almost) no space is needed for /home. But on the other hand if e.g. a virtual user is to be used for keeping mailstores, or other service users need home space, then /home needs to be big enough for that.</ref> | 512MiB<ref name="home"/> | ext3 | /home |- | style="background:lightgrey" | usr | 3GiB | 3GiB | ext3 | /usr |- | style="background:lightgrey" | tmp | 1GiB | 512MiB | ext3 | /tmp |- | style="background:lightgrey" | opt | 1GiB | - | ext3 | /opt |- ! colspan="4" style="text-align:right"| Total ! 18.1GiB ! 6.9GiB ! colspan="2" | |- |} <references/> ba97ff5fb7bcdf56baa4492ec7b1d11f6ab56945 1424 1423 2008-04-28T16:23:36Z Saruman! 2 First step of installation is added wikitext text/x-wiki <big>'''Debian Etch Base Server setup'''</big> ==Getting the hardware== {| class="wikitable" border="1" |- |Note: in the following we're assuming you'll be assembling an x86 or x64 type of machine, as it has about the best price/performance ratio you could wish. Hardware costs for other platforms, e.g. IBM's Series p or HP 9000, can be much higher, while platforms like ARM are just not very powerful. Also, the availability of components and of help can be less than with the ubiquietous x86/x64 platforms. |} Naturally, before we can begin to install the operating system, we need to obtain the necessary hardware. Which hardware you require depends on what you want the server for; a testserver on which you will test only a single feature for a short while does not need the same quality of hardware as does a server that's supposed to act as a homeserver for many tasks for a long time. We'll assume your server will be like ours: a home server that must perform many tasks with sufficient performance for a few users, that's reliable and will last for a couple of years. So build or obtain a server with at least the following hardware: * a spacious casing with big, quiet cooling fans, like the [http://www.coolermaster.com/products/product.php?act=detail&id=317 one we have]; * an efficient, heavy-duty power supply that's rated high enough for your devices, and has a decent efficiency. For example, a [http://www.corsair.com/products/power_supplies.aspx Corsair HX520] power supply; * a server class motherboard, e.g. an [http://www.intel.com/products/server/index.htm?iid=home+hdr_nav2_server Intel] or [http://uk.asus.com/products.aspx?l1=9&l2=39&l3=263 AMD] based single-processor motherboard. DO NOT go for the cheapest motherboard you can find: if you pay peanuts, that's what you get. Server class motherboards have the quality, stability and durability you'll need from it, and usually also most of the needed peripherals, like multiple ethernet network cards on-board. Usually a Linux server doesn not require much in the way of video performance (and the screen will be used rarely, if ever), so any old integrated graphics will do. * a matching CPU - or multiple, if you think you need the power and the selected motherboard has the sockets. * a CD-ROM- or DVD-player * ''multiple'' harddisks - you'll want redundancy, because every harddisk fails at some time. The drive with your data on it will fail fatally when it is most inconvenient to you, and any data on it that you consider valuable will likely be lost forever. To make Murphy's work somewhat harder for him, we're going to store our data redundantly, so that if any drive in the server fails, we'll not lose our data or our server. Thus, get yourself at least two harddisks for your operating system, at least 40GiB in size (don't think you'll be able to buy smaller ones nowadays), and spanking new (NEVER use old harddisks for your production server, new ones are just too cheap to run that risk!). * (multipe) network card(s) (NICs) if your motherboard does not have enough NICs integrated on-board. You'll want a NIC for your network, and another one for your Internet connection; and possible a third one for the wireless segment of your network. Now build a machine out of the above, or have someone build it for you. ==Preparation of the hardware== (Note: in the following we're again assuming you're running an x86/x64 type of machine. Hardware requirements and preparation for other platforms, e.g. IBM's Series p or HP 9000, can differ significantly) Next, check the assembled hardware: * is the configuration complete? If it does not have a CD/DVDplayer from which it can boot, then installing the software gets more difficult - at least get an USB external DVDdrive or something like that. * are all components connected properly (memory DIMMs seated correctly in their sockets, AGP card inserted correctly into the AGP slot, et cetera) and are all cable connections made (multiple power cables to the motherboard, one power cable plus one data cable to each hard disk, etcetera)? Following this, you may hook up the machine. It's going to need power, and you will need at least a keyboard and a monitor attached. And if you want to use a Graphic User Interface to install, a mouse is required also. When you've ensured that everything is safe, you can turn on the machine, and continue to check it: * do all fans start to run when you turn on the machine? (if not, then '''quickly''' turn off your machine and correct the problem!) * does/do the hard disk(s) spin up? * do the power button and reset button operate correctly? * are the power led, HDD led and other display gadgetry functional? * when you let the machine power up, does it emit a single beep? And does it then show a Power-On Self Test screen (POST)? * Does it show the correct amount of memory in the POST screen? The correct number & speed of the CPU(s)? * Does the machine recognise all controller cards (SCSI, S-ATA etc)? And all attached DVD-drives and hard disks? * are all BIOSes/firmwares up to date? * If you have a hardware RAID controller, are your RAID arrays built already? * does the machine attempt to boot from at least the hard disk? ...et cetera. If there is any problem, or you want to update the BIOS or firmwares, it's best to do it before the operating system is installed. This Wiki, however, is not the place (yet) to get the information on how to accomplish these type of tasks. The last steps in the preparation of the hardware, are * to ensure that the machine can boot from CD/DVD, so that you can start installing Debian from it. It is possible to install Debian over the network, but that requires setting up a [http://www.debian-administration.org/articles/478 PXE Boot server] which is (currently) outside the scope of this wiki. * to connect the hardware to the Internet, so that it can get all required updates etcetera; please do ''not'' connect the box ''straight'' to the Internet, but make sure that it's safely behind a firewall, or failing that, a NAT router. By now the system should be all ready to receive it's Operating System. ==Operating System installation== To install an Operating System (OS), it's kinda instrumental that you have one. Here, we're going to use [http://www.debian.org/intro/about Debian], the biggest [http://www.debian.org/intro/about#free Free] OS that we know of. Free stands for Freedom, but incidentally that Freedom also means it's gratis, an appealing aspect of Free. To get your own copy of Debian, go to their [http://www.debian.org/distrib/ download site] and obtain the latest [http://www.debian.org/releases/ Stable] image - in this wiki it's Debian 4.0, or "Etch" as it's also known. Besides the choice which release of Debian you want to run, you also have to know for which platform you're downloading (in our case: either ''amd64'' or ''i386'' depending on your hardware platform) and what kind of install you wish - if you have a working, fast Internet connection available at the time of install, then we recommend getting the [[http://www.debian.org/CD/netinst/ netinst] CD image; it's a relatively small CD, that'll be able to get you going, but gets most of the software you'll need straight from the 'net at install time. So, since in the example at hand we're installing on a Xeon server on which we wish to install 32-bits software, we'll download [http://cdimage.debian.org/debian-cd/4.0_r3/i386/iso-cd/debian-40r3-i386-netinst.iso debian-40r3-i386-netinst.iso], the latest netinstall image at the time of writing. Burn this to a CD-recordable and boot your prepared hardware platform from this CD. After booting from the CD, a friendly prompt invites you to indicate how you want to boot the CD. Your choices are listed under &lt;F3&gt;; we're going to use the standard Command Line installation, so we type "install"&lt;enter&gt; or just simply &lt;enter&gt;. After the Linux kernel finishes initializing the machine, a simple text-based installer appears that immediately starts asking questions. Answer them according to your needs. Our example system uses the following choices: * Language: english * country: other &gt; Netherlands * keymap: American English (since we have a keyboard with US layout) Some installation software loads, and we get to the next phase: we're required to indicate which of the detected network interface cards (NIC) is going to be the "primary" NIC. {| class="wikitable" border="1" |- |Here, trouble could begin. If your machine has network cards that are '''not''' supported, then you'll see '''no''' cards here - but then how are you going to do a NetInstall? A solution would be to (temporarily) install a NIC that ''is'' supported, like a cheap Realtek card, or an old 3Com 905 card. Then, when the whole system is installed, up and running, you could compile a new kernel that contains support for your actual NICs, and when these work, remove the temporary NIC. For now, we'll assume your NICs are recognised properly by the Debian installation routine. |} Select the card that's connected to the Internet (again: it should ''not'' be connected straight to the wild wild web, but sit safely behind a firewall, at least until we've installed our own firewall); let's assume that this NIC is designated ''eth0'' by the Debian installation. This card will now be configured using DHCP, so if you're on a network with a DHCP-server, the network will work straight away. If it's not, you can either configure the network manually or fix your DHCP-server and connection between it and ''eth0''. Next is one of the hardest questions that any OS installation is going to ask you: what will be the host name of the system? You could change it at any time in the future, but with lots of hassle, so you better choose wisely. Here are our tips: * do '''not''' name your machine after the user that's going to use it, e.g. "bernie-pc" (at some time in the future, Bernie's machine will be moved to Alice, so then Alice is working on "bernie-pc" which makes the situation quite unclear); * do '''not''' name your machine after the department or workgroup that's using it most, e.g. "accounting-srv" (same reasoning); * do '''not''' name your machine after it's main function, e.g. "printserver" (at some time in the future, the main function is moved to another machine, and/or an alternative function will become the main function of the machine); * do '''not''' name your machine after it's location, e.g. "srv-boston" (at some time in the future, the box will be moved to another location); * do '''not''' name your machine after it's hardware configuration, e.g. "ibmx346" (at some time in the future, either another xSeries x346 will be wheeled in, or the machine will be upgraded to accomodate increased use or overcome hardware problems - your "ibmx346" could suddenly be running on an xSeries x3650). What we feel are safe names for ''any'' machine in your network are true names, perhaps linked to a common theme: names of European cities, names of movie characters, names of countries or holiday destinations et cetera. Immediately following comes the question of the Domain Name. This is about a DNS domain, so effectively the installation program is asking which DNS suffix the host name should have; if the DHCP-server already provided something it'll be suggested, but you can override it. Here is our tip: * do '''not''' use a publicly registered domain name (e.g. "cocacola.com") for a machine that's not primarily intended to serve the public on the Internet; * for machines serving a private network, we urge you to use Top Level Domain name "lan" (to signify your machine is on a Local Area Network or LAN) * for the Domain Name, we suggest you use a level 2 name, like "saruman.lan" At any rate, this section has most likely showed you that you need to put some thought into the DNS Domain Name design of your home network. ==Partitioning== Next comes the question of partitioning, or how to divide the available disk space into chunks for the server to use. This is a tricky subject, because if you put all storage space into one partition, then some day a runaway process will fill up the entire disk with useless logs, and the system will crash. On the other hand, if you divvy up all space into little chunks, then some application is going to need space in one of those partitions where there is none, even though there may be plenty in other partitions. To prevent both problems from occuring, we're going to use [http://tldp.org/HOWTO/LVM-HOWTO/whatisvolman.html Logical Volume Management (LVM)] so that we can provision enough space to start our server, but keep some space in reserve to apply when needed, where it'll be needed. So, we have put together a recommended standard partitioning scheme. The basis is this: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Partition !style="background:#ffdead;"|MD !style="background:#ffdead;"|LVG !style="background:#ffdead;"|LV-name !style="background:#ffdead;"|Size <br> (physical machine) !style="background:#ffdead;"|Size (VM) !style="background:#ffdead;"|File System !style="background:#ffdead;"|Mount point |- | 1 | /dev/md0 | &nbsp; | &nbsp; | 100MiB | 100MiB | ext3 | /boot |- | 2 | /dev/md1 | &nbsp; | &nbsp; | 3GiB | 1GiB | ext3 | / |- | rowspan="7" valign="top" | 3 | rowspan="7" valign="top" | /dev/md2 | rowspan="7" valign="top" style="background:lightgrey"| system | style="background:lightgrey" | swap | 1GiB<ref name="swap">Rule of thumb: twice the size of the machine's RAM, but no less than 256MiB and no more than 2GiB</ref> | 256MiB<ref name="swap"/> | swap | &nbsp; |- | style="background:lightgrey" | var | 2GiB | 1GiB | ext3 | /var |- | style="background:lightgrey" | appslog | 3GiB | - | ext3 | /var/appslog |- | style="background:lightgrey" | home | 1GiB<ref name="home">Note that this heavily depends on the purpose of the machine; if it is not to house any users, then (almost) no space is needed for /home. But on the other hand if e.g. a virtual user is to be used for keeping mailstores, or other service users need home space, then /home needs to be big enough for that.</ref> | 512MiB<ref name="home"/> | ext3 | /home |- | style="background:lightgrey" | usr | 3GiB | 3GiB | ext3 | /usr |- | style="background:lightgrey" | tmp | 1GiB | 512MiB | ext3 | /tmp |- | style="background:lightgrey" | opt | 1GiB | - | ext3 | /opt |- ! colspan="4" style="text-align:right"| Total ! 18.1GiB ! 6.9GiB ! colspan="2" | |- |} <references/> e5cb9f6baa94d9cc828975277f4a2e96e00c22f9 1426 1424 2008-04-28T17:19:21Z Saruman! 2 put in a pointer to RAID wikitext text/x-wiki <big>'''Debian Etch Base Server setup'''</big> ==Getting the hardware== {| class="wikitable" border="1" |- |Note: in the following we're assuming you'll be assembling an x86 or x64 type of machine, as it has about the best price/performance ratio you could wish. Hardware costs for other platforms, e.g. IBM's Series p or HP 9000, can be much higher, while platforms like ARM are just not very powerful. Also, the availability of components and of help can be less than with the ubiquietous x86/x64 platforms. |} Naturally, before we can begin to install the operating system, we need to obtain the necessary hardware. Which hardware you require depends on what you want the server for; a testserver on which you will test only a single feature for a short while does not need the same quality of hardware as does a server that's supposed to act as a homeserver for many tasks for a long time. We'll assume your server will be like ours: a home server that must perform many tasks with sufficient performance for a few users, that's reliable and will last for a couple of years. So build or obtain a server with at least the following hardware: * a spacious casing with big, quiet cooling fans, like the [http://www.coolermaster.com/products/product.php?act=detail&id=317 one we have]; * an efficient, heavy-duty power supply that's rated high enough for your devices, and has a decent efficiency. For example, a [http://www.corsair.com/products/power_supplies.aspx Corsair HX520] power supply; * a server class motherboard, e.g. an [http://www.intel.com/products/server/index.htm?iid=home+hdr_nav2_server Intel] or [http://uk.asus.com/products.aspx?l1=9&l2=39&l3=263 AMD] based single-processor motherboard. DO NOT go for the cheapest motherboard you can find: if you pay peanuts, that's what you get. Server class motherboards have the quality, stability and durability you'll need from it, and usually also most of the needed peripherals, like multiple ethernet network cards on-board. Usually a Linux server doesn not require much in the way of video performance (and the screen will be used rarely, if ever), so any old integrated graphics will do. * a matching CPU - or multiple, if you think you need the power and the selected motherboard has the sockets. * a CD-ROM- or DVD-player * ''multiple'' harddisks - you'll want redundancy, because every harddisk fails at some time. The drive with your data on it will fail fatally when it is most inconvenient to you, and any data on it that you consider valuable will likely be lost forever. To make Murphy's work somewhat harder for him, we're going to store our data redundantly, so that if any drive in the server fails, we'll not lose our data or our server. Thus, get yourself at least two harddisks for your operating system, at least 40GiB in size (don't think you'll be able to buy smaller ones nowadays), and spanking new (NEVER use old harddisks for your production server, new ones are just too cheap to run that risk!). * (multipe) network card(s) (NICs) if your motherboard does not have enough NICs integrated on-board. You'll want a NIC for your network, and another one for your Internet connection; and possible a third one for the wireless segment of your network. Now build a machine out of the above, or have someone build it for you. ==Preparation of the hardware== (Note: in the following we're again assuming you're running an x86/x64 type of machine. Hardware requirements and preparation for other platforms, e.g. IBM's Series p or HP 9000, can differ significantly) Next, check the assembled hardware: * is the configuration complete? If it does not have a CD/DVDplayer from which it can boot, then installing the software gets more difficult - at least get an USB external DVDdrive or something like that. * are all components connected properly (memory DIMMs seated correctly in their sockets, AGP card inserted correctly into the AGP slot, et cetera) and are all cable connections made (multiple power cables to the motherboard, one power cable plus one data cable to each hard disk, etcetera)? Following this, you may hook up the machine. It's going to need power, and you will need at least a keyboard and a monitor attached. And if you want to use a Graphic User Interface to install, a mouse is required also. When you've ensured that everything is safe, you can turn on the machine, and continue to check it: * do all fans start to run when you turn on the machine? (if not, then '''quickly''' turn off your machine and correct the problem!) * does/do the hard disk(s) spin up? * do the power button and reset button operate correctly? * are the power led, HDD led and other display gadgetry functional? * when you let the machine power up, does it emit a single beep? And does it then show a Power-On Self Test screen (POST)? * Does it show the correct amount of memory in the POST screen? The correct number & speed of the CPU(s)? * Does the machine recognise all controller cards (SCSI, S-ATA etc)? And all attached DVD-drives and hard disks? * are all BIOSes/firmwares up to date? * If you have a hardware RAID controller, are your RAID arrays built already? * does the machine attempt to boot from at least the hard disk? ...et cetera. If there is any problem, or you want to update the BIOS or firmwares, it's best to do it before the operating system is installed. This Wiki, however, is not the place (yet) to get the information on how to accomplish these type of tasks. The last steps in the preparation of the hardware, are * to ensure that the machine can boot from CD/DVD, so that you can start installing Debian from it. It is possible to install Debian over the network, but that requires setting up a [http://www.debian-administration.org/articles/478 PXE Boot server] which is (currently) outside the scope of this wiki. * to connect the hardware to the Internet, so that it can get all required updates etcetera; please do ''not'' connect the box ''straight'' to the Internet, but make sure that it's safely behind a firewall, or failing that, a NAT router. By now the system should be all ready to receive it's Operating System. ==Operating System installation== To install an Operating System (OS), it's kinda instrumental that you have one. Here, we're going to use [http://www.debian.org/intro/about Debian], the biggest [http://www.debian.org/intro/about#free Free] OS that we know of. Free stands for Freedom, but incidentally that Freedom also means it's gratis, an appealing aspect of Free. To get your own copy of Debian, go to their [http://www.debian.org/distrib/ download site] and obtain the latest [http://www.debian.org/releases/ Stable] image - in this wiki it's Debian 4.0, or "Etch" as it's also known. Besides the choice which release of Debian you want to run, you also have to know for which platform you're downloading (in our case: either ''amd64'' or ''i386'' depending on your hardware platform) and what kind of install you wish - if you have a working, fast Internet connection available at the time of install, then we recommend getting the [[http://www.debian.org/CD/netinst/ netinst] CD image; it's a relatively small CD, that'll be able to get you going, but gets most of the software you'll need straight from the 'net at install time. So, since in the example at hand we're installing on a Xeon server on which we wish to install 32-bits software, we'll download [http://cdimage.debian.org/debian-cd/4.0_r3/i386/iso-cd/debian-40r3-i386-netinst.iso debian-40r3-i386-netinst.iso], the latest netinstall image at the time of writing. Burn this to a CD-recordable and boot your prepared hardware platform from this CD. After booting from the CD, a friendly prompt invites you to indicate how you want to boot the CD. Your choices are listed under &lt;F3&gt;; we're going to use the standard Command Line installation, so we type "install"&lt;enter&gt; or just simply &lt;enter&gt;. After the Linux kernel finishes initializing the machine, a simple text-based installer appears that immediately starts asking questions. Answer them according to your needs. Our example system uses the following choices: * Language: english * country: other &gt; Netherlands * keymap: American English (since we have a keyboard with US layout) Some installation software loads, and we get to the next phase: we're required to indicate which of the detected network interface cards (NIC) is going to be the "primary" NIC. {| class="wikitable" border="1" |- |Here, trouble could begin. If your machine has network cards that are '''not''' supported, then you'll see '''no''' cards here - but then how are you going to do a NetInstall? A solution would be to (temporarily) install a NIC that ''is'' supported, like a cheap Realtek card, or an old 3Com 905 card. Then, when the whole system is installed, up and running, you could compile a new kernel that contains support for your actual NICs, and when these work, remove the temporary NIC. For now, we'll assume your NICs are recognised properly by the Debian installation routine. |} Select the card that's connected to the Internet (again: it should ''not'' be connected straight to the wild wild web, but sit safely behind a firewall, at least until we've installed our own firewall); let's assume that this NIC is designated ''eth0'' by the Debian installation. This card will now be configured using DHCP, so if you're on a network with a DHCP-server, the network will work straight away. If it's not, you can either configure the network manually or fix your DHCP-server and connection between it and ''eth0''. Next is one of the hardest questions that any OS installation is going to ask you: what will be the host name of the system? You could change it at any time in the future, but with lots of hassle, so you better choose wisely. Here are our tips: * do '''not''' name your machine after the user that's going to use it, e.g. "bernie-pc" (at some time in the future, Bernie's machine will be moved to Alice, so then Alice is working on "bernie-pc" which makes the situation quite unclear); * do '''not''' name your machine after the department or workgroup that's using it most, e.g. "accounting-srv" (same reasoning); * do '''not''' name your machine after it's main function, e.g. "printserver" (at some time in the future, the main function is moved to another machine, and/or an alternative function will become the main function of the machine); * do '''not''' name your machine after it's location, e.g. "srv-boston" (at some time in the future, the box will be moved to another location); * do '''not''' name your machine after it's hardware configuration, e.g. "ibmx346" (at some time in the future, either another xSeries x346 will be wheeled in, or the machine will be upgraded to accomodate increased use or overcome hardware problems - your "ibmx346" could suddenly be running on an xSeries x3650). What we feel are safe names for ''any'' machine in your network are true names, perhaps linked to a common theme: names of European cities, names of movie characters, names of countries or holiday destinations et cetera. Immediately following comes the question of the Domain Name. This is about a DNS domain, so effectively the installation program is asking which DNS suffix the host name should have; if the DHCP-server already provided something it'll be suggested, but you can override it. Here is our tip: * do '''not''' use a publicly registered domain name (e.g. "cocacola.com") for a machine that's not primarily intended to serve the public on the Internet; * for machines serving a private network, we urge you to use Top Level Domain name "lan" (to signify your machine is on a Local Area Network or LAN) * for the Domain Name, we suggest you use a level 2 name, like "saruman.lan" At any rate, this section has most likely showed you that you need to put some thought into the DNS Domain Name design of your home network. ==Software or hardware RAID== But first we have an issue to tackle: that of redundancy. Your hard disks will fail. They absolutely will. It is never a question of "if", only of "when". So what will you do when the hard disk containing your complete operating system fails (besides pulling your hair out, that is)? What we propose is this: hard disks are pretty cheap nowadays, so let's use [http://en.wikipedia.org/wiki/Redundant_array_of_independent_disks RAID technology] to make our hard drive space resilient against failure of a whole drive. So first make sure that you have ''two'' disks of equal size instead of only one. Had you been planning to use multiple disks already, then make sure you have at least ''one'' disk more than your space requirements prescribe; the space on that extra drive will provide the needed redundancy. Next, [[RAID fundamentals under Linux | click here]] to learn a bit more about RAID, to make the decision to use hardware-based and/or software-based RAID, and to plan your RAID arrays. ==Partitioning== Next comes the question of partitioning, or how to divide the available disk space into chunks for the server to use. This is a tricky subject, because if you put all storage space into one partition, then some day a runaway process will fill up the entire disk with useless logs, and the system will crash. On the other hand, if you divvy up all space into little chunks, then some application is going to need space in one of those partitions where there is none, even though there may be plenty in other partitions. To prevent both problems from occuring, we're going to use [http://tldp.org/HOWTO/LVM-HOWTO/whatisvolman.html Logical Volume Management (LVM)] so that we can provision enough space to start our server, but keep some space in reserve to apply when needed, where it'll be needed. So, we have put together a recommended standard partitioning scheme. The basis is this: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Partition !style="background:#ffdead;"|MD !style="background:#ffdead;"|LVG !style="background:#ffdead;"|LV-name !style="background:#ffdead;"|Size <br> (physical machine) !style="background:#ffdead;"|Size (VM) !style="background:#ffdead;"|File System !style="background:#ffdead;"|Mount point |- | 1 | /dev/md0 | &nbsp; | &nbsp; | 100MiB | 100MiB | ext3 | /boot |- | 2 | /dev/md1 | &nbsp; | &nbsp; | 3GiB | 1GiB | ext3 | / |- | rowspan="7" valign="top" | 3 | rowspan="7" valign="top" | /dev/md2 | rowspan="7" valign="top" style="background:lightgrey"| system | style="background:lightgrey" | swap | 1GiB<ref name="swap">Rule of thumb: twice the size of the machine's RAM, but no less than 256MiB and no more than 2GiB</ref> | 256MiB<ref name="swap"/> | swap | &nbsp; |- | style="background:lightgrey" | var | 2GiB | 1GiB | ext3 | /var |- | style="background:lightgrey" | appslog | 3GiB | - | ext3 | /var/appslog |- | style="background:lightgrey" | home | 1GiB<ref name="home">Note that this heavily depends on the purpose of the machine; if it is not to house any users, then (almost) no space is needed for /home. But on the other hand if e.g. a virtual user is to be used for keeping mailstores, or other service users need home space, then /home needs to be big enough for that.</ref> | 512MiB<ref name="home"/> | ext3 | /home |- | style="background:lightgrey" | usr | 3GiB | 3GiB | ext3 | /usr |- | style="background:lightgrey" | tmp | 1GiB | 512MiB | ext3 | /tmp |- | style="background:lightgrey" | opt | 1GiB | - | ext3 | /opt |- ! colspan="4" style="text-align:right"| Total ! 18.1GiB ! 6.9GiB ! colspan="2" | |- |} <references/> 6422762008be96617e7686bf4be1b810355a7ba3 1427 1426 2008-05-12T10:46:50Z Saruman! 2 reordering wikitext text/x-wiki <big>'''Debian Etch Base Server setup'''</big> ==Getting the hardware== {| class="wikitable" border="1" |- |Note: in the following we're assuming you'll be assembling an x86 or x64 type of machine, as it has about the best price/performance ratio you could wish. Hardware costs for other platforms, e.g. IBM's Series p or HP 9000, can be much higher, while platforms like ARM are just not very powerful. Also, the availability of components and of help can be less than with the ubiquietous x86/x64 platforms. |} Naturally, before we can begin to install the operating system, we need to obtain the necessary hardware. Which hardware you require depends on what you want the server for; a testserver on which you will test only a single feature for a short while does not need the same quality of hardware as does a server that's supposed to act as a homeserver for many tasks for a long time. We'll assume your server will be like ours: a home server that must perform many tasks with sufficient performance for a few users, that's reliable and will last for a couple of years. So build or obtain a server with at least the following hardware: * a spacious casing with big, quiet cooling fans, like the [http://www.coolermaster.com/products/product.php?act=detail&id=317 one we have]; * an efficient, heavy-duty power supply that's rated high enough for your devices, and has a decent efficiency. For example, a [http://www.corsair.com/products/power_supplies.aspx Corsair HX520] power supply; * a server class motherboard, e.g. an [http://www.intel.com/products/server/index.htm?iid=home+hdr_nav2_server Intel] or [http://uk.asus.com/products.aspx?l1=9&l2=39&l3=263 AMD] based single-processor motherboard. DO NOT go for the cheapest motherboard you can find: if you pay peanuts, that's what you get. Server class motherboards have the quality, stability and durability you'll need from it, and usually also most of the needed peripherals, like multiple ethernet network cards on-board. Usually a Linux server doesn not require much in the way of video performance (and the screen will be used rarely, if ever), so any old integrated graphics will do. * a matching CPU - or multiple, if you think you need the power and the selected motherboard has the sockets. * a CD-ROM- or DVD-player * ''multiple'' harddisks - you'll want redundancy, because every harddisk fails at some time. The drive with your data on it will fail fatally when it is most inconvenient to you, and any data on it that you consider valuable will likely be lost forever. To make Murphy's work somewhat harder for him, we're going to store our data redundantly, so that if any drive in the server fails, we'll not lose our data or our server. Thus, get yourself at least two harddisks for your operating system, at least 40GiB in size (don't think you'll be able to buy smaller ones nowadays), and spanking new (NEVER use old harddisks for your production server, new ones are just too cheap to run that risk!). * (multipe) network card(s) (NICs) if your motherboard does not have enough NICs integrated on-board. You'll want a NIC for your network, and another one for your Internet connection; and possible a third one for the wireless segment of your network. Now build a machine out of the above, or have someone build it for you. ==Preparation of the hardware== (Note: in the following we're again assuming you're running an x86/x64 type of machine. Hardware requirements and preparation for other platforms, e.g. IBM's Series p or HP 9000, can differ significantly) Next, check the assembled hardware: * is the configuration complete? If it does not have a CD/DVDplayer from which it can boot, then installing the software gets more difficult - at least get an USB external DVDdrive or something like that. * are all components connected properly (memory DIMMs seated correctly in their sockets, AGP card inserted correctly into the AGP slot, et cetera) and are all cable connections made (multiple power cables to the motherboard, one power cable plus one data cable to each hard disk, etcetera)? Following this, you may hook up the machine. It's going to need power, and you will need at least a keyboard and a monitor attached. And if you want to use a Graphic User Interface to install, a mouse is required also. When you've ensured that everything is safe, you can turn on the machine, and continue to check it: * do all fans start to run when you turn on the machine? (if not, then '''quickly''' turn off your machine and correct the problem!) * does/do the hard disk(s) spin up? * do the power button and reset button operate correctly? * are the power led, HDD led and other display gadgetry functional? * when you let the machine power up, does it emit a single beep? And does it then show a Power-On Self Test screen (POST)? * Does it show the correct amount of memory in the POST screen? The correct number & speed of the CPU(s)? * Does the machine recognise all controller cards (SCSI, S-ATA etc)? And all attached DVD-drives and hard disks? * are all BIOSes/firmwares up to date? * If you have a hardware RAID controller, are your RAID arrays built already? * does the machine attempt to boot from at least the hard disk? ...et cetera. If there is any problem, or you want to update the BIOS or firmwares, it's best to do it before the operating system is installed. This Wiki, however, is not the place (yet) to get the information on how to accomplish these type of tasks. The last steps in the preparation of the hardware, are * to ensure that the machine can boot from CD/DVD, so that you can start installing Debian from it. It is possible to install Debian over the network, but that requires setting up a [http://www.debian-administration.org/articles/478 PXE Boot server] which is (currently) outside the scope of this wiki. * to connect the hardware to the Internet, so that it can get all required updates etcetera; please do ''not'' connect the box ''straight'' to the Internet, but make sure that it's safely behind a firewall, or failing that, a NAT router. By now the system should be almost ready to receive it's Operating System. But first we have an issue to tackle: that of redundancy. ==Software or hardware RAID== Your hard disks will fail. They absolutely will. It is never a question of "if", only of "when". So what will you do when the hard disk containing your complete operating system fails (besides pulling your hair out, that is)? What we propose is this: hard disks are pretty cheap nowadays, so let's use [http://en.wikipedia.org/wiki/Redundant_array_of_independent_disks RAID technology] to make our hard drive space resilient against failure of a whole drive. So first make sure that you have ''two'' disks of equal size instead of only one. Had you already been planning to use multiple disks already, then make sure you have at least ''one'' disk more than your space requirements prescribe; the space on that extra drive will provide the needed redundancy. Next, [[RAID fundamentals under Linux | click here]] to learn a bit more about RAID, to make the decision to use hardware-based and/or software-based RAID, and to plan your RAID arrays. In this example, we'll assume you're using hardware RAID on a RAID controller that's supported by the Debian installation software. This means that the installation software will "see" your RAID array(s) and present them as usable drives. ==Planning your network names== If your machine must become a part of an existing network, then it's almost certain that you already have a DNS domain in place; in that case: obtain the DNS suffix your machine will get (the DNS domain your machine will "belong" to). However, it's also possible that this machine is going to be the first machine in your new network, in which case the whole issue of DNS suffixes is wide open. If you need more information on DNS, go [[http://www.isc.org/sw/bind/arm95/Bv9ARM-all.html#id2564824 here]]. For now we'll assume you have (or will quickly obtain) a working knowledge of the DNS system. Here is our tip on choosing a DNS domain for your home network: * do '''not''' use a publicly registered domain name (e.g. "cocacola.com") for any machine that's not primarily intended to serve the public on the Internet; * for machines serving a private network, we urge you to use Top Level Domain name "lan" (to signify your machine is on a Local Area Network or LAN) * for the Domain Name itself, we suggest you use a level 2 name, like "saruman.lan", and not a level 3 name, like "mister.saruman.lan". This is only a short section on DNS, but remember that once a proper DNS system is in place, it's pretty much work to change it. At any rate, this section has most likely showed you that you need to put some thought into the DNS Domain Name design of your home network. OK, with this out of the way, we can get to installing the OS. ==Operating System installation== To install an Operating System (OS), it's kinda instrumental that you have one. Here, we're going to use [http://www.debian.org/intro/about Debian], the biggest [http://www.debian.org/intro/about#free Free] OS that we know of. Free stands for Freedom, but incidentally that Freedom also means it's gratis, an appealing aspect of Free. To get your own copy of Debian, go to their [http://www.debian.org/distrib/ download site] and obtain the latest [http://www.debian.org/releases/ Stable] image - in this wiki it's Debian 4.0, or "Etch" as it's also known. Besides the choice which release of Debian you want to run, you also have to know for which platform you're downloading (in our case: either ''amd64'' or ''i386'' depending on your hardware platform) and what kind of install you wish - if you have a working, fast Internet connection available at the time of install, then we recommend getting the [[http://www.debian.org/CD/netinst/ netinst] CD image; it's a relatively small CD, that'll be able to get you going, but gets most of the software you'll need straight from the 'net at install time. So, since in the example at hand we're installing on a Xeon server on which we wish to install 32-bits software, we'll download [http://cdimage.debian.org/debian-cd/4.0_r3/i386/iso-cd/debian-40r3-i386-netinst.iso debian-40r3-i386-netinst.iso], the latest netinstall image at the time of writing. Burn this to a CD-recordable and boot your prepared hardware platform from this CD. After booting from the CD, a friendly prompt invites you to indicate how you want to boot the CD. Your choices are listed under &lt;F3&gt;; we're going to use the standard Command Line installation, so we type "install"&lt;enter&gt; or just simply &lt;enter&gt;. {| class="wikitable" border="1" |- |We could easily use "installgui", in which case we'd have a nice fresh Graphical User Interface for our installation. ''We're'' not going to, because we're real men, and [[http://isg.ee.ethz.ch/tools/realmen/ Real Men Don't Click]]. Also, we've found that from the GUI it's hard to switch to a second console and then back. We could also |} After the Linux kernel finishes initializing the machine, a simple text-based installer appears that immediately starts asking questions. Answer them according to your needs. Our example system uses the following choices: * Language: english * country: other &gt; Netherlands * keymap: American English (since we have a keyboard with US layout) Some installation software loads, and we get to the next phase: we're required to indicate which of the detected network interface cards (NIC) is going to be the "primary" NIC. {| class="wikitable" border="1" |- |Here, trouble could begin. If your machine has network cards that are '''not''' supported, then you'll see '''no''' cards here - but then how are you going to do a NetInstall? A solution would be to (temporarily) install a NIC that ''is'' supported, like a cheap Realtek card, or an old 3Com 905 card. Then, when the whole system is installed, up and running, you could compile a new kernel that contains support for your actual NICs, and when these work, remove the temporary NIC. For now, we'll assume your NICs are recognised properly by the Debian installation routine. |} Select the card that's connected to the Internet (again: it should ''not'' be connected straight to the wild wild web, but sit safely behind a firewall, at least until we've installed our own firewall); let's assume that this NIC is designated ''eth0'' by the Debian installation. This card will now be configured using DHCP, so if you're on a network with a DHCP-server, the network will work straight away. If it's not, you can either configure the network manually or fix your DHCP-server and connection between it and ''eth0''. Next is one of the hardest questions that any OS installation is going to ask you: what will be the host name of the system? You could change it at any time in the future, but with lots of hassle, so you better choose wisely. Here are our tips: * do '''not''' name your machine after the user that's going to use it, e.g. "bernie-pc" (at some time in the future, Bernie's machine will be moved to Alice, so then Alice is working on "bernie-pc" which makes the situation quite unclear); * do '''not''' name your machine after the department or workgroup that's using it most, e.g. "accounting-srv" (same reasoning); * do '''not''' name your machine after it's main function, e.g. "printserver" (at some time in the future, the main function is moved to another machine, and/or an alternative function will become the main function of the machine); * do '''not''' name your machine after it's location, e.g. "srv-boston" (at some time in the future, the box will be moved to another location); * do '''not''' name your machine after it's hardware configuration, e.g. "ibmx346" (at some time in the future, either another xSeries x346 will be wheeled in, or the machine will be upgraded to accomodate increased use or overcome hardware problems - your "ibmx346" could suddenly be running on an xSeries x3650). What we feel are safe names for ''any'' machine in your network are true names, perhaps linked to a common theme: names of European cities, names of movie characters, names of countries or holiday destinations et cetera. Immediately following comes the question of the Domain Name. This is about a DNS domain, so effectively the installation program is asking which DNS suffix the host name should have; if the DHCP-server already provided something it'll be suggested, but you can override it. ==Partitioning== Next comes the question of partitioning, or how to divide the available disk space into chunks for the server to use. This is a tricky subject, because if you put all storage space into one partition, then some day a runaway process will fill up the entire disk with useless logs, and the system will crash. On the other hand, if you divvy up all space into little chunks, then some application is going to need space in one of those partitions where there is none, even though there may be plenty in other partitions. To prevent both problems from occuring, we're going to use [http://tldp.org/HOWTO/LVM-HOWTO/whatisvolman.html Logical Volume Management (LVM)] so that we can provision enough space to start our server, but keep some space in reserve to apply when needed, where it'll be needed. So, we have put together a recommended standard partitioning scheme. The basis is this: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Partition !style="background:#ffdead;"|MD !style="background:#ffdead;"|LVG !style="background:#ffdead;"|LV-name !style="background:#ffdead;"|Size <br> (physical machine) !style="background:#ffdead;"|Size (VM) !style="background:#ffdead;"|File System !style="background:#ffdead;"|Mount point |- | 1 | /dev/md0 | &nbsp; | &nbsp; | 100MiB | 100MiB | ext3 | /boot |- | 2 | /dev/md1 | &nbsp; | &nbsp; | 3GiB | 1GiB | ext3 | / |- | rowspan="7" valign="top" | 3 | rowspan="7" valign="top" | /dev/md2 | rowspan="7" valign="top" style="background:lightgrey"| system | style="background:lightgrey" | swap | 1GiB<ref name="swap">Rule of thumb: twice the size of the machine's RAM, but no less than 256MiB and no more than 2GiB</ref> | 256MiB<ref name="swap"/> | swap | &nbsp; |- | style="background:lightgrey" | var | 2GiB | 1GiB | ext3 | /var |- | style="background:lightgrey" | appslog | 3GiB | - | ext3 | /var/appslog |- | style="background:lightgrey" | home | 1GiB<ref name="home">Note that this heavily depends on the purpose of the machine; if it is not to house any users, then (almost) no space is needed for /home. But on the other hand if e.g. a virtual user is to be used for keeping mailstores, or other service users need home space, then /home needs to be big enough for that.</ref> | 512MiB<ref name="home"/> | ext3 | /home |- | style="background:lightgrey" | usr | 3GiB | 3GiB | ext3 | /usr |- | style="background:lightgrey" | tmp | 1GiB | 512MiB | ext3 | /tmp |- | style="background:lightgrey" | opt | 1GiB | - | ext3 | /opt |- ! colspan="4" style="text-align:right"| Total ! 18.1GiB ! 6.9GiB ! colspan="2" | |- |} <references/> e32452c445612aac3a7a1c7b7bb45febfecfaf1c 1428 1427 2008-05-12T13:22:04Z Saruman! 2 /* Operating System installation */ wikitext text/x-wiki <big>'''Debian Etch Base Server setup'''</big> ==Getting the hardware== {| class="wikitable" border="1" |- |Note: in the following we're assuming you'll be assembling an x86 or x64 type of machine, as it has about the best price/performance ratio you could wish. Hardware costs for other platforms, e.g. IBM's Series p or HP 9000, can be much higher, while platforms like ARM are just not very powerful. Also, the availability of components and of help can be less than with the ubiquietous x86/x64 platforms. |} Naturally, before we can begin to install the operating system, we need to obtain the necessary hardware. Which hardware you require depends on what you want the server for; a testserver on which you will test only a single feature for a short while does not need the same quality of hardware as does a server that's supposed to act as a homeserver for many tasks for a long time. We'll assume your server will be like ours: a home server that must perform many tasks with sufficient performance for a few users, that's reliable and will last for a couple of years. So build or obtain a server with at least the following hardware: * a spacious casing with big, quiet cooling fans, like the [http://www.coolermaster.com/products/product.php?act=detail&id=317 one we have]; * an efficient, heavy-duty power supply that's rated high enough for your devices, and has a decent efficiency. For example, a [http://www.corsair.com/products/power_supplies.aspx Corsair HX520] power supply; * a server class motherboard, e.g. an [http://www.intel.com/products/server/index.htm?iid=home+hdr_nav2_server Intel] or [http://uk.asus.com/products.aspx?l1=9&l2=39&l3=263 AMD] based single-processor motherboard. DO NOT go for the cheapest motherboard you can find: if you pay peanuts, that's what you get. Server class motherboards have the quality, stability and durability you'll need from it, and usually also most of the needed peripherals, like multiple ethernet network cards on-board. Usually a Linux server doesn not require much in the way of video performance (and the screen will be used rarely, if ever), so any old integrated graphics will do. * a matching CPU - or multiple, if you think you need the power and the selected motherboard has the sockets. * a CD-ROM- or DVD-player * ''multiple'' harddisks - you'll want redundancy, because every harddisk fails at some time. The drive with your data on it will fail fatally when it is most inconvenient to you, and any data on it that you consider valuable will likely be lost forever. To make Murphy's work somewhat harder for him, we're going to store our data redundantly, so that if any drive in the server fails, we'll not lose our data or our server. Thus, get yourself at least two harddisks for your operating system, at least 40GiB in size (don't think you'll be able to buy smaller ones nowadays), and spanking new (NEVER use old harddisks for your production server, new ones are just too cheap to run that risk!). * (multipe) network card(s) (NICs) if your motherboard does not have enough NICs integrated on-board. You'll want a NIC for your network, and another one for your Internet connection; and possible a third one for the wireless segment of your network. Now build a machine out of the above, or have someone build it for you. ==Preparation of the hardware== (Note: in the following we're again assuming you're running an x86/x64 type of machine. Hardware requirements and preparation for other platforms, e.g. IBM's Series p or HP 9000, can differ significantly) Next, check the assembled hardware: * is the configuration complete? If it does not have a CD/DVDplayer from which it can boot, then installing the software gets more difficult - at least get an USB external DVDdrive or something like that. * are all components connected properly (memory DIMMs seated correctly in their sockets, AGP card inserted correctly into the AGP slot, et cetera) and are all cable connections made (multiple power cables to the motherboard, one power cable plus one data cable to each hard disk, etcetera)? Following this, you may hook up the machine. It's going to need power, and you will need at least a keyboard and a monitor attached. And if you want to use a Graphic User Interface to install, a mouse is required also. When you've ensured that everything is safe, you can turn on the machine, and continue to check it: * do all fans start to run when you turn on the machine? (if not, then '''quickly''' turn off your machine and correct the problem!) * does/do the hard disk(s) spin up? * do the power button and reset button operate correctly? * are the power led, HDD led and other display gadgetry functional? * when you let the machine power up, does it emit a single beep? And does it then show a Power-On Self Test screen (POST)? * Does it show the correct amount of memory in the POST screen? The correct number & speed of the CPU(s)? * Does the machine recognise all controller cards (SCSI, S-ATA etc)? And all attached DVD-drives and hard disks? * are all BIOSes/firmwares up to date? * If you have a hardware RAID controller, are your RAID arrays built already? * does the machine attempt to boot from at least the hard disk? ...et cetera. If there is any problem, or you want to update the BIOS or firmwares, it's best to do it before the operating system is installed. This Wiki, however, is not the place (yet) to get the information on how to accomplish these type of tasks. The last steps in the preparation of the hardware, are * to ensure that the machine can boot from CD/DVD, so that you can start installing Debian from it. It is possible to install Debian over the network, but that requires setting up a [http://www.debian-administration.org/articles/478 PXE Boot server] which is (currently) outside the scope of this wiki. * to connect the hardware to the Internet, so that it can get all required updates etcetera; please do ''not'' connect the box ''straight'' to the Internet, but make sure that it's safely behind a firewall, or failing that, a NAT router. By now the system should be almost ready to receive it's Operating System. But first we have an issue to tackle: that of redundancy. ==Software or hardware RAID== Your hard disks will fail. They absolutely will. It is never a question of "if", only of "when". So what will you do when the hard disk containing your complete operating system fails (besides pulling your hair out, that is)? What we propose is this: hard disks are pretty cheap nowadays, so let's use [http://en.wikipedia.org/wiki/Redundant_array_of_independent_disks RAID technology] to make our hard drive space resilient against failure of a whole drive. So first make sure that you have ''two'' disks of equal size instead of only one. Had you already been planning to use multiple disks already, then make sure you have at least ''one'' disk more than your space requirements prescribe; the space on that extra drive will provide the needed redundancy. Next, [[RAID fundamentals under Linux | click here]] to learn a bit more about RAID, to make the decision to use hardware-based and/or software-based RAID, and to plan your RAID arrays. In this example, we'll assume you're using hardware RAID on a RAID controller that's supported by the Debian installation software. This means that the installation software will "see" your RAID array(s) and present them as usable drives. ==Planning your network names== If your machine must become a part of an existing network, then it's almost certain that you already have a DNS domain in place; in that case: obtain the DNS suffix your machine will get (the DNS domain your machine will "belong" to). However, it's also possible that this machine is going to be the first machine in your new network, in which case the whole issue of DNS suffixes is wide open. If you need more information on DNS, go [[http://www.isc.org/sw/bind/arm95/Bv9ARM-all.html#id2564824 here]]. For now we'll assume you have (or will quickly obtain) a working knowledge of the DNS system. Here is our tip on choosing a DNS domain for your home network: * do '''not''' use a publicly registered domain name (e.g. "cocacola.com") for any machine that's not primarily intended to serve the public on the Internet; * for machines serving a private network, we urge you to use Top Level Domain name "lan" (to signify your machine is on a Local Area Network or LAN) * for the Domain Name itself, we suggest you use a level 2 name, like "saruman.lan", and not a level 3 name, like "mister.saruman.lan". This is only a short section on DNS, but remember that once a proper DNS system is in place, it's pretty much work to change it. At any rate, this section has most likely showed you that you need to put some thought into the DNS Domain Name design of your home network. OK, with this out of the way, we can get to installing the OS. ==Operating System installation== To install an Operating System (OS), it's kinda instrumental that you have one. Here, we're going to use [http://www.debian.org/intro/about Debian], the biggest [http://www.debian.org/intro/about#free Free] OS that we know of. Free stands for Freedom, but incidentally that Freedom also means it's gratis, an appealing aspect of Free. To get your own copy of Debian, go to their [http://www.debian.org/distrib/ download site] and obtain the latest [http://www.debian.org/releases/ Stable] image - in this wiki it's Debian 4.0, or "Etch" as it's also known. Besides the choice which release of Debian you want to run, you also have to know for which platform you're downloading (in our case: either ''amd64'' or ''i386'' depending on your hardware platform) and what kind of install you wish - if you have a working, fast Internet connection available at the time of install, then we recommend getting the [[http://www.debian.org/CD/netinst/ netinst] CD image; it's a relatively small CD, that'll be able to get you going, but gets most of the software you'll need straight from the 'net at install time. So, since in the example at hand we're installing on a Xeon server on which we wish to install 32-bits software, we'll download [http://cdimage.debian.org/debian-cd/4.0_r3/i386/iso-cd/debian-40r3-i386-netinst.iso debian-40r3-i386-netinst.iso], the latest netinstall image at the time of writing. Burn this to a CD-recordable and boot your prepared hardware platform from this CD. After booting from the CD, a friendly prompt invites you to indicate how you want to boot the CD. Your choices are listed under &lt;F3&gt;; we're going to use the standard Command Line installation, so we type "install"&lt;enter&gt; or just simply &lt;enter&gt;. {| class="wikitable" border="1" |- |We could easily use "installgui", in which case we'd have a nice fresh Graphical User Interface for our installation. ''We're'' not going to, because we're real men, and [http://isg.ee.ethz.ch/tools/realmen/ Real Men Don't Click]. Also, we've found that from the GUI it's hard to switch to a second console and then back. We could also opt for "expert" as installation method, because it gives a much finer grain of control, but we usually don't need that control, and can do without the barrage of extra questions that the "expert" installation method pose. Finally, we could opt for "expertgui", where we have both the barrage of extra questions ''and'' the GUI, neither of which we need. |} After the Linux kernel finishes initializing the machine, a simple text-based installer appears that immediately starts asking questions. Answer them according to your needs. Our example system uses the following choices: * Language: english * country: other &gt; Netherlands * keymap: American English (since we have a keyboard with US layout) Some installation software loads, and we get to the next phase: if you have multiple NICs in your machine (which we believe you ''should'' have!!), and if they're detected properly, then you're required to indicate which of the detected network interface cards (NIC) is going to be the "primary" NIC. {| class="wikitable" border="1" |- |Here, trouble could begin. If your machine has network cards that are '''not''' supported, then you'll see '''no''' cards here - but then how are you going to do a NetInstall? A solution would be to (temporarily) install a NIC that ''is'' supported, like a cheap Realtek card, or an old 3Com 905 card. Then, when the whole system is installed, up and running, you could compile a new kernel that contains support for your actual NICs, and when these work, remove the temporary NIC. For now, we'll assume that at least one of your NICs is recognised properly by the Debian installation routine. |} Select the card that's connected and has (indirect) access to Internet (again: it should ''not'' be connected straight to the wild wild web, but sit safely behind a firewall, at least until we've installed our own firewall); if at all possible, let it be the NIC that'll be connected to your home network itself, on the ''inside'' of your server. Let's assume that this NIC is designated ''eth0'' by the Debian installation. This card will now be configured using DHCP, so if you're on a network with a DHCP-server, the network will work straight away. If it's not, you can either configure the network manually or fix your DHCP-server and connection between it and ''eth0''. Next is one of the hardest questions that any OS installation is going to ask you: what will be the host name of the system? You could change it at any time in the future, but with lots of hassle, so you better choose wisely. Here are our tips: * do '''not''' name your machine after the user that's going to use it, e.g. "bernie-pc" (at some time in the future, Bernie's machine will be moved to Alice, so then Alice is working on "bernie-pc" which makes the situation quite unclear); * do '''not''' name your machine after the department or workgroup that's using it most, e.g. "accounting-srv" (same reasoning); * do '''not''' name your machine after it's main function, e.g. "printserver" (at some time in the future, the main function is moved to another machine, and/or an alternative function will become the main function of the machine); * do '''not''' name your machine after it's location, e.g. "srv-boston" (at some time in the future, the box will be moved to another location); * do '''not''' name your machine after it's hardware configuration, e.g. "ibmx346" (at some time in the future, either another xSeries x346 will be wheeled in, or the machine will be upgraded to accomodate increased use or overcome hardware problems - your "ibmx346" could suddenly be running on an xSeries x3650). What we feel are safe names for ''any'' machine in your network are true names, perhaps linked to a common theme: names of European cities, names of movie characters, names of countries or holiday destinations et cetera. Immediately following comes the question of the Domain Name. This is about a DNS domain, so effectively the installation program is asking which DNS suffix the host name should have; if the DHCP-server already provided something it'll be suggested, but you can override it. ==Partitioning== Next comes the question of partitioning, or how to divide the available disk space into chunks for the server to use. This is a tricky subject, because if you put all storage space into one partition, then some day a runaway process will fill up the entire disk with useless logs, and the system will crash. On the other hand, if you divvy up all space into little chunks, then some application is going to need space in one of those partitions where there is none, even though there may be plenty in other partitions. To prevent both problems from occuring, we're going to use [http://tldp.org/HOWTO/LVM-HOWTO/whatisvolman.html Logical Volume Management (LVM)] so that we can provision enough space to start our server, but keep some space in reserve to apply when needed, where it'll be needed. So, we have put together a recommended standard partitioning scheme. The basis is this: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Partition !style="background:#ffdead;"|MD !style="background:#ffdead;"|LVG !style="background:#ffdead;"|LV-name !style="background:#ffdead;"|Size <br> (physical machine) !style="background:#ffdead;"|Size (VM) !style="background:#ffdead;"|File System !style="background:#ffdead;"|Mount point |- | 1 | /dev/md0 | &nbsp; | &nbsp; | 100MiB | 100MiB | ext3 | /boot |- | 2 | /dev/md1 | &nbsp; | &nbsp; | 3GiB | 1GiB | ext3 | / |- | rowspan="7" valign="top" | 3 | rowspan="7" valign="top" | /dev/md2 | rowspan="7" valign="top" style="background:lightgrey"| system | style="background:lightgrey" | swap | 1GiB<ref name="swap">Rule of thumb: twice the size of the machine's RAM, but no less than 256MiB and no more than 2GiB</ref> | 256MiB<ref name="swap"/> | swap | &nbsp; |- | style="background:lightgrey" | var | 2GiB | 1GiB | ext3 | /var |- | style="background:lightgrey" | appslog | 3GiB | - | ext3 | /var/appslog |- | style="background:lightgrey" | home | 1GiB<ref name="home">Note that this heavily depends on the purpose of the machine; if it is not to house any users, then (almost) no space is needed for /home. But on the other hand if e.g. a virtual user is to be used for keeping mailstores, or other service users need home space, then /home needs to be big enough for that.</ref> | 512MiB<ref name="home"/> | ext3 | /home |- | style="background:lightgrey" | usr | 3GiB | 3GiB | ext3 | /usr |- | style="background:lightgrey" | tmp | 1GiB | 512MiB | ext3 | /tmp |- | style="background:lightgrey" | opt | 1GiB | - | ext3 | /opt |- ! colspan="4" style="text-align:right"| Total ! 18.1GiB ! 6.9GiB ! colspan="2" | |- |} <references/> c98554b72bf9e9007b776217b3e33622a1d41736 1432 1428 2008-05-12T14:29:35Z Saruman! 2 DNS remark wikitext text/x-wiki <big>'''Debian Etch Base Server setup'''</big> ==Getting the hardware== {| class="wikitable" border="1" |- |Note: in the following we're assuming you'll be assembling an x86 or x64 type of machine, as it has about the best price/performance ratio you could wish. Hardware costs for other platforms, e.g. IBM's Series p or HP 9000, can be much higher, while platforms like ARM are just not very powerful. Also, the availability of components and of help can be less than with the ubiquietous x86/x64 platforms. |} Naturally, before we can begin to install the operating system, we need to obtain the necessary hardware. Which hardware you require depends on what you want the server for; a testserver on which you will test only a single feature for a short while does not need the same quality of hardware as does a server that's supposed to act as a homeserver for many tasks for a long time. We'll assume your server will be like ours: a home server that must perform many tasks with sufficient performance for a few users, that's reliable and will last for a couple of years. So build or obtain a server with at least the following hardware: * a spacious casing with big, quiet cooling fans, like the [http://www.coolermaster.com/products/product.php?act=detail&id=317 one we have]; * an efficient, heavy-duty power supply that's rated high enough for your devices, and has a decent efficiency. For example, a [http://www.corsair.com/products/power_supplies.aspx Corsair HX520] power supply; * a server class motherboard, e.g. an [http://www.intel.com/products/server/index.htm?iid=home+hdr_nav2_server Intel] or [http://uk.asus.com/products.aspx?l1=9&l2=39&l3=263 AMD] based single-processor motherboard. DO NOT go for the cheapest motherboard you can find: if you pay peanuts, that's what you get. Server class motherboards have the quality, stability and durability you'll need from it, and usually also most of the needed peripherals, like multiple ethernet network cards on-board. Usually a Linux server doesn not require much in the way of video performance (and the screen will be used rarely, if ever), so any old integrated graphics will do. * a matching CPU - or multiple, if you think you need the power and the selected motherboard has the sockets. * a CD-ROM- or DVD-player * ''multiple'' harddisks - you'll want redundancy, because every harddisk fails at some time. The drive with your data on it will fail fatally when it is most inconvenient to you, and any data on it that you consider valuable will likely be lost forever. To make Murphy's work somewhat harder for him, we're going to store our data redundantly, so that if any drive in the server fails, we'll not lose our data or our server. Thus, get yourself at least two harddisks for your operating system, at least 40GiB in size (don't think you'll be able to buy smaller ones nowadays), and spanking new (NEVER use old harddisks for your production server, new ones are just too cheap to run that risk!). * (multipe) network card(s) (NICs) if your motherboard does not have enough NICs integrated on-board. You'll want a NIC for your network, and another one for your Internet connection; and possible a third one for the wireless segment of your network. Now build a machine out of the above, or have someone build it for you. ==Preparation of the hardware== (Note: in the following we're again assuming you're running an x86/x64 type of machine. Hardware requirements and preparation for other platforms, e.g. IBM's Series p or HP 9000, can differ significantly) Next, check the assembled hardware: * is the configuration complete? If it does not have a CD/DVDplayer from which it can boot, then installing the software gets more difficult - at least get an USB external DVDdrive or something like that. * are all components connected properly (memory DIMMs seated correctly in their sockets, AGP card inserted correctly into the AGP slot, et cetera) and are all cable connections made (multiple power cables to the motherboard, one power cable plus one data cable to each hard disk, etcetera)? Following this, you may hook up the machine. It's going to need power, and you will need at least a keyboard and a monitor attached. And if you want to use a Graphic User Interface to install, a mouse is required also. When you've ensured that everything is safe, you can turn on the machine, and continue to check it: * do all fans start to run when you turn on the machine? (if not, then '''quickly''' turn off your machine and correct the problem!) * does/do the hard disk(s) spin up? * do the power button and reset button operate correctly? * are the power led, HDD led and other display gadgetry functional? * when you let the machine power up, does it emit a single beep? And does it then show a Power-On Self Test screen (POST)? * Does it show the correct amount of memory in the POST screen? The correct number & speed of the CPU(s)? * Does the machine recognise all controller cards (SCSI, S-ATA etc)? And all attached DVD-drives and hard disks? * are all BIOSes/firmwares up to date? * If you have a hardware RAID controller, are your RAID arrays built already? * does the machine attempt to boot from at least the hard disk? ...et cetera. If there is any problem, or you want to update the BIOS or firmwares, it's best to do it before the operating system is installed. This Wiki, however, is not the place (yet) to get the information on how to accomplish these type of tasks. The last steps in the preparation of the hardware, are * to ensure that the machine can boot from CD/DVD, so that you can start installing Debian from it. It is possible to install Debian over the network, but that requires setting up a [http://www.debian-administration.org/articles/478 PXE Boot server] which is (currently) outside the scope of this wiki. * to connect the hardware to the Internet, so that it can get all required updates etcetera; please do ''not'' connect the box ''straight'' to the Internet, but make sure that it's safely behind a firewall, or failing that, a NAT router. By now the system should be almost ready to receive it's Operating System. But first we have an issue to tackle: that of redundancy. ==Software or hardware RAID== Your hard disks will fail. They absolutely will. It is never a question of "if", only of "when". So what will you do when the hard disk containing your complete operating system fails (besides pulling your hair out, that is)? What we propose is this: hard disks are pretty cheap nowadays, so let's use [http://en.wikipedia.org/wiki/Redundant_array_of_independent_disks RAID technology] to make our hard drive space resilient against failure of a whole drive. So first make sure that you have ''two'' disks of equal size instead of only one. Had you already been planning to use multiple disks already, then make sure you have at least ''one'' disk more than your space requirements prescribe; the space on that extra drive will provide the needed redundancy. Next, [[RAID fundamentals under Linux | click here]] to learn a bit more about RAID, to make the decision to use hardware-based and/or software-based RAID, and to plan your RAID arrays. In this example, we'll assume you're using hardware RAID on a RAID controller that's supported by the Debian installation software. This means that the installation software will "see" your RAID array(s) and present them as usable drives. ==Planning your network names== If your machine must become a part of an existing network, then it's almost certain that you already have a DNS domain in place; in that case: obtain the DNS suffix your machine will get (the DNS domain your machine will "belong" to). However, it's also possible that this machine is going to be the first machine in your new network, in which case the whole issue of DNS suffixes is wide open. If you need more information on DNS, go [[http://www.isc.org/sw/bind/arm95/Bv9ARM-all.html#id2564824 here]]. For now we'll assume you have (or will quickly obtain) a working knowledge of the DNS system. Here is our tip on choosing a DNS domain for your home network: * do '''not''' use a publicly registered domain name (e.g. "cocacola.com") for any machine that's not primarily intended to serve the public on the Internet; * for machines serving a private network, we urge you to use Top Level Domain name "lan" (to signify your machine is on a Local Area Network or LAN) * for the Domain Name itself, we suggest you use a level 2 name, like "saruman.lan", and not a level 3 name, like "mister.saruman.lan". This is only a short section on DNS, but remember that once a proper DNS system is in place, it's pretty much work to change it. At any rate, this section has most likely showed you that you need to put some thought into the DNS Domain Name design of your home network. OK, with this out of the way, we can get to installing the OS. ==Operating System installation== To install an Operating System (OS), it's kinda instrumental that you have one. Here, we're going to use [http://www.debian.org/intro/about Debian], the biggest [http://www.debian.org/intro/about#free Free] OS that we know of. Free stands for Freedom, but incidentally that Freedom also means it's gratis, an appealing aspect of Free. To get your own copy of Debian, go to their [http://www.debian.org/distrib/ download site] and obtain the latest [http://www.debian.org/releases/ Stable] image - in this wiki it's Debian 4.0, or "Etch" as it's also known. Besides the choice which release of Debian you want to run, you also have to know for which platform you're downloading (in our case: either ''amd64'' or ''i386'' depending on your hardware platform) and what kind of install you wish - if you have a working, fast Internet connection available at the time of install, then we recommend getting the [[http://www.debian.org/CD/netinst/ netinst] CD image; it's a relatively small CD, that'll be able to get you going, but gets most of the software you'll need straight from the 'net at install time. So, since in the example at hand we're installing on a Xeon server on which we wish to install 32-bits software, we'll download [http://cdimage.debian.org/debian-cd/4.0_r3/i386/iso-cd/debian-40r3-i386-netinst.iso debian-40r3-i386-netinst.iso], the latest netinstall image at the time of writing. Burn this to a CD-recordable and boot your prepared hardware platform from this CD. After booting from the CD, a friendly prompt invites you to indicate how you want to boot the CD. Your choices are listed under &lt;F3&gt;; we're going to use the standard Command Line installation, so we type "install"&lt;enter&gt; or just simply &lt;enter&gt;. {| class="wikitable" border="1" |- |We could easily use "installgui", in which case we'd have a nice fresh Graphical User Interface for our installation. ''We're'' not going to, because we're real men, and [http://isg.ee.ethz.ch/tools/realmen/ Real Men Don't Click]. Also, we've found that from the GUI it's hard to switch to a second console and then back. We could also opt for "expert" as installation method, because it gives a much finer grain of control, but we usually don't need that control, and can do without the barrage of extra questions that the "expert" installation method pose. Finally, we could opt for "expertgui", where we have both the barrage of extra questions ''and'' the GUI, neither of which we need. |} After the Linux kernel finishes initializing the machine, a simple text-based installer appears that immediately starts asking questions. Answer them according to your needs. Our example system uses the following choices: * Language: english * country: other &gt; Netherlands * keymap: American English (since we have a keyboard with US layout) Some installation software loads, and we get to the next phase: if you have multiple NICs in your machine (which we believe you ''should'' have!!), and if they're detected properly, then you're required to indicate which of the detected network interface cards (NIC) is going to be the "primary" NIC. {| class="wikitable" border="1" |- |Here, trouble could begin. If your machine has network cards that are '''not''' supported, then you'll see '''no''' cards here - but then how are you going to do a NetInstall? A solution would be to (temporarily) install a NIC that ''is'' supported, like a cheap Realtek card, or an old 3Com 905 card. Then, when the whole system is installed, up and running, you could compile a new kernel that contains support for your actual NICs, and when these work, remove the temporary NIC. For now, we'll assume that at least one of your NICs is recognised properly by the Debian installation routine. |} Select the card that's connected and has (indirect) access to Internet (again: it should ''not'' be connected straight to the wild wild web, but sit safely behind a firewall, at least until we've installed our own firewall); if at all possible, let it be the NIC that'll be connected to your home network itself, on the ''inside'' of your server. Let's assume that this NIC is designated ''eth0'' by the Debian installation. This card will now be configured using DHCP, so if you're on a network with a DHCP-server, the network will work straight away. If it's not, you can either configure the network manually or fix your DHCP-server and connection between it and ''eth0''. Next is one of the hardest questions that any OS installation is going to ask you: what will be the host name of the system? You could change it at any time in the future, but with lots of hassle, so you better choose wisely. Here are our tips: * do '''not''' name your machine after the user that's going to use it, e.g. "bernie-pc" (at some time in the future, Bernie's machine will be moved to Alice, so then Alice is working on "bernie-pc" which makes the situation quite unclear); * do '''not''' name your machine after the department or workgroup that's using it most, e.g. "accounting-srv" (same reasoning); * do '''not''' name your machine after it's main function, e.g. "printserver" (at some time in the future, the main function is moved to another machine, and/or an alternative function will become the main function of the machine); * do '''not''' name your machine after it's location, e.g. "srv-boston" (at some time in the future, the box will be moved to another location); * do '''not''' name your machine after it's hardware configuration, e.g. "ibmx346" (at some time in the future, either another xSeries x346 will be wheeled in, or the machine will be upgraded to accomodate increased use or overcome hardware problems - your "ibmx346" could suddenly be running on an xSeries x3650). What we feel are safe names for ''any'' machine in your network are true names, perhaps linked to a common theme: names of European cities, names of movie characters, names of countries or holiday destinations et cetera. Immediately following comes the question of the Domain Name. This is about a DNS domain, so effectively the installation program is asking which DNS suffix the host name should have; if the DHCP-server already provided something it'll be suggested, but you can override it if need be. In the preparatory phase, you'll have decided on continuation of your current DNS schema, or starting a new one. Either way, put the chosen DNS suffix in and press &lt;enter&gt;. ==Partitioning== Next comes the question of partitioning, or how to divide the available disk space into chunks for the server to use. This is a tricky subject, because if you put all storage space into one partition, then some day a runaway process will fill up the entire disk with useless logs, and the system will crash. On the other hand, if you divvy up all space into little chunks, then some application is going to need space in one of those partitions where there is none, even though there may be plenty in other partitions. To prevent both problems from occuring, we're going to use [http://tldp.org/HOWTO/LVM-HOWTO/whatisvolman.html Logical Volume Management (LVM)] so that we can provision enough space to start our server, but keep some space in reserve to apply when needed, where it'll be needed. So, we have put together a recommended standard partitioning scheme. The basis is this: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Partition !style="background:#ffdead;"|MD !style="background:#ffdead;"|LVG !style="background:#ffdead;"|LV-name !style="background:#ffdead;"|Size <br> (physical machine) !style="background:#ffdead;"|Size (VM) !style="background:#ffdead;"|File System !style="background:#ffdead;"|Mount point |- | 1 | /dev/md0 | &nbsp; | &nbsp; | 100MiB | 100MiB | ext3 | /boot |- | 2 | /dev/md1 | &nbsp; | &nbsp; | 3GiB | 1GiB | ext3 | / |- | rowspan="7" valign="top" | 3 | rowspan="7" valign="top" | /dev/md2 | rowspan="7" valign="top" style="background:lightgrey"| system | style="background:lightgrey" | swap | 1GiB<ref name="swap">Rule of thumb: twice the size of the machine's RAM, but no less than 256MiB and no more than 2GiB</ref> | 256MiB<ref name="swap"/> | swap | &nbsp; |- | style="background:lightgrey" | var | 2GiB | 1GiB | ext3 | /var |- | style="background:lightgrey" | appslog | 3GiB | - | ext3 | /var/appslog |- | style="background:lightgrey" | home | 1GiB<ref name="home">Note that this heavily depends on the purpose of the machine; if it is not to house any users, then (almost) no space is needed for /home. But on the other hand if e.g. a virtual user is to be used for keeping mailstores, or other service users need home space, then /home needs to be big enough for that.</ref> | 512MiB<ref name="home"/> | ext3 | /home |- | style="background:lightgrey" | usr | 3GiB | 3GiB | ext3 | /usr |- | style="background:lightgrey" | tmp | 1GiB | 512MiB | ext3 | /tmp |- | style="background:lightgrey" | opt | 1GiB | - | ext3 | /opt |- ! colspan="4" style="text-align:right"| Total ! 18.1GiB ! 6.9GiB ! colspan="2" | |- |} <references/> 6a483407b440b2dc369f613cd5aa5d7929de13af 1433 1432 2008-05-12T14:54:03Z Saruman! 2 working on software RAID description wikitext text/x-wiki <big>'''Debian Etch Base Server setup'''</big> ==Getting the hardware== {| class="wikitable" border="1" |- |Note: in the following we're assuming you'll be assembling an x86 or x64 type of machine, as it has about the best price/performance ratio you could wish. Hardware costs for other platforms, e.g. IBM's Series p or HP 9000, can be much higher, while platforms like ARM are just not very powerful. Also, the availability of components and of help can be less than with the ubiquietous x86/x64 platforms. |} Naturally, before we can begin to install the operating system, we need to obtain the necessary hardware. Which hardware you require depends on what you want the server for; a testserver on which you will test only a single feature for a short while does not need the same quality of hardware as does a server that's supposed to act as a homeserver for many tasks for a long time. We'll assume your server will be like ours: a home server that must perform many tasks with sufficient performance for a few users, that's reliable and will last for a couple of years. So build or obtain a server with at least the following hardware: * a spacious casing with big, quiet cooling fans, like the [http://www.coolermaster.com/products/product.php?act=detail&id=317 one we have]; * an efficient, heavy-duty power supply that's rated high enough for your devices, and has a decent efficiency. For example, a [http://www.corsair.com/products/power_supplies.aspx Corsair HX520] power supply; * a server class motherboard, e.g. an [http://www.intel.com/products/server/index.htm?iid=home+hdr_nav2_server Intel] or [http://uk.asus.com/products.aspx?l1=9&l2=39&l3=263 AMD] based single-processor motherboard. DO NOT go for the cheapest motherboard you can find: if you pay peanuts, that's what you get. Server class motherboards have the quality, stability and durability you'll need from it, and usually also most of the needed peripherals, like multiple ethernet network cards on-board. Usually a Linux server doesn not require much in the way of video performance (and the screen will be used rarely, if ever), so any old integrated graphics will do. * a matching CPU - or multiple, if you think you need the power and the selected motherboard has the sockets. * a CD-ROM- or DVD-player * ''multiple'' harddisks - you'll want redundancy, because every harddisk fails at some time. The drive with your data on it will fail fatally when it is most inconvenient to you, and any data on it that you consider valuable will likely be lost forever. To make Murphy's work somewhat harder for him, we're going to store our data redundantly, so that if any drive in the server fails, we'll not lose our data or our server. Thus, get yourself at least two harddisks for your operating system, at least 40GiB in size (don't think you'll be able to buy smaller ones nowadays), and spanking new (NEVER use old harddisks for your production server, new ones are just too cheap to run that risk!). * (multipe) network card(s) (NICs) if your motherboard does not have enough NICs integrated on-board. You'll want a NIC for your network, and another one for your Internet connection; and possible a third one for the wireless segment of your network. Now build a machine out of the above, or have someone build it for you. ==Preparation of the hardware== (Note: in the following we're again assuming you're running an x86/x64 type of machine. Hardware requirements and preparation for other platforms, e.g. IBM's Series p or HP 9000, can differ significantly) Next, check the assembled hardware: * is the configuration complete? If it does not have a CD/DVDplayer from which it can boot, then installing the software gets more difficult - at least get an USB external DVDdrive or something like that. * are all components connected properly (memory DIMMs seated correctly in their sockets, AGP card inserted correctly into the AGP slot, et cetera) and are all cable connections made (multiple power cables to the motherboard, one power cable plus one data cable to each hard disk, etcetera)? Following this, you may hook up the machine. It's going to need power, and you will need at least a keyboard and a monitor attached. And if you want to use a Graphic User Interface to install, a mouse is required also. When you've ensured that everything is safe, you can turn on the machine, and continue to check it: * do all fans start to run when you turn on the machine? (if not, then '''quickly''' turn off your machine and correct the problem!) * does/do the hard disk(s) spin up? * do the power button and reset button operate correctly? * are the power led, HDD led and other display gadgetry functional? * when you let the machine power up, does it emit a single beep? And does it then show a Power-On Self Test screen (POST)? * Does it show the correct amount of memory in the POST screen? The correct number & speed of the CPU(s)? * Does the machine recognise all controller cards (SCSI, S-ATA etc)? And all attached DVD-drives and hard disks? * are all BIOSes/firmwares up to date? * If you have a hardware RAID controller, are your RAID arrays built already? * does the machine attempt to boot from at least the hard disk? ...et cetera. If there is any problem, or you want to update the BIOS or firmwares, it's best to do it before the operating system is installed. This Wiki, however, is not the place (yet) to get the information on how to accomplish these type of tasks. The last steps in the preparation of the hardware, are * to ensure that the machine can boot from CD/DVD, so that you can start installing Debian from it. It is possible to install Debian over the network, but that requires setting up a [http://www.debian-administration.org/articles/478 PXE Boot server] which is (currently) outside the scope of this wiki. * to connect the hardware to the Internet, so that it can get all required updates etcetera; please do ''not'' connect the box ''straight'' to the Internet, but make sure that it's safely behind a firewall, or failing that, a NAT router. By now the system should be almost ready to receive it's Operating System. But first we have an issue to tackle: that of redundancy. ==Software or hardware RAID== Your hard disks will fail. They absolutely will. It is never a question of "if", only of "when". So what will you do when the hard disk containing your complete operating system fails (besides pulling your hair out, that is)? What we propose is this: hard disks are pretty cheap nowadays, so let's use [http://en.wikipedia.org/wiki/Redundant_array_of_independent_disks RAID technology] to make our hard drive space resilient against failure of a whole drive. So first make sure that you have ''two'' disks of equal size instead of only one. Had you already been planning to use multiple disks already, then make sure you have at least ''one'' disk more than your space requirements prescribe; the space on that extra drive will provide the needed redundancy. Next, [[RAID fundamentals under Linux | click here]] to learn a bit more about RAID, to make the decision to use hardware-based and/or software-based RAID, and to plan your RAID arrays. In this example, we'll assume you're using hardware RAID on a RAID controller that's supported by the Debian installation software. This means that the installation software will "see" your RAID array(s) and present them as usable drives. ==Planning your network names== If your machine must become a part of an existing network, then it's almost certain that you already have a DNS domain in place; in that case: obtain the DNS suffix your machine will get (the DNS domain your machine will "belong" to). However, it's also possible that this machine is going to be the first machine in your new network, in which case the whole issue of DNS suffixes is wide open. If you need more information on DNS, go [[http://www.isc.org/sw/bind/arm95/Bv9ARM-all.html#id2564824 here]]. For now we'll assume you have (or will quickly obtain) a working knowledge of the DNS system. Here is our tip on choosing a DNS domain for your home network: * do '''not''' use a publicly registered domain name (e.g. "cocacola.com") for any machine that's not primarily intended to serve the public on the Internet; * for machines serving a private network, we urge you to use Top Level Domain name "lan" (to signify your machine is on a Local Area Network or LAN) * for the Domain Name itself, we suggest you use a level 2 name, like "saruman.lan", and not a level 3 name, like "mister.saruman.lan". This is only a short section on DNS, but remember that once a proper DNS system is in place, it's pretty much work to change it. At any rate, this section has most likely showed you that you need to put some thought into the DNS Domain Name design of your home network. OK, with this out of the way, we can get to installing the OS. ==Operating System installation== To install an Operating System (OS), it's kinda instrumental that you have one. Here, we're going to use [http://www.debian.org/intro/about Debian], the biggest [http://www.debian.org/intro/about#free Free] OS that we know of. Free stands for Freedom, but incidentally that Freedom also means it's gratis, an appealing aspect of Free. To get your own copy of Debian, go to their [http://www.debian.org/distrib/ download site] and obtain the latest [http://www.debian.org/releases/ Stable] image - in this wiki it's Debian 4.0, or "Etch" as it's also known. Besides the choice which release of Debian you want to run, you also have to know for which platform you're downloading (in our case: either ''amd64'' or ''i386'' depending on your hardware platform) and what kind of install you wish - if you have a working, fast Internet connection available at the time of install, then we recommend getting the [[http://www.debian.org/CD/netinst/ netinst] CD image; it's a relatively small CD, that'll be able to get you going, but gets most of the software you'll need straight from the 'net at install time. So, since in the example at hand we're installing on a Xeon server on which we wish to install 32-bits software, we'll download [http://cdimage.debian.org/debian-cd/4.0_r3/i386/iso-cd/debian-40r3-i386-netinst.iso debian-40r3-i386-netinst.iso], the latest netinstall image at the time of writing. Burn this to a CD-recordable and boot your prepared hardware platform from this CD. After booting from the CD, a friendly prompt invites you to indicate how you want to boot the CD. Your choices are listed under &lt;F3&gt;; we're going to use the standard Command Line installation, so we type "install"&lt;enter&gt; or just simply &lt;enter&gt;. {| class="wikitable" border="1" |- |We could easily use "installgui", in which case we'd have a nice fresh Graphical User Interface for our installation. ''We're'' not going to, because we're real men, and [http://isg.ee.ethz.ch/tools/realmen/ Real Men Don't Click]. Also, we've found that from the GUI it's hard to switch to a second console and then back. We could also opt for "expert" as installation method, because it gives a much finer grain of control, but we usually don't need that control, and can do without the barrage of extra questions that the "expert" installation method pose. Finally, we could opt for "expertgui", where we have both the barrage of extra questions ''and'' the GUI, neither of which we need. |} After the Linux kernel finishes initializing the machine, a simple text-based installer appears that immediately starts asking questions. Answer them according to your needs. Our example system uses the following choices: * Language: english * country: other &gt; Netherlands * keymap: American English (since we have a keyboard with US layout) Some installation software loads, and we get to the next phase: if you have multiple NICs in your machine (which we believe you ''should'' have!!), and if they're detected properly, then you're required to indicate which of the detected network interface cards (NIC) is going to be the "primary" NIC. {| class="wikitable" border="1" |- |Here, trouble could begin. If your machine has network cards that are '''not''' supported, then you'll see '''no''' cards here - but then how are you going to do a NetInstall? A solution would be to (temporarily) install a NIC that ''is'' supported, like a cheap Realtek card, or an old 3Com 905 card. Then, when the whole system is installed, up and running, you could compile a new kernel that contains support for your actual NICs, and when these work, remove the temporary NIC. For now, we'll assume that at least one of your NICs is recognised properly by the Debian installation routine. |} Select the card that's connected and has (indirect) access to Internet (again: it should ''not'' be connected straight to the wild wild web, but sit safely behind a firewall, at least until we've installed our own firewall); if at all possible, let it be the NIC that'll be connected to your home network itself, on the ''inside'' of your server. Let's assume that this NIC is designated ''eth0'' by the Debian installation. This card will now be configured using DHCP, so if you're on a network with a DHCP-server, the network will work straight away. If it's not, you can either configure the network manually or fix your DHCP-server and connection between it and ''eth0''. Next is one of the hardest questions that any OS installation is going to ask you: what will be the host name of the system? You could change it at any time in the future, but with lots of hassle, so you better choose wisely. Here are our tips: * do '''not''' name your machine after the user that's going to use it, e.g. "bernie-pc" (at some time in the future, Bernie's machine will be moved to Alice, so then Alice is working on "bernie-pc" which makes the situation quite unclear); * do '''not''' name your machine after the department or workgroup that's using it most, e.g. "accounting-srv" (same reasoning); * do '''not''' name your machine after it's main function, e.g. "printserver" (at some time in the future, the main function is moved to another machine, and/or an alternative function will become the main function of the machine); * do '''not''' name your machine after it's location, e.g. "srv-boston" (at some time in the future, the box will be moved to another location); * do '''not''' name your machine after it's hardware configuration, e.g. "ibmx346" (at some time in the future, either another xSeries x346 will be wheeled in, or the machine will be upgraded to accomodate increased use or overcome hardware problems - your "ibmx346" could suddenly be running on an xSeries x3650). What we feel are safe names for ''any'' machine in your network are true names, perhaps linked to a common theme: names of European cities, names of movie characters, names of countries or holiday destinations et cetera. Immediately following comes the question of the Domain Name. This is about a DNS domain, so effectively the installation program is asking which DNS suffix the host name should have; if the DHCP-server already provided something it'll be suggested, but you can override it if need be. In the preparatory phase, you'll have decided on continuation of your current DNS schema, or starting a new one. Either way, put the chosen DNS suffix in and press &lt;enter&gt;. ==Partitioning== Next comes the question of partitioning, or how to divide the available disk space into chunks for the server to use. This is a tricky subject, because if you put all storage space into one partition, then some day a runaway process will fill up the entire disk with useless logs, and the system will crash. On the other hand, if you divvy up all space into little chunks, then some application is going to need space in one of those partitions where there is none, even though there may be plenty in other partitions. To prevent both problems from occuring, we're going to use [http://tldp.org/HOWTO/LVM-HOWTO/whatisvolman.html Logical Volume Management (LVM)] so that we can provision enough space to start our server, but keep some space in reserve to apply when needed, where it'll be needed. So, we at Saruman.biz have put together a recommended standard partitioning scheme. The basis is this: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Partition !style="background:#ffdead;"|MD !style="background:#ffdead;"|LVG !style="background:#ffdead;"|LV-name !style="background:#ffdead;"|Size <br> (physical machine) !style="background:#ffdead;"|Size (VM) !style="background:#ffdead;"|File System !style="background:#ffdead;"|Mount point |- | 1 | /dev/md0 | &nbsp; | &nbsp; | 100MiB | 100MiB | ext3 | /boot |- | 2 | /dev/md1 | &nbsp; | &nbsp; | 3GiB | 1GiB | ext3 | / |- | rowspan="7" valign="top" | 3 | rowspan="7" valign="top" | /dev/md2 | rowspan="7" valign="top" style="background:lightgrey"| system | style="background:lightgrey" | swap | 1GiB<ref name="swap">Rule of thumb: twice the size of the machine's RAM, but no less than 256MiB and no more than 2GiB</ref> | 256MiB<ref name="swap"/> | swap | &nbsp; |- | style="background:lightgrey" | var | 2GiB | 1GiB | ext3 | /var |- | style="background:lightgrey" | appslog | 3GiB | - | ext3 | /var/appslog |- | style="background:lightgrey" | home | 1GiB<ref name="home">Note that this heavily depends on the purpose of the machine; if it is not to house any users, then (almost) no space is needed for /home. But on the other hand if e.g. a virtual user is to be used for keeping mailstores, or other service users need home space, then /home needs to be big enough for that.</ref> | 512MiB<ref name="home"/> | ext3 | /home |- | style="background:lightgrey" | usr | 3GiB | 3GiB | ext3 | /usr |- | style="background:lightgrey" | tmp | 1GiB | 512MiB | ext3 | /tmp |- | style="background:lightgrey" | opt | 1GiB | - | ext3 | /opt |- ! colspan="4" style="text-align:right"| Total ! 18.1GiB ! 6.9GiB ! colspan="2" | |- |} As you can see, the partition table works as follows: we assume that we wind up with 3 partitions, either on three separate software RAID arrays (''md0'' through ''md2'') or on one single hardware RAID array (in which case the 2nd column ''MD'' does not apply). The size of the partitions depends on your machine's make: for standard physical machines the 5th column does sensible suggestions, even though you could choose to have different sizes and of course different divisions altogether. If your machine happens to be a virtual one, running inside a [http://www.vmware.com/products/server/ VMware Server] or [http://www.vmware.com/products/vi/esx/ VMware ESX host], or the like, then you might want to start out with more modest partitions. The same holds for small servers that must run off Flash drives. Anyways, we're now at the Debian installation screen that lets us partition our disks. We're ''not'' going to use any of the "guided" partitionings, we go for "manual". Choosing that brings us to a screen showing all drives that the installation routine has detected, and all partitions on those drives that the installer can "see". We're going to do some assuming here once more: let's assume the drive(s) on which you want to install are visible, and are empty (containing no other partitions). <references/> ===Software RAID partitioning=== If you're to use software RAID, you now have to select the free space on the first drive, press &lt;enter&gt;, and then tell what you want to do with the free space: create a new partition, tell which size you want (see table above), give type (primary), and give where on the disk (the beginning). Next, a screen comes up that details how the partition will be created. Here we make some changes: under "use as" we're going to select "physical volume for RAID". This clears all the other options in this screen, except for the "bootable" flag, which must be "on" for the first partition that we'll mount as ''/boot''. Now select "Done setting up the partition". Next, go to the free space on the second disk, and do ''exactly'' the same, to create an identical physical volume for RAID - if it's the first one, select the "bootable" flag as well (we'll want to be able to boot from this second disk if the first one fails, right?). Then go back to the rest of the free space on the first disk, make the second physical volume for RAID, duplicate it on the second disk. Then, go back to the rest of the free space on the first disk, make the third physical volume for RAID, and again duplicate it on the second disk. If you now go back to ===Hardware RAID partitioning=== Now, if you have hardware RAID, then on your boot disk just make 3 partitions 141dee28349947232e2ecef87f1db7d73a69bac0 1434 1433 2008-05-12T17:21:53Z Saruman! 2 LVM started wikitext text/x-wiki <big>'''Debian Etch Base Server setup'''</big> ==Getting the hardware== {| class="wikitable" border="1" |- |Note: in the following we're assuming you'll be assembling an x86 or x64 type of machine, as it has about the best price/performance ratio you could wish. Hardware costs for other platforms, e.g. IBM's Series p or HP 9000, can be much higher, while platforms like ARM are just not very powerful. Also, the availability of components and of help can be less than with the ubiquietous x86/x64 platforms. |} Naturally, before we can begin to install the operating system, we need to obtain the necessary hardware. Which hardware you require depends on what you want the server for; a testserver on which you will test only a single feature for a short while does not need the same quality of hardware as does a server that's supposed to act as a homeserver for many tasks for a long time. We'll assume your server will be like ours: a home server that must perform many tasks with sufficient performance for a few users, that's reliable and will last for a couple of years. So build or obtain a server with at least the following hardware: * a spacious casing with big, quiet cooling fans, like the [http://www.coolermaster.com/products/product.php?act=detail&id=317 one we have]; * an efficient, heavy-duty power supply that's rated high enough for your devices, and has a decent efficiency. For example, a [http://www.corsair.com/products/power_supplies.aspx Corsair HX520] power supply; * a server class motherboard, e.g. an [http://www.intel.com/products/server/index.htm?iid=home+hdr_nav2_server Intel] or [http://uk.asus.com/products.aspx?l1=9&l2=39&l3=263 AMD] based single-processor motherboard. DO NOT go for the cheapest motherboard you can find: if you pay peanuts, that's what you get. Server class motherboards have the quality, stability and durability you'll need from it, and usually also most of the needed peripherals, like multiple ethernet network cards on-board. Usually a Linux server doesn not require much in the way of video performance (and the screen will be used rarely, if ever), so any old integrated graphics will do. * a matching CPU - or multiple, if you think you need the power and the selected motherboard has the sockets. * a CD-ROM- or DVD-player * ''multiple'' harddisks - you'll want redundancy, because every harddisk fails at some time. The drive with your data on it will fail fatally when it is most inconvenient to you, and any data on it that you consider valuable will likely be lost forever. To make Murphy's work somewhat harder for him, we're going to store our data redundantly, so that if any drive in the server fails, we'll not lose our data or our server. Thus, get yourself at least two harddisks for your operating system, at least 40GiB in size (don't think you'll be able to buy smaller ones nowadays), and spanking new (NEVER use old harddisks for your production server, new ones are just too cheap to run that risk!). * (multipe) network card(s) (NICs) if your motherboard does not have enough NICs integrated on-board. You'll want a NIC for your network, and another one for your Internet connection; and possible a third one for the wireless segment of your network. Now build a machine out of the above, or have someone build it for you. ==Preparation of the hardware== (Note: in the following we're again assuming you're running an x86/x64 type of machine. Hardware requirements and preparation for other platforms, e.g. IBM's Series p or HP 9000, can differ significantly) Next, check the assembled hardware: * is the configuration complete? If it does not have a CD/DVDplayer from which it can boot, then installing the software gets more difficult - at least get an USB external DVDdrive or something like that. * are all components connected properly (memory DIMMs seated correctly in their sockets, AGP card inserted correctly into the AGP slot, et cetera) and are all cable connections made (multiple power cables to the motherboard, one power cable plus one data cable to each hard disk, etcetera)? Following this, you may hook up the machine. It's going to need power, and you will need at least a keyboard and a monitor attached. And if you want to use a Graphic User Interface to install, a mouse is required also. When you've ensured that everything is safe, you can turn on the machine, and continue to check it: * do all fans start to run when you turn on the machine? (if not, then '''quickly''' turn off your machine and correct the problem!) * does/do the hard disk(s) spin up? * do the power button and reset button operate correctly? * are the power led, HDD led and other display gadgetry functional? * when you let the machine power up, does it emit a single beep? And does it then show a Power-On Self Test screen (POST)? * Does it show the correct amount of memory in the POST screen? The correct number & speed of the CPU(s)? * Does the machine recognise all controller cards (SCSI, S-ATA etc)? And all attached DVD-drives and hard disks? * are all BIOSes/firmwares up to date? * If you have a hardware RAID controller, are your RAID arrays built already? * does the machine attempt to boot from at least the hard disk? ...et cetera. If there is any problem, or you want to update the BIOS or firmwares, it's best to do it before the operating system is installed. This Wiki, however, is not the place (yet) to get the information on how to accomplish these type of tasks. The last steps in the preparation of the hardware, are * to ensure that the machine can boot from CD/DVD, so that you can start installing Debian from it. It is possible to install Debian over the network, but that requires setting up a [http://www.debian-administration.org/articles/478 PXE Boot server] which is (currently) outside the scope of this wiki. * to connect the hardware to the Internet, so that it can get all required updates etcetera; please do ''not'' connect the box ''straight'' to the Internet, but make sure that it's safely behind a firewall, or failing that, a NAT router. By now the system should be almost ready to receive it's Operating System. But first we have an issue to tackle: that of redundancy. ==Software or hardware RAID== Your hard disks will fail. They absolutely will. It is never a question of "if", only of "when". So what will you do when the hard disk containing your complete operating system fails (besides pulling your hair out, that is)? What we propose is this: hard disks are pretty cheap nowadays, so let's use [http://en.wikipedia.org/wiki/Redundant_array_of_independent_disks RAID technology] to make our hard drive space resilient against failure of a whole drive. So first make sure that you have ''two'' disks of equal size instead of only one. Had you already been planning to use multiple disks already, then make sure you have at least ''one'' disk more than your space requirements prescribe; the space on that extra drive will provide the needed redundancy. Next, [[RAID fundamentals under Linux | click here]] to learn a bit more about RAID, to make the decision to use hardware-based and/or software-based RAID, and to plan your RAID arrays. In this example, we'll assume you're using hardware RAID on a RAID controller that's supported by the Debian installation software. This means that the installation software will "see" your RAID array(s) and present them as usable drives. ==Planning your network names== If your machine must become a part of an existing network, then it's almost certain that you already have a DNS domain in place; in that case: obtain the DNS suffix your machine will get (the DNS domain your machine will "belong" to). However, it's also possible that this machine is going to be the first machine in your new network, in which case the whole issue of DNS suffixes is wide open. If you need more information on DNS, go [[http://www.isc.org/sw/bind/arm95/Bv9ARM-all.html#id2564824 here]]. For now we'll assume you have (or will quickly obtain) a working knowledge of the DNS system. Here is our tip on choosing a DNS domain for your home network: * do '''not''' use a publicly registered domain name (e.g. "cocacola.com") for any machine that's not primarily intended to serve the public on the Internet; * for machines serving a private network, we urge you to use Top Level Domain name "lan" (to signify your machine is on a Local Area Network or LAN) * for the Domain Name itself, we suggest you use a level 2 name, like "saruman.lan", and not a level 3 name, like "mister.saruman.lan". This is only a short section on DNS, but remember that once a proper DNS system is in place, it's pretty much work to change it. At any rate, this section has most likely showed you that you need to put some thought into the DNS Domain Name design of your home network. OK, with this out of the way, we can get to installing the OS. ==Operating System installation== To install an Operating System (OS), it's kinda instrumental that you have one. Here, we're going to use [http://www.debian.org/intro/about Debian], the biggest [http://www.debian.org/intro/about#free Free] OS that we know of. Free stands for Freedom, but incidentally that Freedom also means it's gratis, an appealing aspect of Free. To get your own copy of Debian, go to their [http://www.debian.org/distrib/ download site] and obtain the latest [http://www.debian.org/releases/ Stable] image - in this wiki it's Debian 4.0, or "Etch" as it's also known. Besides the choice which release of Debian you want to run, you also have to know for which platform you're downloading (in our case: either ''amd64'' or ''i386'' depending on your hardware platform) and what kind of install you wish - if you have a working, fast Internet connection available at the time of install, then we recommend getting the [[http://www.debian.org/CD/netinst/ netinst] CD image; it's a relatively small CD, that'll be able to get you going, but gets most of the software you'll need straight from the 'net at install time. So, since in the example at hand we're installing on a Xeon server on which we wish to install 32-bits software, we'll download [http://cdimage.debian.org/debian-cd/4.0_r3/i386/iso-cd/debian-40r3-i386-netinst.iso debian-40r3-i386-netinst.iso], the latest netinstall image at the time of writing. Burn this to a CD-recordable and boot your prepared hardware platform from this CD. After booting from the CD, a friendly prompt invites you to indicate how you want to boot the CD. Your choices are listed under &lt;F3&gt;; we're going to use the standard Command Line installation, so we type "install"&lt;enter&gt; or just simply &lt;enter&gt;. {| class="wikitable" border="1" |- |We could easily use "installgui", in which case we'd have a nice fresh Graphical User Interface for our installation. ''We're'' not going to, because we're real men, and [http://isg.ee.ethz.ch/tools/realmen/ Real Men Don't Click]. Also, we've found that from the GUI it's hard to switch to a second console and then back. We could also opt for "expert" as installation method, because it gives a much finer grain of control, but we usually don't need that control, and can do without the barrage of extra questions that the "expert" installation method pose. Finally, we could opt for "expertgui", where we have both the barrage of extra questions ''and'' the GUI, neither of which we need. |} After the Linux kernel finishes initializing the machine, a simple text-based installer appears that immediately starts asking questions. Answer them according to your needs. Our example system uses the following choices: * Language: english * country: other &gt; Netherlands * keymap: American English (since we have a keyboard with US layout) Some installation software loads, and we get to the next phase: if you have multiple NICs in your machine (which we believe you ''should'' have!!), and if they're detected properly, then you're required to indicate which of the detected network interface cards (NIC) is going to be the "primary" NIC. {| class="wikitable" border="1" |- |Here, trouble could begin. If your machine has network cards that are '''not''' supported, then you'll see '''no''' cards here - but then how are you going to do a NetInstall? A solution would be to (temporarily) install a NIC that ''is'' supported, like a cheap Realtek card, or an old 3Com 905 card. Then, when the whole system is installed, up and running, you could compile a new kernel that contains support for your actual NICs, and when these work, remove the temporary NIC. For now, we'll assume that at least one of your NICs is recognised properly by the Debian installation routine. |} Select the card that's connected and has (indirect) access to Internet (again: it should ''not'' be connected straight to the wild wild web, but sit safely behind a firewall, at least until we've installed our own firewall); if at all possible, let it be the NIC that'll be connected to your home network itself, on the ''inside'' of your server. Let's assume that this NIC is designated ''eth0'' by the Debian installation. This card will now be configured using DHCP, so if you're on a network with a DHCP-server, the network will work straight away. If it's not, you can either configure the network manually or fix your DHCP-server and connection between it and ''eth0''. Next is one of the hardest questions that any OS installation is going to ask you: what will be the host name of the system? You could change it at any time in the future, but with lots of hassle, so you better choose wisely. Here are our tips: * do '''not''' name your machine after the user that's going to use it, e.g. "bernie-pc" (at some time in the future, Bernie's machine will be moved to Alice, so then Alice is working on "bernie-pc" which makes the situation quite unclear); * do '''not''' name your machine after the department or workgroup that's using it most, e.g. "accounting-srv" (same reasoning); * do '''not''' name your machine after it's main function, e.g. "printserver" (at some time in the future, the main function is moved to another machine, and/or an alternative function will become the main function of the machine); * do '''not''' name your machine after it's location, e.g. "srv-boston" (at some time in the future, the box will be moved to another location); * do '''not''' name your machine after it's hardware configuration, e.g. "ibmx346" (at some time in the future, either another xSeries x346 will be wheeled in, or the machine will be upgraded to accomodate increased use or overcome hardware problems - your "ibmx346" could suddenly be running on an xSeries x3650). What we feel are safe names for ''any'' machine in your network are true names, perhaps linked to a common theme: names of European cities, names of movie characters, names of countries or holiday destinations et cetera. Immediately following comes the question of the Domain Name. This is about a DNS domain, so effectively the installation program is asking which DNS suffix the host name should have; if the DHCP-server already provided something it'll be suggested, but you can override it if need be. In the preparatory phase, you'll have decided on continuation of your current DNS schema, or starting a new one. Either way, put the chosen DNS suffix in and press &lt;enter&gt;. ==Partitioning== Next comes the question of partitioning, or how to divide the available disk space into chunks for the server to use. This is a tricky subject, because if you put all storage space into one partition, then some day a runaway process will fill up the entire disk with useless logs, and the system will crash. On the other hand, if you divvy up all space into little chunks, then some application is going to need space in one of those partitions where there is none, even though there may be plenty in other partitions. To prevent both problems from occuring, we're going to use [http://tldp.org/HOWTO/LVM-HOWTO/whatisvolman.html Logical Volume Management (LVM)] so that we can provision enough space to start our server, but keep some space in reserve to apply when needed, where it'll be needed. So, we at Saruman.biz have put together a recommended standard partitioning scheme. The basis is this: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Partition !style="background:#ffdead;"|MD !style="background:#ffdead;"|LVG !style="background:#ffdead;"|LV-name !style="background:#ffdead;"|Size <br> (physical machine) !style="background:#ffdead;"|Size (VM) !style="background:#ffdead;"|File System !style="background:#ffdead;"|Mount point |- | 1 | /dev/md0 | &nbsp; | &nbsp; | 100MiB | 100MiB | ext3 | /boot |- | 2 | /dev/md1 | &nbsp; | &nbsp; | 3GiB | 1GiB | ext3 | / |- | rowspan="7" valign="top" | 3 | rowspan="7" valign="top" | /dev/md2 | rowspan="7" valign="top" style="background:lightgrey"| system | style="background:lightgrey" | swap | 1GiB<ref name="swap">Rule of thumb: twice the size of the machine's RAM, but no less than 256MiB and no more than 2GiB</ref> | 256MiB<ref name="swap"/> | swap | &nbsp; |- | style="background:lightgrey" | var | 2GiB | 1GiB | ext3 | /var |- | style="background:lightgrey" | appslog | 3GiB | - | ext3 | /var/appslog |- | style="background:lightgrey" | home | 1GiB<ref name="home">Note that this heavily depends on the purpose of the machine; if it is not to house any users, then (almost) no space is needed for /home. But on the other hand if e.g. a virtual user is to be used for keeping mailstores, or other service users need home space, then /home needs to be big enough for that.</ref> | 512MiB<ref name="home"/> | ext3 | /home |- | style="background:lightgrey" | usr | 3GiB | 3GiB | ext3 | /usr |- | style="background:lightgrey" | tmp | 1GiB | 512MiB | ext3 | /tmp |- | style="background:lightgrey" | opt | 1GiB | - | ext3 | /opt |- ! colspan="4" style="text-align:right"| Total ! 18.1GiB ! 6.9GiB ! colspan="2" | |- |} As you can see, the partition table works as follows: we assume that we wind up with 3 partitions, either on three separate software RAID arrays (''md0'' through ''md2'') or on one single hardware RAID array (in which case the 2nd column ''MD'' does not apply). The size of the partitions depends on your machine's make: for standard physical machines the 5th column does sensible suggestions, even though you could choose to have different sizes and of course different divisions altogether. If your machine happens to be a virtual one, running inside a [http://www.vmware.com/products/server/ VMware Server] or [http://www.vmware.com/products/vi/esx/ VMware ESX host], or the like, then you might want to start out with more modest partitions. The same holds for small servers that must run off Flash drives. Anyways, we're now at the Debian installation screen that lets us partition our disks. We're ''not'' going to use any of the "guided" partitionings, we go for "manual". Choosing that brings us to a screen showing all drives that the installation routine has detected, and all partitions on those drives that the installer can "see". We're going to do some assuming here once more: let's assume the drive(s) on which you want to install are visible, and are empty (containing no other partitions). <references/> ===Software RAID partitioning=== If you're to use software RAID, you now have to select the free space on the first drive, press &lt;enter&gt;, and then tell what you want to do with the free space: create a new partition, tell which size you want it to be (see table above), give the type of partition (primary), and give where on the disk it'll sit (the beginning). Next, a screen comes up that details how the partition you're requesting will be created. Here we make some changes: under "use as" we're going to select "physical volume for RAID". This clears all the other options in this screen, except for the "bootable" flag, which must be "on" for the first partition that we'll mount as ''/boot''. Now select "Done setting up the partition". Next, go to the free space on the second disk, and do ''exactly'' the same, to create an identical physical volume for RAID - if it's the first partition, select the "bootable" flag as well (we'll want to be able to boot from this second disk if the first disk fails, right?). Then go back to the rest of the free space on the first disk, make the second physical volume for RAID, duplicate it on the second disk. Then, go back to the rest of the free space on the first disk, make the third physical volume for RAID, and again duplicate it on the second disk. If you now go back to the "partition disks" overview, you'll see all the partitions you've specified listed on their respective disks. But at the top an extra option has appeared, called "configure software RAID". When you now select this option, the installer will ask if it may write the changes you've made to disk. This actually creates the partition tables on the disks. ===Hardware RAID partitioning=== Now, if you have hardware RAID, then on your first (boot) disk just make 3 partitions, in the following manner: Select the free space on the intended boot disk, press &lt;enter&gt;, select "create a new partition", and fill out the desired size (100MB). Type is primary, location is beginning of the disk, and in the details of the partition, we only need to change the Mount point to "/boot", and set the Bootable flag to "On". Then we're "Done setting up this partition". The second partition is made the same way, but the desired size is 3GB, the Mount point is "/", and the Bootable flag remains off. Again, we're "Done setting up this partition". The third partition is again a primary partition, it takes up the entire rest of the disk, but the type is not ext3, but "physical volume for LVM". Again, we're "Done setting up this partition". But now from the main partitioner screen, we can access "Configure the Logical Volume Manager". The installer asks if it can write out the choices made to the disk, and then enters the LVM setup screen, which begins with a summary explaining that you have one Free Physical Volume, and nothing more. We now 5f4656b635ad120819c860e12ec135579b8d926e 1435 1434 2008-05-12T18:48:25Z Saruman! 2 /* Hardware RAID partitioning */ described LVM config wikitext text/x-wiki <big>'''Debian Etch Base Server setup'''</big> ==Getting the hardware== {| class="wikitable" border="1" |- |Note: in the following we're assuming you'll be assembling an x86 or x64 type of machine, as it has about the best price/performance ratio you could wish. Hardware costs for other platforms, e.g. IBM's Series p or HP 9000, can be much higher, while platforms like ARM are just not very powerful. Also, the availability of components and of help can be less than with the ubiquietous x86/x64 platforms. |} Naturally, before we can begin to install the operating system, we need to obtain the necessary hardware. Which hardware you require depends on what you want the server for; a testserver on which you will test only a single feature for a short while does not need the same quality of hardware as does a server that's supposed to act as a homeserver for many tasks for a long time. We'll assume your server will be like ours: a home server that must perform many tasks with sufficient performance for a few users, that's reliable and will last for a couple of years. So build or obtain a server with at least the following hardware: * a spacious casing with big, quiet cooling fans, like the [http://www.coolermaster.com/products/product.php?act=detail&id=317 one we have]; * an efficient, heavy-duty power supply that's rated high enough for your devices, and has a decent efficiency. For example, a [http://www.corsair.com/products/power_supplies.aspx Corsair HX520] power supply; * a server class motherboard, e.g. an [http://www.intel.com/products/server/index.htm?iid=home+hdr_nav2_server Intel] or [http://uk.asus.com/products.aspx?l1=9&l2=39&l3=263 AMD] based single-processor motherboard. DO NOT go for the cheapest motherboard you can find: if you pay peanuts, that's what you get. Server class motherboards have the quality, stability and durability you'll need from it, and usually also most of the needed peripherals, like multiple ethernet network cards on-board. Usually a Linux server doesn not require much in the way of video performance (and the screen will be used rarely, if ever), so any old integrated graphics will do. * a matching CPU - or multiple, if you think you need the power and the selected motherboard has the sockets. * a CD-ROM- or DVD-player * ''multiple'' harddisks - you'll want redundancy, because every harddisk fails at some time. The drive with your data on it will fail fatally when it is most inconvenient to you, and any data on it that you consider valuable will likely be lost forever. To make Murphy's work somewhat harder for him, we're going to store our data redundantly, so that if any drive in the server fails, we'll not lose our data or our server. Thus, get yourself at least two harddisks for your operating system, at least 40GiB in size (don't think you'll be able to buy smaller ones nowadays), and spanking new (NEVER use old harddisks for your production server, new ones are just too cheap to run that risk!). * (multipe) network card(s) (NICs) if your motherboard does not have enough NICs integrated on-board. You'll want a NIC for your network, and another one for your Internet connection; and possible a third one for the wireless segment of your network. Now build a machine out of the above, or have someone build it for you. ==Preparation of the hardware== (Note: in the following we're again assuming you're running an x86/x64 type of machine. Hardware requirements and preparation for other platforms, e.g. IBM's Series p or HP 9000, can differ significantly) Next, check the assembled hardware: * is the configuration complete? If it does not have a CD/DVDplayer from which it can boot, then installing the software gets more difficult - at least get an USB external DVDdrive or something like that. * are all components connected properly (memory DIMMs seated correctly in their sockets, AGP card inserted correctly into the AGP slot, et cetera) and are all cable connections made (multiple power cables to the motherboard, one power cable plus one data cable to each hard disk, etcetera)? Following this, you may hook up the machine. It's going to need power, and you will need at least a keyboard and a monitor attached. And if you want to use a Graphic User Interface to install, a mouse is required also. When you've ensured that everything is safe, you can turn on the machine, and continue to check it: * do all fans start to run when you turn on the machine? (if not, then '''quickly''' turn off your machine and correct the problem!) * does/do the hard disk(s) spin up? * do the power button and reset button operate correctly? * are the power led, HDD led and other display gadgetry functional? * when you let the machine power up, does it emit a single beep? And does it then show a Power-On Self Test screen (POST)? * Does it show the correct amount of memory in the POST screen? The correct number & speed of the CPU(s)? * Does the machine recognise all controller cards (SCSI, S-ATA etc)? And all attached DVD-drives and hard disks? * are all BIOSes/firmwares up to date? * If you have a hardware RAID controller, are your RAID arrays built already? * does the machine attempt to boot from at least the hard disk? ...et cetera. If there is any problem, or you want to update the BIOS or firmwares, it's best to do it before the operating system is installed. This Wiki, however, is not the place (yet) to get the information on how to accomplish these type of tasks. The last steps in the preparation of the hardware, are * to ensure that the machine can boot from CD/DVD, so that you can start installing Debian from it. It is possible to install Debian over the network, but that requires setting up a [http://www.debian-administration.org/articles/478 PXE Boot server] which is (currently) outside the scope of this wiki. * to connect the hardware to the Internet, so that it can get all required updates etcetera; please do ''not'' connect the box ''straight'' to the Internet, but make sure that it's safely behind a firewall, or failing that, a NAT router. By now the system should be almost ready to receive it's Operating System. But first we have an issue to tackle: that of redundancy. ==Software or hardware RAID== Your hard disks will fail. They absolutely will. It is never a question of "if", only of "when". So what will you do when the hard disk containing your complete operating system fails (besides pulling your hair out, that is)? What we propose is this: hard disks are pretty cheap nowadays, so let's use [http://en.wikipedia.org/wiki/Redundant_array_of_independent_disks RAID technology] to make our hard drive space resilient against failure of a whole drive. So first make sure that you have ''two'' disks of equal size instead of only one. Had you already been planning to use multiple disks already, then make sure you have at least ''one'' disk more than your space requirements prescribe; the space on that extra drive will provide the needed redundancy. Next, [[RAID fundamentals under Linux | click here]] to learn a bit more about RAID, to make the decision to use hardware-based and/or software-based RAID, and to plan your RAID arrays. In this example, we'll assume you're using hardware RAID on a RAID controller that's supported by the Debian installation software. This means that the installation software will "see" your RAID array(s) and present them as usable drives. ==Planning your network names== If your machine must become a part of an existing network, then it's almost certain that you already have a DNS domain in place; in that case: obtain the DNS suffix your machine will get (the DNS domain your machine will "belong" to). However, it's also possible that this machine is going to be the first machine in your new network, in which case the whole issue of DNS suffixes is wide open. If you need more information on DNS, go [[http://www.isc.org/sw/bind/arm95/Bv9ARM-all.html#id2564824 here]]. For now we'll assume you have (or will quickly obtain) a working knowledge of the DNS system. Here is our tip on choosing a DNS domain for your home network: * do '''not''' use a publicly registered domain name (e.g. "cocacola.com") for any machine that's not primarily intended to serve the public on the Internet; * for machines serving a private network, we urge you to use Top Level Domain name "lan" (to signify your machine is on a Local Area Network or LAN) * for the Domain Name itself, we suggest you use a level 2 name, like "saruman.lan", and not a level 3 name, like "mister.saruman.lan". This is only a short section on DNS, but remember that once a proper DNS system is in place, it's pretty much work to change it. At any rate, this section has most likely showed you that you need to put some thought into the DNS Domain Name design of your home network. OK, with this out of the way, we can get to installing the OS. ==Operating System installation== To install an Operating System (OS), it's kinda instrumental that you have one. Here, we're going to use [http://www.debian.org/intro/about Debian], the biggest [http://www.debian.org/intro/about#free Free] OS that we know of. Free stands for Freedom, but incidentally that Freedom also means it's gratis, an appealing aspect of Free. To get your own copy of Debian, go to their [http://www.debian.org/distrib/ download site] and obtain the latest [http://www.debian.org/releases/ Stable] image - in this wiki it's Debian 4.0, or "Etch" as it's also known. Besides the choice which release of Debian you want to run, you also have to know for which platform you're downloading (in our case: either ''amd64'' or ''i386'' depending on your hardware platform) and what kind of install you wish - if you have a working, fast Internet connection available at the time of install, then we recommend getting the [[http://www.debian.org/CD/netinst/ netinst] CD image; it's a relatively small CD, that'll be able to get you going, but gets most of the software you'll need straight from the 'net at install time. So, since in the example at hand we're installing on a Xeon server on which we wish to install 32-bits software, we'll download [http://cdimage.debian.org/debian-cd/4.0_r3/i386/iso-cd/debian-40r3-i386-netinst.iso debian-40r3-i386-netinst.iso], the latest netinstall image at the time of writing. Burn this to a CD-recordable and boot your prepared hardware platform from this CD. After booting from the CD, a friendly prompt invites you to indicate how you want to boot the CD. Your choices are listed under &lt;F3&gt;; we're going to use the standard Command Line installation, so we type "install"&lt;enter&gt; or just simply &lt;enter&gt;. {| class="wikitable" border="1" |- |We could easily use "installgui", in which case we'd have a nice fresh Graphical User Interface for our installation. ''We're'' not going to, because we're real men, and [http://isg.ee.ethz.ch/tools/realmen/ Real Men Don't Click]. Also, we've found that from the GUI it's hard to switch to a second console and then back. We could also opt for "expert" as installation method, because it gives a much finer grain of control, but we usually don't need that control, and can do without the barrage of extra questions that the "expert" installation method pose. Finally, we could opt for "expertgui", where we have both the barrage of extra questions ''and'' the GUI, neither of which we need. |} After the Linux kernel finishes initializing the machine, a simple text-based installer appears that immediately starts asking questions. Answer them according to your needs. Our example system uses the following choices: * Language: english * country: other &gt; Netherlands * keymap: American English (since we have a keyboard with US layout) Some installation software loads, and we get to the next phase: if you have multiple NICs in your machine (which we believe you ''should'' have!!), and if they're detected properly, then you're required to indicate which of the detected network interface cards (NIC) is going to be the "primary" NIC. {| class="wikitable" border="1" |- |Here, trouble could begin. If your machine has network cards that are '''not''' supported, then you'll see '''no''' cards here - but then how are you going to do a NetInstall? A solution would be to (temporarily) install a NIC that ''is'' supported, like a cheap Realtek card, or an old 3Com 905 card. Then, when the whole system is installed, up and running, you could compile a new kernel that contains support for your actual NICs, and when these work, remove the temporary NIC. For now, we'll assume that at least one of your NICs is recognised properly by the Debian installation routine. |} Select the card that's connected and has (indirect) access to Internet (again: it should ''not'' be connected straight to the wild wild web, but sit safely behind a firewall, at least until we've installed our own firewall); if at all possible, let it be the NIC that'll be connected to your home network itself, on the ''inside'' of your server. Let's assume that this NIC is designated ''eth0'' by the Debian installation. This card will now be configured using DHCP, so if you're on a network with a DHCP-server, the network will work straight away. If it's not, you can either configure the network manually or fix your DHCP-server and connection between it and ''eth0''. Next is one of the hardest questions that any OS installation is going to ask you: what will be the host name of the system? You could change it at any time in the future, but with lots of hassle, so you better choose wisely. Here are our tips: * do '''not''' name your machine after the user that's going to use it, e.g. "bernie-pc" (at some time in the future, Bernie's machine will be moved to Alice, so then Alice is working on "bernie-pc" which makes the situation quite unclear); * do '''not''' name your machine after the department or workgroup that's using it most, e.g. "accounting-srv" (same reasoning); * do '''not''' name your machine after it's main function, e.g. "printserver" (at some time in the future, the main function is moved to another machine, and/or an alternative function will become the main function of the machine); * do '''not''' name your machine after it's location, e.g. "srv-boston" (at some time in the future, the box will be moved to another location); * do '''not''' name your machine after it's hardware configuration, e.g. "ibmx346" (at some time in the future, either another xSeries x346 will be wheeled in, or the machine will be upgraded to accomodate increased use or overcome hardware problems - your "ibmx346" could suddenly be running on an xSeries x3650). What we feel are safe names for ''any'' machine in your network are true names, perhaps linked to a common theme: names of European cities, names of movie characters, names of countries or holiday destinations et cetera. Immediately following comes the question of the Domain Name. This is about a DNS domain, so effectively the installation program is asking which DNS suffix the host name should have; if the DHCP-server already provided something it'll be suggested, but you can override it if need be. In the preparatory phase, you'll have decided on continuation of your current DNS schema, or starting a new one. Either way, put the chosen DNS suffix in and press &lt;enter&gt;. ==Partitioning== Next comes the question of partitioning, or how to divide the available disk space into chunks for the server to use. This is a tricky subject, because if you put all storage space into one partition, then some day a runaway process will fill up the entire disk with useless logs, and the system will crash. On the other hand, if you divvy up all space into little chunks, then some application is going to need space in one of those partitions where there is none, even though there may be plenty in other partitions. To prevent both problems from occuring, we're going to use [http://tldp.org/HOWTO/LVM-HOWTO/whatisvolman.html Logical Volume Management (LVM)] so that we can provision enough space to start our server, but keep some space in reserve to apply when needed, where it'll be needed. So, we at Saruman.biz have put together a recommended standard partitioning scheme. The basis is this: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Partition !style="background:#ffdead;"|MD !style="background:#ffdead;"|LVG !style="background:#ffdead;"|LV-name !style="background:#ffdead;"|Size <br> (physical machine) !style="background:#ffdead;"|Size (VM) !style="background:#ffdead;"|File System !style="background:#ffdead;"|Mount point |- | 1 | /dev/md0 | &nbsp; | &nbsp; | 100MiB | 100MiB | ext3 | /boot |- | 2 | /dev/md1 | &nbsp; | &nbsp; | 3GiB | 1GiB | ext3 | / |- | rowspan="7" valign="top" | 3 | rowspan="7" valign="top" | /dev/md2 | rowspan="7" valign="top" style="background:lightgrey"| system | style="background:lightgrey" | swap | 1GiB<ref name="swap">Rule of thumb: twice the size of the machine's RAM, but no less than 256MiB and no more than 2GiB</ref> | 256MiB<ref name="swap"/> | swap | &nbsp; |- | style="background:lightgrey" | var | 2GiB | 1GiB | ext3 | /var |- | style="background:lightgrey" | appslog | 3GiB | - | ext3 | /var/appslog |- | style="background:lightgrey" | home | 1GiB<ref name="home">Note that this heavily depends on the purpose of the machine; if it is not to house any users, then (almost) no space is needed for /home. But on the other hand if e.g. a virtual user is to be used for keeping mailstores, or other service users need home space, then /home needs to be big enough for that.</ref> | 512MiB<ref name="home"/> | ext3 | /home |- | style="background:lightgrey" | usr | 3GiB | 3GiB | ext3 | /usr |- | style="background:lightgrey" | tmp | 1GiB | 512MiB | ext3 | /tmp |- | style="background:lightgrey" | opt | 1GiB | - | ext3 | /opt |- ! colspan="4" style="text-align:right"| Total ! 18.1GiB ! 6.9GiB ! colspan="2" | |- |} As you can see, the partition table works as follows: we assume that we wind up with 3 partitions, either on three separate software RAID arrays (''md0'' through ''md2'') or on one single hardware RAID array (in which case the 2nd column ''MD'' does not apply). The size of the partitions depends on your machine's make: for standard physical machines the 5th column does sensible suggestions, even though you could choose to have different sizes and of course different divisions altogether. If your machine happens to be a virtual one, running inside a [http://www.vmware.com/products/server/ VMware Server] or [http://www.vmware.com/products/vi/esx/ VMware ESX host], or the like, then you might want to start out with more modest partitions. The same holds for small servers that must run off Flash drives. Anyways, we're now at the Debian installation screen that lets us partition our disks. We're ''not'' going to use any of the "guided" partitionings, we go for "manual". Choosing that brings us to a screen showing all drives that the installation routine has detected, and all partitions on those drives that the installer can "see". We're going to do some assuming here once more: let's assume the drive(s) on which you want to install are visible, and are empty (containing no other partitions). <references/> ===Software RAID partitioning=== If you're to use software RAID, you now have to select the free space on the first drive, press &lt;enter&gt;, and then tell what you want to do with the free space: create a new partition, tell which size you want it to be (see table above), give the type of partition (primary), and give where on the disk it'll sit (the beginning). Next, a screen comes up that details how the partition you're requesting will be created. Here we make some changes: under "use as" we're going to select "physical volume for RAID". This clears all the other options in this screen, except for the "bootable" flag, which must be "on" for the first partition that we'll mount as ''/boot''. Now select "Done setting up the partition". Next, go to the free space on the second disk, and do ''exactly'' the same, to create an identical physical volume for RAID - if it's the first partition, select the "bootable" flag as well (we'll want to be able to boot from this second disk if the first disk fails, right?). Then go back to the rest of the free space on the first disk, make the second physical volume for RAID, duplicate it on the second disk. Then, go back to the rest of the free space on the first disk, make the third physical volume for RAID, and again duplicate it on the second disk. If you now go back to the "partition disks" overview, you'll see all the partitions you've specified listed on their respective disks. But at the top an extra option has appeared, called "configure software RAID". When you now select this option, the installer will ask if it may write the changes you've made to disk. This actually creates the partition tables on the disks. ===Hardware RAID partitioning=== Now, if you have hardware RAID, then on your first (boot) disk just make 3 partitions, in the following manner: Select the free space on the intended boot disk, press &lt;enter&gt;, select "create a new partition", and fill out the desired size (100MB). Type is primary, location is beginning of the disk, and in the details of the partition, we only need to change the Mount point to "/boot", and set the Bootable flag to "On". Then we're "Done setting up this partition". The second partition is made the same way, but the desired size is 3GB, the Mount point is "/", and the Bootable flag remains off. Again, we're "Done setting up this partition". The third partition is again a primary partition, it takes up the entire rest of the disk, but the type is not ext3, but "physical volume for LVM". Again, we're "Done setting up this partition". But now from the main partitioner screen, we can access "Configure the Logical Volume Manager". The installer asks if it can write out the choices made to the disk, and then enters the LVM setup screen, which begins with a summary explaining that you have one Free Physical Volume, and nothing more. We now create a Volume Group (VG), which (in accordance to our partitioning standard) we'll call "system". In this VG, we'll add all Physical Volumes (being the one partition we've designated so in the previous step) using the space bar. Now we repeat the following process seven times: * select "Create Logical Volume" * select Volume Group "System" * give the LV Name (from the table, e.g. swap, var etc) * give the LV size (from the table, e.g. 1GB for swap etc) After this, we can select "Finish", the partitioner creates the seven LVs, and we're back at the partitioner screen, where there are now 7 extra "disks", with names such as ''LVM VG system, LV appslog - 3.2GB Linux device mapper''. Each of these "disks" has one block of empty space, which we now assign: seven times we repeat the following process: * select the unassigned chunk of empty space of an LV (e.g. appslog) and press &lt;enter&gt;; * Change "Use as: do not use" into the desired filesystem (ext3 - only the LV "swap" gets as filesystem type "swap area") * Change the mount point from "none" to the one corresponding with the name of the LV (note: the swap LV has no mountpoint; the appslog mountpoint must be entered manually as "/var/appslog") * If so desired, a label can be assigned to the partition (we usually don't) * select "Done setting up the partition" Once all this is done, we can look over the configuration once more, and then select "Finish partitioning and write changes to disk". A summary configuration screen will show, and we'll affirm with "yes" that these partitions can indeed be formatted. After some formatting screens flashing by (unless your partitions are particularly big, your system is particularly slow, or something goes wrong) the installation procedure continues. 4049679818379ed18a4cf63f9b308ebe02388d10 1436 1435 2008-05-12T19:00:30Z Saruman! 2 Started "further installation" wikitext text/x-wiki <big>'''Debian Etch Base Server setup'''</big> ==Getting the hardware== {| class="wikitable" border="1" |- |Note: in the following we're assuming you'll be assembling an x86 or x64 type of machine, as it has about the best price/performance ratio you could wish. Hardware costs for other platforms, e.g. IBM's Series p or HP 9000, can be much higher, while platforms like ARM are just not very powerful. Also, the availability of components and of help can be less than with the ubiquietous x86/x64 platforms. |} Naturally, before we can begin to install the operating system, we need to obtain the necessary hardware. Which hardware you require depends on what you want the server for; a testserver on which you will test only a single feature for a short while does not need the same quality of hardware as does a server that's supposed to act as a homeserver for many tasks for a long time. We'll assume your server will be like ours: a home server that must perform many tasks with sufficient performance for a few users, that's reliable and will last for a couple of years. So build or obtain a server with at least the following hardware: * a spacious casing with big, quiet cooling fans, like the [http://www.coolermaster.com/products/product.php?act=detail&id=317 one we have]; * an efficient, heavy-duty power supply that's rated high enough for your devices, and has a decent efficiency. For example, a [http://www.corsair.com/products/power_supplies.aspx Corsair HX520] power supply; * a server class motherboard, e.g. an [http://www.intel.com/products/server/index.htm?iid=home+hdr_nav2_server Intel] or [http://uk.asus.com/products.aspx?l1=9&l2=39&l3=263 AMD] based single-processor motherboard. DO NOT go for the cheapest motherboard you can find: if you pay peanuts, that's what you get. Server class motherboards have the quality, stability and durability you'll need from it, and usually also most of the needed peripherals, like multiple ethernet network cards on-board. Usually a Linux server doesn not require much in the way of video performance (and the screen will be used rarely, if ever), so any old integrated graphics will do. * a matching CPU - or multiple, if you think you need the power and the selected motherboard has the sockets. * a CD-ROM- or DVD-player * ''multiple'' harddisks - you'll want redundancy, because every harddisk fails at some time. The drive with your data on it will fail fatally when it is most inconvenient to you, and any data on it that you consider valuable will likely be lost forever. To make Murphy's work somewhat harder for him, we're going to store our data redundantly, so that if any drive in the server fails, we'll not lose our data or our server. Thus, get yourself at least two harddisks for your operating system, at least 40GiB in size (don't think you'll be able to buy smaller ones nowadays), and spanking new (NEVER use old harddisks for your production server, new ones are just too cheap to run that risk!). * (multipe) network card(s) (NICs) if your motherboard does not have enough NICs integrated on-board. You'll want a NIC for your network, and another one for your Internet connection; and possible a third one for the wireless segment of your network. Now build a machine out of the above, or have someone build it for you. ==Preparation of the hardware== (Note: in the following we're again assuming you're running an x86/x64 type of machine. Hardware requirements and preparation for other platforms, e.g. IBM's Series p or HP 9000, can differ significantly) Next, check the assembled hardware: * is the configuration complete? If it does not have a CD/DVDplayer from which it can boot, then installing the software gets more difficult - at least get an USB external DVDdrive or something like that. * are all components connected properly (memory DIMMs seated correctly in their sockets, AGP card inserted correctly into the AGP slot, et cetera) and are all cable connections made (multiple power cables to the motherboard, one power cable plus one data cable to each hard disk, etcetera)? Following this, you may hook up the machine. It's going to need power, and you will need at least a keyboard and a monitor attached. And if you want to use a Graphic User Interface to install, a mouse is required also. When you've ensured that everything is safe, you can turn on the machine, and continue to check it: * do all fans start to run when you turn on the machine? (if not, then '''quickly''' turn off your machine and correct the problem!) * does/do the hard disk(s) spin up? * do the power button and reset button operate correctly? * are the power led, HDD led and other display gadgetry functional? * when you let the machine power up, does it emit a single beep? And does it then show a Power-On Self Test screen (POST)? * Does it show the correct amount of memory in the POST screen? The correct number & speed of the CPU(s)? * Does the machine recognise all controller cards (SCSI, S-ATA etc)? And all attached DVD-drives and hard disks? * are all BIOSes/firmwares up to date? * If you have a hardware RAID controller, are your RAID arrays built already? * does the machine attempt to boot from at least the hard disk? ...et cetera. If there is any problem, or you want to update the BIOS or firmwares, it's best to do it before the operating system is installed. This Wiki, however, is not the place (yet) to get the information on how to accomplish these type of tasks. The last steps in the preparation of the hardware, are * to ensure that the machine can boot from CD/DVD, so that you can start installing Debian from it. It is possible to install Debian over the network, but that requires setting up a [http://www.debian-administration.org/articles/478 PXE Boot server] which is (currently) outside the scope of this wiki. * to connect the hardware to the Internet, so that it can get all required updates etcetera; please do ''not'' connect the box ''straight'' to the Internet, but make sure that it's safely behind a firewall, or failing that, a NAT router. By now the system should be almost ready to receive it's Operating System. But first we have an issue to tackle: that of redundancy. ==Software or hardware RAID== Your hard disks will fail. They absolutely will. It is never a question of "if", only of "when". So what will you do when the hard disk containing your complete operating system fails (besides pulling your hair out, that is)? What we propose is this: hard disks are pretty cheap nowadays, so let's use [http://en.wikipedia.org/wiki/Redundant_array_of_independent_disks RAID technology] to make our hard drive space resilient against failure of a whole drive. So first make sure that you have ''two'' disks of equal size instead of only one. Had you already been planning to use multiple disks already, then make sure you have at least ''one'' disk more than your space requirements prescribe; the space on that extra drive will provide the needed redundancy. Next, [[RAID fundamentals under Linux | click here]] to learn a bit more about RAID, to make the decision to use hardware-based and/or software-based RAID, and to plan your RAID arrays. In this example, we'll assume you're using hardware RAID on a RAID controller that's supported by the Debian installation software. This means that the installation software will "see" your RAID array(s) and present them as usable drives. ==Planning your network names== If your machine must become a part of an existing network, then it's almost certain that you already have a DNS domain in place; in that case: obtain the DNS suffix your machine will get (the DNS domain your machine will "belong" to). However, it's also possible that this machine is going to be the first machine in your new network, in which case the whole issue of DNS suffixes is wide open. If you need more information on DNS, go [[http://www.isc.org/sw/bind/arm95/Bv9ARM-all.html#id2564824 here]]. For now we'll assume you have (or will quickly obtain) a working knowledge of the DNS system. Here is our tip on choosing a DNS domain for your home network: * do '''not''' use a publicly registered domain name (e.g. "cocacola.com") for any machine that's not primarily intended to serve the public on the Internet; * for machines serving a private network, we urge you to use Top Level Domain name "lan" (to signify your machine is on a Local Area Network or LAN) * for the Domain Name itself, we suggest you use a level 2 name, like "saruman.lan", and not a level 3 name, like "mister.saruman.lan". This is only a short section on DNS, but remember that once a proper DNS system is in place, it's pretty much work to change it. At any rate, this section has most likely showed you that you need to put some thought into the DNS Domain Name design of your home network. OK, with this out of the way, we can get to installing the OS. ==Operating System installation== To install an Operating System (OS), it's kinda instrumental that you have one. Here, we're going to use [http://www.debian.org/intro/about Debian], the biggest [http://www.debian.org/intro/about#free Free] OS that we know of. Free stands for Freedom, but incidentally that Freedom also means it's gratis, an appealing aspect of Free. To get your own copy of Debian, go to their [http://www.debian.org/distrib/ download site] and obtain the latest [http://www.debian.org/releases/ Stable] image - in this wiki it's Debian 4.0, or "Etch" as it's also known. Besides the choice which release of Debian you want to run, you also have to know for which platform you're downloading (in our case: either ''amd64'' or ''i386'' depending on your hardware platform) and what kind of install you wish - if you have a working, fast Internet connection available at the time of install, then we recommend getting the [[http://www.debian.org/CD/netinst/ netinst] CD image; it's a relatively small CD, that'll be able to get you going, but gets most of the software you'll need straight from the 'net at install time. So, since in the example at hand we're installing on a Xeon server on which we wish to install 32-bits software, we'll download [http://cdimage.debian.org/debian-cd/4.0_r3/i386/iso-cd/debian-40r3-i386-netinst.iso debian-40r3-i386-netinst.iso], the latest netinstall image at the time of writing. Burn this to a CD-recordable and boot your prepared hardware platform from this CD. After booting from the CD, a friendly prompt invites you to indicate how you want to boot the CD. Your choices are listed under &lt;F3&gt;; we're going to use the standard Command Line installation, so we type "install"&lt;enter&gt; or just simply &lt;enter&gt;. {| class="wikitable" border="1" |- |We could easily use "installgui", in which case we'd have a nice fresh Graphical User Interface for our installation. ''We're'' not going to, because we're real men, and [http://isg.ee.ethz.ch/tools/realmen/ Real Men Don't Click]. Also, we've found that from the GUI it's hard to switch to a second console and then back. We could also opt for "expert" as installation method, because it gives a much finer grain of control, but we usually don't need that control, and can do without the barrage of extra questions that the "expert" installation method pose. Finally, we could opt for "expertgui", where we have both the barrage of extra questions ''and'' the GUI, neither of which we need. |} After the Linux kernel finishes initializing the machine, a simple text-based installer appears that immediately starts asking questions. Answer them according to your needs. Our example system uses the following choices: * Language: english * country: other &gt; Netherlands * keymap: American English (since we have a keyboard with US layout) Some installation software loads, and we get to the next phase: if you have multiple NICs in your machine (which we believe you ''should'' have!!), and if they're detected properly, then you're required to indicate which of the detected network interface cards (NIC) is going to be the "primary" NIC. {| class="wikitable" border="1" |- |Here, trouble could begin. If your machine has network cards that are '''not''' supported, then you'll see '''no''' cards here - but then how are you going to do a NetInstall? A solution would be to (temporarily) install a NIC that ''is'' supported, like a cheap Realtek card, or an old 3Com 905 card. Then, when the whole system is installed, up and running, you could compile a new kernel that contains support for your actual NICs, and when these work, remove the temporary NIC. For now, we'll assume that at least one of your NICs is recognised properly by the Debian installation routine. |} Select the card that's connected and has (indirect) access to Internet (again: it should ''not'' be connected straight to the wild wild web, but sit safely behind a firewall, at least until we've installed our own firewall); if at all possible, let it be the NIC that'll be connected to your home network itself, on the ''inside'' of your server. Let's assume that this NIC is designated ''eth0'' by the Debian installation. This card will now be configured using DHCP, so if you're on a network with a DHCP-server, the network will work straight away. If it's not, you can either configure the network manually or fix your DHCP-server and connection between it and ''eth0''. Next is one of the hardest questions that any OS installation is going to ask you: what will be the host name of the system? You could change it at any time in the future, but with lots of hassle, so you better choose wisely. Here are our tips: * do '''not''' name your machine after the user that's going to use it, e.g. "bernie-pc" (at some time in the future, Bernie's machine will be moved to Alice, so then Alice is working on "bernie-pc" which makes the situation quite unclear); * do '''not''' name your machine after the department or workgroup that's using it most, e.g. "accounting-srv" (same reasoning); * do '''not''' name your machine after it's main function, e.g. "printserver" (at some time in the future, the main function is moved to another machine, and/or an alternative function will become the main function of the machine); * do '''not''' name your machine after it's location, e.g. "srv-boston" (at some time in the future, the box will be moved to another location); * do '''not''' name your machine after it's hardware configuration, e.g. "ibmx346" (at some time in the future, either another xSeries x346 will be wheeled in, or the machine will be upgraded to accomodate increased use or overcome hardware problems - your "ibmx346" could suddenly be running on an xSeries x3650). What we feel are safe names for ''any'' machine in your network are true names, perhaps linked to a common theme: names of European cities, names of movie characters, names of countries or holiday destinations et cetera. Immediately following comes the question of the Domain Name. This is about a DNS domain, so effectively the installation program is asking which DNS suffix the host name should have; if the DHCP-server already provided something it'll be suggested, but you can override it if need be. In the preparatory phase, you'll have decided on continuation of your current DNS schema, or starting a new one. Either way, put the chosen DNS suffix in and press &lt;enter&gt;. ==Partitioning== Next comes the question of partitioning, or how to divide the available disk space into chunks for the server to use. This is a tricky subject, because if you put all storage space into one partition, then some day a runaway process will fill up the entire disk with useless logs, and the system will crash. On the other hand, if you divvy up all space into little chunks, then some application is going to need space in one of those partitions where there is none, even though there may be plenty in other partitions. To prevent both problems from occuring, we're going to use [http://tldp.org/HOWTO/LVM-HOWTO/whatisvolman.html Logical Volume Management (LVM)] so that we can provision enough space to start our server, but keep some space in reserve to apply when needed, where it'll be needed. So, we at Saruman.biz have put together a recommended standard partitioning scheme. The basis is this: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Partition !style="background:#ffdead;"|MD !style="background:#ffdead;"|LVG !style="background:#ffdead;"|LV-name !style="background:#ffdead;"|Size <br> (physical machine) !style="background:#ffdead;"|Size (VM) !style="background:#ffdead;"|File System !style="background:#ffdead;"|Mount point |- | 1 | /dev/md0 | &nbsp; | &nbsp; | 100MiB | 100MiB | ext3 | /boot |- | 2 | /dev/md1 | &nbsp; | &nbsp; | 3GiB | 1GiB | ext3 | / |- | rowspan="7" valign="top" | 3 | rowspan="7" valign="top" | /dev/md2 | rowspan="7" valign="top" style="background:lightgrey"| system | style="background:lightgrey" | swap | 1GiB<ref name="swap">Rule of thumb: twice the size of the machine's RAM, but no less than 256MiB and no more than 2GiB</ref> | 256MiB<ref name="swap"/> | swap | &nbsp; |- | style="background:lightgrey" | var | 2GiB | 1GiB | ext3 | /var |- | style="background:lightgrey" | appslog | 3GiB | - | ext3 | /var/appslog |- | style="background:lightgrey" | home | 1GiB<ref name="home">Note that this heavily depends on the purpose of the machine; if it is not to house any users, then (almost) no space is needed for /home. But on the other hand if e.g. a virtual user is to be used for keeping mailstores, or other service users need home space, then /home needs to be big enough for that.</ref> | 512MiB<ref name="home"/> | ext3 | /home |- | style="background:lightgrey" | usr | 3GiB | 3GiB | ext3 | /usr |- | style="background:lightgrey" | tmp | 1GiB | 512MiB | ext3 | /tmp |- | style="background:lightgrey" | opt | 1GiB | - | ext3 | /opt |- ! colspan="4" style="text-align:right"| Total ! 18.1GiB ! 6.9GiB ! colspan="2" | |- |} As you can see, the partition table works as follows: we assume that we wind up with 3 partitions, either on three separate software RAID arrays (''md0'' through ''md2'') or on one single hardware RAID array (in which case the 2nd column ''MD'' does not apply). The size of the partitions depends on your machine's make: for standard physical machines the 5th column does sensible suggestions, even though you could choose to have different sizes and of course different divisions altogether. If your machine happens to be a virtual one, running inside a [http://www.vmware.com/products/server/ VMware Server] or [http://www.vmware.com/products/vi/esx/ VMware ESX host], or the like, then you might want to start out with more modest partitions. The same holds for small servers that must run off Flash drives. Anyways, we're now at the Debian installation screen that lets us partition our disks. We're ''not'' going to use any of the "guided" partitionings, we go for "manual". Choosing that brings us to a screen showing all drives that the installation routine has detected, and all partitions on those drives that the installer can "see". We're going to do some assuming here once more: let's assume the drive(s) on which you want to install are visible, and are empty (containing no other partitions). <references/> ===Software RAID partitioning=== If you're to use software RAID, you now have to select the free space on the first drive, press &lt;enter&gt;, and then tell what you want to do with the free space: create a new partition, tell which size you want it to be (see table above), give the type of partition (primary), and give where on the disk it'll sit (the beginning). Next, a screen comes up that details how the partition you're requesting will be created. Here we make some changes: under "use as" we're going to select "physical volume for RAID". This clears all the other options in this screen, except for the "bootable" flag, which must be "on" for the first partition that we'll mount as ''/boot''. Now select "Done setting up the partition". Next, go to the free space on the second disk, and do ''exactly'' the same, to create an identical physical volume for RAID - if it's the first partition, select the "bootable" flag as well (we'll want to be able to boot from this second disk if the first disk fails, right?). Then go back to the rest of the free space on the first disk, make the second physical volume for RAID, duplicate it on the second disk. Then, go back to the rest of the free space on the first disk, make the third physical volume for RAID, and again duplicate it on the second disk. If you now go back to the "partition disks" overview, you'll see all the partitions you've specified listed on their respective disks. But at the top an extra option has appeared, called "configure software RAID". When you now select this option, the installer will ask if it may write the changes you've made to disk. This actually creates the partition tables on the disks. ===Hardware RAID partitioning=== Now, if you have hardware RAID, then on your first (boot) disk just make 3 partitions, in the following manner: Select the free space on the intended boot disk, press &lt;enter&gt;, select "create a new partition", and fill out the desired size (100MB). Type is primary, location is beginning of the disk, and in the details of the partition, we only need to change the Mount point to "/boot", and set the Bootable flag to "On". Then we're "Done setting up this partition". The second partition is made the same way, but the desired size is 3GB, the Mount point is "/", and the Bootable flag remains off. Again, we're "Done setting up this partition". The third partition is again a primary partition, it takes up the entire rest of the disk, but the type is not ext3, but "physical volume for LVM". Again, we're "Done setting up this partition". But now from the main partitioner screen, we can access "Configure the Logical Volume Manager". The installer asks if it can write out the choices made to the disk, and then enters the LVM setup screen, which begins with a summary explaining that you have one Free Physical Volume, and nothing more. We now create a Volume Group (VG), which (in accordance to our partitioning standard) we'll call "system". In this VG, we'll add all Physical Volumes (being the one partition we've designated so in the previous step) using the space bar. Now we repeat the following process seven times: * select "Create Logical Volume" * select Volume Group "System" * give the LV Name (from the table, e.g. swap, var etc) * give the LV size (from the table, e.g. 1GB for swap etc) After this, we can select "Finish", the partitioner creates the seven LVs, and we're back at the partitioner screen, where there are now 7 extra "disks", with names such as ''LVM VG system, LV appslog - 3.2GB Linux device mapper''. Each of these "disks" has one block of empty space, which we now assign: seven times we repeat the following process: * select the unassigned chunk of empty space of an LV (e.g. appslog) and press &lt;enter&gt;; * Change "Use as: do not use" into the desired filesystem (ext3 - only the LV "swap" gets as filesystem type "swap area") * Change the mount point from "none" to the one corresponding with the name of the LV (note: the swap LV has no mountpoint; the appslog mountpoint must be entered manually as "/var/appslog") * If so desired, a label can be assigned to the partition (we usually don't) * select "Done setting up the partition" Once all this is done, we can look over the configuration once more, and then select "Finish partitioning and write changes to disk". A summary configuration screen will show, and we'll affirm with "yes" that these partitions can indeed be formatted. After some formatting screens flashing by (unless your partitions are particularly big, your system is particularly slow, or something goes wrong) the installation procedure continues. ==Further installation== Next comes one '''VERY''' important question: what to use as root password? We cannot stress this enough: choose a SAFE password! Do NOT go for an easy-to-remember one, go for STRONG and SAFE. There are tools to help you generate strong passwords, like [http://www.pctools.com/guides/password/ this page]: use them! We strongly suggest 10 characters or more, including letters, mixed case, and numbers, so something like ''SuCRe4hecH'' (do NOT use this, generate your own!). Next, give the full name of the principal user of this server (your own, we assume), give the login-name (your given name, we assume), and a corresponding password. Again, use a SAFE password. As long as you don't make your principal user equivalent to root, you might go for a slightly weaker password (8 characters instead of 10), but we rather suggest you make the password just as strong (and different from!) the root password. Suppose you generate 447d39fbe71792538155aafef2809bcd81ad74e7 1437 1436 2008-05-12T20:30:08Z Saruman! 2 Added "finishing up the installation" wikitext text/x-wiki <big>'''Debian Etch Base Server setup'''</big> ==Getting the hardware== {| class="wikitable" border="1" |- |Note: in the following we're assuming you'll be assembling an x86 or x64 type of machine, as it has about the best price/performance ratio you could wish. Hardware costs for other platforms, e.g. IBM's Series p or HP 9000, can be much higher, while platforms like ARM are just not very powerful. Also, the availability of components and of help can be less than with the ubiquietous x86/x64 platforms. |} Naturally, before we can begin to install the operating system, we need to obtain the necessary hardware. Which hardware you require depends on what you want the server for; a testserver on which you will test only a single feature for a short while does not need the same quality of hardware as does a server that's supposed to act as a homeserver for many tasks for a long time. We'll assume your server will be like ours: a home server that must perform many tasks with sufficient performance for a few users, that's reliable and will last for a couple of years. So build or obtain a server with at least the following hardware: * a spacious casing with big, quiet cooling fans, like the [http://www.coolermaster.com/products/product.php?act=detail&id=317 one we have]; * an efficient, heavy-duty power supply that's rated high enough for your devices, and has a decent efficiency. For example, a [http://www.corsair.com/products/power_supplies.aspx Corsair HX520] power supply; * a server class motherboard, e.g. an [http://www.intel.com/products/server/index.htm?iid=home+hdr_nav2_server Intel] or [http://uk.asus.com/products.aspx?l1=9&l2=39&l3=263 AMD] based single-processor motherboard. DO NOT go for the cheapest motherboard you can find: if you pay peanuts, that's what you get. Server class motherboards have the quality, stability and durability you'll need from it, and usually also most of the needed peripherals, like multiple ethernet network cards on-board. Usually a Linux server doesn not require much in the way of video performance (and the screen will be used rarely, if ever), so any old integrated graphics will do. * a matching CPU - or multiple, if you think you need the power and the selected motherboard has the sockets. * a CD-ROM- or DVD-player * ''multiple'' harddisks - you'll want redundancy, because every harddisk fails at some time. The drive with your data on it will fail fatally when it is most inconvenient to you, and any data on it that you consider valuable will likely be lost forever. To make Murphy's work somewhat harder for him, we're going to store our data redundantly, so that if any drive in the server fails, we'll not lose our data or our server. Thus, get yourself at least two harddisks for your operating system, at least 40GiB in size (don't think you'll be able to buy smaller ones nowadays), and spanking new (NEVER use old harddisks for your production server, new ones are just too cheap to run that risk!). * (multipe) network card(s) (NICs) if your motherboard does not have enough NICs integrated on-board. You'll want a NIC for your network, and another one for your Internet connection; and possible a third one for the wireless segment of your network. Now build a machine out of the above, or have someone build it for you. ==Preparation of the hardware== (Note: in the following we're again assuming you're running an x86/x64 type of machine. Hardware requirements and preparation for other platforms, e.g. IBM's Series p or HP 9000, can differ significantly) Next, check the assembled hardware: * is the configuration complete? If it does not have a CD/DVDplayer from which it can boot, then installing the software gets more difficult - at least get an USB external DVDdrive or something like that. * are all components connected properly (memory DIMMs seated correctly in their sockets, AGP card inserted correctly into the AGP slot, et cetera) and are all cable connections made (multiple power cables to the motherboard, one power cable plus one data cable to each hard disk, etcetera)? Following this, you may hook up the machine. It's going to need power, and you will need at least a keyboard and a monitor attached. And if you want to use a Graphic User Interface to install, a mouse is required also. When you've ensured that everything is safe, you can turn on the machine, and continue to check it: * do all fans start to run when you turn on the machine? (if not, then '''quickly''' turn off your machine and correct the problem!) * does/do the hard disk(s) spin up? * do the power button and reset button operate correctly? * are the power led, HDD led and other display gadgetry functional? * when you let the machine power up, does it emit a single beep? And does it then show a Power-On Self Test screen (POST)? * Does it show the correct amount of memory in the POST screen? The correct number & speed of the CPU(s)? * Does the machine recognise all controller cards (SCSI, S-ATA etc)? And all attached DVD-drives and hard disks? * are all BIOSes/firmwares up to date? * If you have a hardware RAID controller, are your RAID arrays built already? * does the machine attempt to boot from at least the hard disk? ...et cetera. If there is any problem, or you want to update the BIOS or firmwares, it's best to do it before the operating system is installed. This Wiki, however, is not the place (yet) to get the information on how to accomplish these type of tasks. The last steps in the preparation of the hardware, are * to ensure that the machine can boot from CD/DVD, so that you can start installing Debian from it. It is possible to install Debian over the network, but that requires setting up a [http://www.debian-administration.org/articles/478 PXE Boot server] which is (currently) outside the scope of this wiki. * to connect the hardware to the Internet, so that it can get all required updates etcetera; please do ''not'' connect the box ''straight'' to the Internet, but make sure that it's safely behind a firewall, or failing that, a NAT router. By now the system should be almost ready to receive it's Operating System. But first we have an issue to tackle: that of redundancy. ==Software or hardware RAID== Your hard disks will fail. They absolutely will. It is never a question of "if", only of "when". So what will you do when the hard disk containing your complete operating system fails (besides pulling your hair out, that is)? What we propose is this: hard disks are pretty cheap nowadays, so let's use [http://en.wikipedia.org/wiki/Redundant_array_of_independent_disks RAID technology] to make our hard drive space resilient against failure of a whole drive. So first make sure that you have ''two'' disks of equal size instead of only one. Had you already been planning to use multiple disks already, then make sure you have at least ''one'' disk more than your space requirements prescribe; the space on that extra drive will provide the needed redundancy. Next, [[RAID fundamentals under Linux | click here]] to learn a bit more about RAID, to make the decision to use hardware-based and/or software-based RAID, and to plan your RAID arrays. In this example, we'll assume you're using hardware RAID on a RAID controller that's supported by the Debian installation software. This means that the installation software will "see" your RAID array(s) and present them as usable drives. ==Planning your network names== If your machine must become a part of an existing network, then it's almost certain that you already have a DNS domain in place; in that case: obtain the DNS suffix your machine will get (the DNS domain your machine will "belong" to). However, it's also possible that this machine is going to be the first machine in your new network, in which case the whole issue of DNS suffixes is wide open. If you need more information on DNS, go [[http://www.isc.org/sw/bind/arm95/Bv9ARM-all.html#id2564824 here]]. For now we'll assume you have (or will quickly obtain) a working knowledge of the DNS system. Here is our tip on choosing a DNS domain for your home network: * do '''not''' use a publicly registered domain name (e.g. "cocacola.com") for any machine that's not primarily intended to serve the public on the Internet; * for machines serving a private network, we urge you to use Top Level Domain name "lan" (to signify your machine is on a Local Area Network or LAN) * for the Domain Name itself, we suggest you use a level 2 name, like "saruman.lan", and not a level 3 name, like "mister.saruman.lan". This is only a short section on DNS, but remember that once a proper DNS system is in place, it's pretty much work to change it. At any rate, this section has most likely showed you that you need to put some thought into the DNS Domain Name design of your home network. OK, with this out of the way, we can get to installing the OS. ==Operating System installation== To install an Operating System (OS), it's kinda instrumental that you have one. Here, we're going to use [http://www.debian.org/intro/about Debian], the biggest [http://www.debian.org/intro/about#free Free] OS that we know of. Free stands for Freedom, but incidentally that Freedom also means it's gratis, an appealing aspect of Free. To get your own copy of Debian, go to their [http://www.debian.org/distrib/ download site] and obtain the latest [http://www.debian.org/releases/ Stable] image - in this wiki it's Debian 4.0, or "Etch" as it's also known. Besides the choice which release of Debian you want to run, you also have to know for which platform you're downloading (in our case: either ''amd64'' or ''i386'' depending on your hardware platform) and what kind of install you wish - if you have a working, fast Internet connection available at the time of install, then we recommend getting the [[http://www.debian.org/CD/netinst/ netinst] CD image; it's a relatively small CD, that'll be able to get you going, but gets most of the software you'll need straight from the 'net at install time. So, since in the example at hand we're installing on a Xeon server on which we wish to install 32-bits software, we'll download [http://cdimage.debian.org/debian-cd/4.0_r3/i386/iso-cd/debian-40r3-i386-netinst.iso debian-40r3-i386-netinst.iso], the latest netinstall image at the time of writing. Burn this to a CD-recordable and boot your prepared hardware platform from this CD. After booting from the CD, a friendly prompt invites you to indicate how you want to boot the CD. Your choices are listed under &lt;F3&gt;; we're going to use the standard Command Line installation, so we type "install"&lt;enter&gt; or just simply &lt;enter&gt;. {| class="wikitable" border="1" |- |We could easily use "installgui", in which case we'd have a nice fresh Graphical User Interface for our installation. ''We're'' not going to, because we're real men, and [http://isg.ee.ethz.ch/tools/realmen/ Real Men Don't Click]. Also, we've found that from the GUI it's hard to switch to a second console and then back. We could also opt for "expert" as installation method, because it gives a much finer grain of control, but we usually don't need that control, and can do without the barrage of extra questions that the "expert" installation method pose. Finally, we could opt for "expertgui", where we have both the barrage of extra questions ''and'' the GUI, neither of which we need. |} After the Linux kernel finishes initializing the machine, a simple text-based installer appears that immediately starts asking questions. Answer them according to your needs. Our example system uses the following choices: * Language: english * country: other &gt; Netherlands * keymap: American English (since we have a keyboard with US layout) Some installation software loads, and we get to the next phase: if you have multiple NICs in your machine (which we believe you ''should'' have!!), and if they're detected properly, then you're required to indicate which of the detected network interface cards (NIC) is going to be the "primary" NIC. {| class="wikitable" border="1" |- |Here, trouble could begin. If your machine has network cards that are '''not''' supported, then you'll see '''no''' cards here - but then how are you going to do a NetInstall? A solution would be to (temporarily) install a NIC that ''is'' supported, like a cheap Realtek card, or an old 3Com 905 card. Then, when the whole system is installed, up and running, you could compile a new kernel that contains support for your actual NICs, and when these work, remove the temporary NIC. For now, we'll assume that at least one of your NICs is recognised properly by the Debian installation routine. |} Select the card that's connected and has (indirect) access to Internet (again: it should ''not'' be connected straight to the wild wild web, but sit safely behind a firewall, at least until we've installed our own firewall); if at all possible, let it be the NIC that'll be connected to your home network itself, on the ''inside'' of your server. Let's assume that this NIC is designated ''eth0'' by the Debian installation. This card will now be configured using DHCP, so if you're on a network with a DHCP-server, the network will work straight away. If it's not, you can either configure the network manually or fix your DHCP-server and connection between it and ''eth0''. Next is one of the hardest questions that any OS installation is going to ask you: what will be the host name of the system? You could change it at any time in the future, but with lots of hassle, so you better choose wisely. Here are our tips: * do '''not''' name your machine after the user that's going to use it, e.g. "bernie-pc" (at some time in the future, Bernie's machine will be moved to Alice, so then Alice is working on "bernie-pc" which makes the situation quite unclear); * do '''not''' name your machine after the department or workgroup that's using it most, e.g. "accounting-srv" (same reasoning); * do '''not''' name your machine after it's main function, e.g. "printserver" (at some time in the future, the main function is moved to another machine, and/or an alternative function will become the main function of the machine); * do '''not''' name your machine after it's location, e.g. "srv-boston" (at some time in the future, the box will be moved to another location); * do '''not''' name your machine after it's hardware configuration, e.g. "ibmx346" (at some time in the future, either another xSeries x346 will be wheeled in, or the machine will be upgraded to accomodate increased use or overcome hardware problems - your "ibmx346" could suddenly be running on an xSeries x3650). What we feel are safe names for ''any'' machine in your network are true names, perhaps linked to a common theme: names of European cities, names of movie characters, names of countries or holiday destinations et cetera. Immediately following comes the question of the Domain Name. This is about a DNS domain, so effectively the installation program is asking which DNS suffix the host name should have; if the DHCP-server already provided something it'll be suggested, but you can override it if need be. In the preparatory phase, you'll have decided on continuation of your current DNS schema, or starting a new one. Either way, put the chosen DNS suffix in and press &lt;enter&gt;. ==Partitioning== Next comes the question of partitioning, or how to divide the available disk space into chunks for the server to use. This is a tricky subject, because if you put all storage space into one partition, then some day a runaway process will fill up the entire disk with useless logs, and the system will crash. On the other hand, if you divvy up all space into little chunks, then some application is going to need space in one of those partitions where there is none, even though there may be plenty in other partitions. To prevent both problems from occuring, we're going to use [http://tldp.org/HOWTO/LVM-HOWTO/whatisvolman.html Logical Volume Management (LVM)] so that we can provision enough space to start our server, but keep some space in reserve to apply when needed, where it'll be needed. So, we at Saruman.biz have put together a recommended standard partitioning scheme. The basis is this: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Partition !style="background:#ffdead;"|MD !style="background:#ffdead;"|LVG !style="background:#ffdead;"|LV-name !style="background:#ffdead;"|Size <br> (physical machine) !style="background:#ffdead;"|Size (VM) !style="background:#ffdead;"|File System !style="background:#ffdead;"|Mount point |- | 1 | /dev/md0 | &nbsp; | &nbsp; | 100MiB | 100MiB | ext3 | /boot |- | 2 | /dev/md1 | &nbsp; | &nbsp; | 3GiB | 1GiB | ext3 | / |- | rowspan="7" valign="top" | 3 | rowspan="7" valign="top" | /dev/md2 | rowspan="7" valign="top" style="background:lightgrey"| system | style="background:lightgrey" | swap | 1GiB<ref name="swap">Rule of thumb: twice the size of the machine's RAM, but no less than 256MiB and no more than 2GiB</ref> | 256MiB<ref name="swap"/> | swap | &nbsp; |- | style="background:lightgrey" | var | 2GiB | 1GiB | ext3 | /var |- | style="background:lightgrey" | appslog | 3GiB | - | ext3 | /var/appslog |- | style="background:lightgrey" | home | 1GiB<ref name="home">Note that this heavily depends on the purpose of the machine; if it is not to house any users, then (almost) no space is needed for /home. But on the other hand if e.g. a virtual user is to be used for keeping mailstores, or other service users need home space, then /home needs to be big enough for that.</ref> | 512MiB<ref name="home"/> | ext3 | /home |- | style="background:lightgrey" | usr | 3GiB | 3GiB | ext3 | /usr |- | style="background:lightgrey" | tmp | 1GiB | 512MiB | ext3 | /tmp |- | style="background:lightgrey" | opt | 1GiB | - | ext3 | /opt |- ! colspan="4" style="text-align:right"| Total ! 18.1GiB ! 6.9GiB ! colspan="2" | |- |} As you can see, the partition table works as follows: we assume that we wind up with 3 partitions, either on three separate software RAID arrays (''md0'' through ''md2'') or on one single hardware RAID array (in which case the 2nd column ''MD'' does not apply). The size of the partitions depends on your machine's make: for standard physical machines the 5th column does sensible suggestions, even though you could choose to have different sizes and of course different divisions altogether. If your machine happens to be a virtual one, running inside a [http://www.vmware.com/products/server/ VMware Server] or [http://www.vmware.com/products/vi/esx/ VMware ESX host], or the like, then you might want to start out with more modest partitions. The same holds for small servers that must run off Flash drives. Anyways, we're now at the Debian installation screen that lets us partition our disks. We're ''not'' going to use any of the "guided" partitionings, we go for "manual". Choosing that brings us to a screen showing all drives that the installation routine has detected, and all partitions on those drives that the installer can "see". We're going to do some assuming here once more: let's assume the drive(s) on which you want to install are visible, and are empty (containing no other partitions). <references/> ===Software RAID partitioning=== If you're to use software RAID, you now have to select the free space on the first drive, press &lt;enter&gt;, and then tell what you want to do with the free space: create a new partition, tell which size you want it to be (see table above), give the type of partition (primary), and give where on the disk it'll sit (the beginning). Next, a screen comes up that details how the partition you're requesting will be created. Here we make some changes: under "use as" we're going to select "physical volume for RAID". This clears all the other options in this screen, except for the "bootable" flag, which must be "on" for the first partition that we'll mount as ''/boot''. Now select "Done setting up the partition". Next, go to the free space on the second disk, and do ''exactly'' the same, to create an identical physical volume for RAID - if it's the first partition, select the "bootable" flag as well (we'll want to be able to boot from this second disk if the first disk fails, right?). Then go back to the rest of the free space on the first disk, make the second physical volume for RAID, duplicate it on the second disk. Then, go back to the rest of the free space on the first disk, make the third physical volume for RAID, and again duplicate it on the second disk. If you now go back to the "partition disks" overview, you'll see all the partitions you've specified listed on their respective disks. But at the top an extra option has appeared, called "configure software RAID". When you now select this option, the installer will ask if it may write the changes you've made to disk. This actually creates the partition tables on the disks. ===Hardware RAID partitioning=== Now, if you have hardware RAID, then on your first (boot) disk just make 3 partitions, in the following manner: Select the free space on the intended boot disk, press &lt;enter&gt;, select "create a new partition", and fill out the desired size (100MB). Type is primary, location is beginning of the disk, and in the details of the partition, we only need to change the Mount point to "/boot", and set the Bootable flag to "On". Then we're "Done setting up this partition". The second partition is made the same way, but the desired size is 3GB, the Mount point is "/", and the Bootable flag remains off. Again, we're "Done setting up this partition". The third partition is again a primary partition, it takes up the entire rest of the disk, but the type is not ext3, but "physical volume for LVM". Again, we're "Done setting up this partition". But now from the main partitioner screen, we can access "Configure the Logical Volume Manager". The installer asks if it can write out the choices made to the disk, and then enters the LVM setup screen, which begins with a summary explaining that you have one Free Physical Volume, and nothing more. We now create a Volume Group (VG), which (in accordance to our partitioning standard) we'll call "system". In this VG, we'll add all Physical Volumes (being the one partition we've designated so in the previous step) using the space bar. Now we repeat the following process seven times: * select "Create Logical Volume" * select Volume Group "System" * give the LV Name (from the table, e.g. swap, var etc) * give the LV size (from the table, e.g. 1GB for swap etc) After this, we can select "Finish", the partitioner creates the seven LVs, and we're back at the partitioner screen, where there are now 7 extra "disks", with names such as ''LVM VG system, LV appslog - 3.2GB Linux device mapper''. Each of these "disks" has one block of empty space, which we now assign: seven times we repeat the following process: * select the unassigned chunk of empty space of an LV (e.g. appslog) and press &lt;enter&gt;; * Change "Use as: do not use" into the desired filesystem (ext3 - only the LV "swap" gets as filesystem type "swap area") * Change the mount point from "none" to the one corresponding with the name of the LV (note: the swap LV has no mountpoint; the appslog mountpoint must be entered manually as "/var/appslog") * If so desired, a label can be assigned to the partition (we usually don't) * select "Done setting up the partition" Once all this is done, we can look over the configuration once more, and then select "Finish partitioning and write changes to disk". A summary configuration screen will show, and we'll affirm with "yes" that these partitions can indeed be formatted. After some formatting screens flashing by (unless your partitions are particularly big, your system is particularly slow, or something goes wrong) the installation procedure continues. ==Final installer steps== Next comes one '''VERY''' important question: what to use as root password? We cannot stress this enough: choose a SAFE password! Do NOT go for an easy-to-remember one, go for STRONG and SAFE. There are tools to help you generate strong passwords, like [http://www.pctools.com/guides/password/ this page]: use them! We strongly suggest 10 characters or more, including letters, mixed case, and numbers, so something like ''SuCRe4hecH'' (do NOT use this, generate your own!). Next, give the full name of the principal user of this server (your own, we assume), give the login-name (your given name, we assume), and a corresponding password. Again, use a SAFE password. As long as you don't make your principal user equivalent to root, you might go for a slightly weaker password (8 characters instead of 10), but we rather suggest you make the password just as strong (and different from!) the root password. After entering the details of these two users "root" and "you", the Debian installer will ask you how it can contact the Debian archives, in the dialoge "configure the package manager". For the NetInstall version of Debian, this is as good as mandatory. So here, we say "yes, use a Network Mirror", and in the following list select the country in which we are (in our case: the Netherlands), so the installer can present us with a number of network mirrors "close by". We select ftp.nl.debian.org. Next screen: should you be behind a proxy server, then it's possible to specify that here. And then the test: the system will say "scanning the mirror..." and try to contact the specified mirror. If it does not succeed, then there is either a network problem, a problem with this box's network card, or you've not specified the mirror or proxy correctly - so fix it. You'll know the network mirror has succesfully been contacted when the next dialogue appears - currently "configuring popularity-contest". Answer this question as you please. And then one of the last "big" questions: Software Selection. In this dialogue, you can easily select bundles of software to be installed. The choices are currently: * Desktop environment * Web server * Print server * DNS server * File server * Mail server * SQL database * Laptop * Standard system (selected by default) We have to make a little confession here: we've never before used this option in the installer. In fact, we even deselect the Standard System, so as to minimize the number of software packages that the base installation of our server contains. This makes it more work to manually add packages later, but we feel it gives us more control and understanding of our systems. So if you are like us: deselect the Standard System entry, and select Continue. The next dialogue handles the installation of the [http://www.gnu.org/software/grub/ ''grub'' bootloader]. Unless your disks weren't empty and you're attempting to make this system multiboot, you'll most likely get a question if you'll allow the installer to install ''grub'' into the boot sector of the first hard disk. We'll confirm with "Yes". After the installation of grub is completed, the CD-ROM is ejected, and the system is ready to reboot into Debian Etch. Remove the CD and select "Continue" ==Finishing up the installation== The system should reboot into Debian. This means you should see the following boot sequence: * your machine's standard POST messages * then, a blue grub menu on a black screen, with two entries: ** Debian GNU/Linux, kernel 2.6.&lt;something&gt; ** Debian GNU/Linux, kernel 2.6.&lt;something&gt (single-user mode); * then, after a default time-out, the first grub option will go into effect, and the Linux kernel is started. Lots of cryptic messages in grey-on-black will scroll by, until the last few lines read: "Debian GNU/Linux 4.0 &lt;hostname&gt; tty1" and "&lt;hostname&gt; login:" If your system does not reach this login, and/or some horrible error messages appear anywhere in this boot sequence, then you've got some extra work ahead. For now we'll assume you've reached the login prompt without problem. Log in as the principal user (try to avoid logging in as root! That's BAD practice!). Once logged in, save a copy of the boot messages using ''dmesg > boot.txt'' or whatever you like. Then look through the boot messages, e.g. with ''vi -R boot.txt''. 926c67769916d642cc5d8b5a8ec47dfb32723a08 1438 1437 2008-05-17T13:20:18Z Saruman! 2 /* Finishing up the installation */ wikitext text/x-wiki <big>'''Debian Etch Base Server setup'''</big> ==Getting the hardware== {| class="wikitable" border="1" |- |Note: in the following we're assuming you'll be assembling an x86 or x64 type of machine, as it has about the best price/performance ratio you could wish. Hardware costs for other platforms, e.g. IBM's Series p or HP 9000, can be much higher, while platforms like ARM are just not very powerful. Also, the availability of components and of help can be less than with the ubiquietous x86/x64 platforms. |} Naturally, before we can begin to install the operating system, we need to obtain the necessary hardware. Which hardware you require depends on what you want the server for; a testserver on which you will test only a single feature for a short while does not need the same quality of hardware as does a server that's supposed to act as a homeserver for many tasks for a long time. We'll assume your server will be like ours: a home server that must perform many tasks with sufficient performance for a few users, that's reliable and will last for a couple of years. So build or obtain a server with at least the following hardware: * a spacious casing with big, quiet cooling fans, like the [http://www.coolermaster.com/products/product.php?act=detail&id=317 one we have]; * an efficient, heavy-duty power supply that's rated high enough for your devices, and has a decent efficiency. For example, a [http://www.corsair.com/products/power_supplies.aspx Corsair HX520] power supply; * a server class motherboard, e.g. an [http://www.intel.com/products/server/index.htm?iid=home+hdr_nav2_server Intel] or [http://uk.asus.com/products.aspx?l1=9&l2=39&l3=263 AMD] based single-processor motherboard. DO NOT go for the cheapest motherboard you can find: if you pay peanuts, that's what you get. Server class motherboards have the quality, stability and durability you'll need from it, and usually also most of the needed peripherals, like multiple ethernet network cards on-board. Usually a Linux server doesn not require much in the way of video performance (and the screen will be used rarely, if ever), so any old integrated graphics will do. * a matching CPU - or multiple, if you think you need the power and the selected motherboard has the sockets. * a CD-ROM- or DVD-player * ''multiple'' harddisks - you'll want redundancy, because every harddisk fails at some time. The drive with your data on it will fail fatally when it is most inconvenient to you, and any data on it that you consider valuable will likely be lost forever. To make Murphy's work somewhat harder for him, we're going to store our data redundantly, so that if any drive in the server fails, we'll not lose our data or our server. Thus, get yourself at least two harddisks for your operating system, at least 40GiB in size (don't think you'll be able to buy smaller ones nowadays), and spanking new (NEVER use old harddisks for your production server, new ones are just too cheap to run that risk!). * (multipe) network card(s) (NICs) if your motherboard does not have enough NICs integrated on-board. You'll want a NIC for your network, and another one for your Internet connection; and possible a third one for the wireless segment of your network. Now build a machine out of the above, or have someone build it for you. ==Preparation of the hardware== (Note: in the following we're again assuming you're running an x86/x64 type of machine. Hardware requirements and preparation for other platforms, e.g. IBM's Series p or HP 9000, can differ significantly) Next, check the assembled hardware: * is the configuration complete? If it does not have a CD/DVDplayer from which it can boot, then installing the software gets more difficult - at least get an USB external DVDdrive or something like that. * are all components connected properly (memory DIMMs seated correctly in their sockets, AGP card inserted correctly into the AGP slot, et cetera) and are all cable connections made (multiple power cables to the motherboard, one power cable plus one data cable to each hard disk, etcetera)? Following this, you may hook up the machine. It's going to need power, and you will need at least a keyboard and a monitor attached. And if you want to use a Graphic User Interface to install, a mouse is required also. When you've ensured that everything is safe, you can turn on the machine, and continue to check it: * do all fans start to run when you turn on the machine? (if not, then '''quickly''' turn off your machine and correct the problem!) * does/do the hard disk(s) spin up? * do the power button and reset button operate correctly? * are the power led, HDD led and other display gadgetry functional? * when you let the machine power up, does it emit a single beep? And does it then show a Power-On Self Test screen (POST)? * Does it show the correct amount of memory in the POST screen? The correct number & speed of the CPU(s)? * Does the machine recognise all controller cards (SCSI, S-ATA etc)? And all attached DVD-drives and hard disks? * are all BIOSes/firmwares up to date? * If you have a hardware RAID controller, are your RAID arrays built already? * does the machine attempt to boot from at least the hard disk? ...et cetera. If there is any problem, or you want to update the BIOS or firmwares, it's best to do it before the operating system is installed. This Wiki, however, is not the place (yet) to get the information on how to accomplish these type of tasks. The last steps in the preparation of the hardware, are * to ensure that the machine can boot from CD/DVD, so that you can start installing Debian from it. It is possible to install Debian over the network, but that requires setting up a [http://www.debian-administration.org/articles/478 PXE Boot server] which is (currently) outside the scope of this wiki. * to connect the hardware to the Internet, so that it can get all required updates etcetera; please do ''not'' connect the box ''straight'' to the Internet, but make sure that it's safely behind a firewall, or failing that, a NAT router. By now the system should be almost ready to receive it's Operating System. But first we have an issue to tackle: that of redundancy. ==Software or hardware RAID== Your hard disks will fail. They absolutely will. It is never a question of "if", only of "when". So what will you do when the hard disk containing your complete operating system fails (besides pulling your hair out, that is)? What we propose is this: hard disks are pretty cheap nowadays, so let's use [http://en.wikipedia.org/wiki/Redundant_array_of_independent_disks RAID technology] to make our hard drive space resilient against failure of a whole drive. So first make sure that you have ''two'' disks of equal size instead of only one. Had you already been planning to use multiple disks already, then make sure you have at least ''one'' disk more than your space requirements prescribe; the space on that extra drive will provide the needed redundancy. Next, [[RAID fundamentals under Linux | click here]] to learn a bit more about RAID, to make the decision to use hardware-based and/or software-based RAID, and to plan your RAID arrays. In this example, we'll assume you're using hardware RAID on a RAID controller that's supported by the Debian installation software. This means that the installation software will "see" your RAID array(s) and present them as usable drives. ==Planning your network names== If your machine must become a part of an existing network, then it's almost certain that you already have a DNS domain in place; in that case: obtain the DNS suffix your machine will get (the DNS domain your machine will "belong" to). However, it's also possible that this machine is going to be the first machine in your new network, in which case the whole issue of DNS suffixes is wide open. If you need more information on DNS, go [[http://www.isc.org/sw/bind/arm95/Bv9ARM-all.html#id2564824 here]]. For now we'll assume you have (or will quickly obtain) a working knowledge of the DNS system. Here is our tip on choosing a DNS domain for your home network: * do '''not''' use a publicly registered domain name (e.g. "cocacola.com") for any machine that's not primarily intended to serve the public on the Internet; * for machines serving a private network, we urge you to use Top Level Domain name "lan" (to signify your machine is on a Local Area Network or LAN) * for the Domain Name itself, we suggest you use a level 2 name, like "saruman.lan", and not a level 3 name, like "mister.saruman.lan". This is only a short section on DNS, but remember that once a proper DNS system is in place, it's pretty much work to change it. At any rate, this section has most likely showed you that you need to put some thought into the DNS Domain Name design of your home network. OK, with this out of the way, we can get to installing the OS. ==Operating System installation== To install an Operating System (OS), it's kinda instrumental that you have one. Here, we're going to use [http://www.debian.org/intro/about Debian], the biggest [http://www.debian.org/intro/about#free Free] OS that we know of. Free stands for Freedom, but incidentally that Freedom also means it's gratis, an appealing aspect of Free. To get your own copy of Debian, go to their [http://www.debian.org/distrib/ download site] and obtain the latest [http://www.debian.org/releases/ Stable] image - in this wiki it's Debian 4.0, or "Etch" as it's also known. Besides the choice which release of Debian you want to run, you also have to know for which platform you're downloading (in our case: either ''amd64'' or ''i386'' depending on your hardware platform) and what kind of install you wish - if you have a working, fast Internet connection available at the time of install, then we recommend getting the [[http://www.debian.org/CD/netinst/ netinst] CD image; it's a relatively small CD, that'll be able to get you going, but gets most of the software you'll need straight from the 'net at install time. So, since in the example at hand we're installing on a Xeon server on which we wish to install 32-bits software, we'll download [http://cdimage.debian.org/debian-cd/4.0_r3/i386/iso-cd/debian-40r3-i386-netinst.iso debian-40r3-i386-netinst.iso], the latest netinstall image at the time of writing. Burn this to a CD-recordable and boot your prepared hardware platform from this CD. After booting from the CD, a friendly prompt invites you to indicate how you want to boot the CD. Your choices are listed under &lt;F3&gt;; we're going to use the standard Command Line installation, so we type "install"&lt;enter&gt; or just simply &lt;enter&gt;. {| class="wikitable" border="1" |- |We could easily use "installgui", in which case we'd have a nice fresh Graphical User Interface for our installation. ''We're'' not going to, because we're real men, and [http://isg.ee.ethz.ch/tools/realmen/ Real Men Don't Click]. Also, we've found that from the GUI it's hard to switch to a second console and then back. We could also opt for "expert" as installation method, because it gives a much finer grain of control, but we usually don't need that control, and can do without the barrage of extra questions that the "expert" installation method pose. Finally, we could opt for "expertgui", where we have both the barrage of extra questions ''and'' the GUI, neither of which we need. |} After the Linux kernel finishes initializing the machine, a simple text-based installer appears that immediately starts asking questions. Answer them according to your needs. Our example system uses the following choices: * Language: english * country: other &gt; Netherlands * keymap: American English (since we have a keyboard with US layout) Some installation software loads, and we get to the next phase: if you have multiple NICs in your machine (which we believe you ''should'' have!!), and if they're detected properly, then you're required to indicate which of the detected network interface cards (NIC) is going to be the "primary" NIC. {| class="wikitable" border="1" |- |Here, trouble could begin. If your machine has network cards that are '''not''' supported, then you'll see '''no''' cards here - but then how are you going to do a NetInstall? A solution would be to (temporarily) install a NIC that ''is'' supported, like a cheap Realtek card, or an old 3Com 905 card. Then, when the whole system is installed, up and running, you could compile a new kernel that contains support for your actual NICs, and when these work, remove the temporary NIC. For now, we'll assume that at least one of your NICs is recognised properly by the Debian installation routine. |} Select the card that's connected and has (indirect) access to Internet (again: it should ''not'' be connected straight to the wild wild web, but sit safely behind a firewall, at least until we've installed our own firewall); if at all possible, let it be the NIC that'll be connected to your home network itself, on the ''inside'' of your server. Let's assume that this NIC is designated ''eth0'' by the Debian installation. This card will now be configured using DHCP, so if you're on a network with a DHCP-server, the network will work straight away. If it's not, you can either configure the network manually or fix your DHCP-server and connection between it and ''eth0''. Next is one of the hardest questions that any OS installation is going to ask you: what will be the host name of the system? You could change it at any time in the future, but with lots of hassle, so you better choose wisely. Here are our tips: * do '''not''' name your machine after the user that's going to use it, e.g. "bernie-pc" (at some time in the future, Bernie's machine will be moved to Alice, so then Alice is working on "bernie-pc" which makes the situation quite unclear); * do '''not''' name your machine after the department or workgroup that's using it most, e.g. "accounting-srv" (same reasoning); * do '''not''' name your machine after it's main function, e.g. "printserver" (at some time in the future, the main function is moved to another machine, and/or an alternative function will become the main function of the machine); * do '''not''' name your machine after it's location, e.g. "srv-boston" (at some time in the future, the box will be moved to another location); * do '''not''' name your machine after it's hardware configuration, e.g. "ibmx346" (at some time in the future, either another xSeries x346 will be wheeled in, or the machine will be upgraded to accomodate increased use or overcome hardware problems - your "ibmx346" could suddenly be running on an xSeries x3650). What we feel are safe names for ''any'' machine in your network are true names, perhaps linked to a common theme: names of European cities, names of movie characters, names of countries or holiday destinations et cetera. Immediately following comes the question of the Domain Name. This is about a DNS domain, so effectively the installation program is asking which DNS suffix the host name should have; if the DHCP-server already provided something it'll be suggested, but you can override it if need be. In the preparatory phase, you'll have decided on continuation of your current DNS schema, or starting a new one. Either way, put the chosen DNS suffix in and press &lt;enter&gt;. ==Partitioning== Next comes the question of partitioning, or how to divide the available disk space into chunks for the server to use. This is a tricky subject, because if you put all storage space into one partition, then some day a runaway process will fill up the entire disk with useless logs, and the system will crash. On the other hand, if you divvy up all space into little chunks, then some application is going to need space in one of those partitions where there is none, even though there may be plenty in other partitions. To prevent both problems from occuring, we're going to use [http://tldp.org/HOWTO/LVM-HOWTO/whatisvolman.html Logical Volume Management (LVM)] so that we can provision enough space to start our server, but keep some space in reserve to apply when needed, where it'll be needed. So, we at Saruman.biz have put together a recommended standard partitioning scheme. The basis is this: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Partition !style="background:#ffdead;"|MD !style="background:#ffdead;"|LVG !style="background:#ffdead;"|LV-name !style="background:#ffdead;"|Size <br> (physical machine) !style="background:#ffdead;"|Size (VM) !style="background:#ffdead;"|File System !style="background:#ffdead;"|Mount point |- | 1 | /dev/md0 | &nbsp; | &nbsp; | 100MiB | 100MiB | ext3 | /boot |- | 2 | /dev/md1 | &nbsp; | &nbsp; | 3GiB | 1GiB | ext3 | / |- | rowspan="7" valign="top" | 3 | rowspan="7" valign="top" | /dev/md2 | rowspan="7" valign="top" style="background:lightgrey"| system | style="background:lightgrey" | swap | 1GiB<ref name="swap">Rule of thumb: twice the size of the machine's RAM, but no less than 256MiB and no more than 2GiB</ref> | 256MiB<ref name="swap"/> | swap | &nbsp; |- | style="background:lightgrey" | var | 2GiB | 1GiB | ext3 | /var |- | style="background:lightgrey" | appslog | 3GiB | - | ext3 | /var/appslog |- | style="background:lightgrey" | home | 1GiB<ref name="home">Note that this heavily depends on the purpose of the machine; if it is not to house any users, then (almost) no space is needed for /home. But on the other hand if e.g. a virtual user is to be used for keeping mailstores, or other service users need home space, then /home needs to be big enough for that.</ref> | 512MiB<ref name="home"/> | ext3 | /home |- | style="background:lightgrey" | usr | 3GiB | 3GiB | ext3 | /usr |- | style="background:lightgrey" | tmp | 1GiB | 512MiB | ext3 | /tmp |- | style="background:lightgrey" | opt | 1GiB | - | ext3 | /opt |- ! colspan="4" style="text-align:right"| Total ! 18.1GiB ! 6.9GiB ! colspan="2" | |- |} As you can see, the partition table works as follows: we assume that we wind up with 3 partitions, either on three separate software RAID arrays (''md0'' through ''md2'') or on one single hardware RAID array (in which case the 2nd column ''MD'' does not apply). The size of the partitions depends on your machine's make: for standard physical machines the 5th column does sensible suggestions, even though you could choose to have different sizes and of course different divisions altogether. If your machine happens to be a virtual one, running inside a [http://www.vmware.com/products/server/ VMware Server] or [http://www.vmware.com/products/vi/esx/ VMware ESX host], or the like, then you might want to start out with more modest partitions. The same holds for small servers that must run off Flash drives. Anyways, we're now at the Debian installation screen that lets us partition our disks. We're ''not'' going to use any of the "guided" partitionings, we go for "manual". Choosing that brings us to a screen showing all drives that the installation routine has detected, and all partitions on those drives that the installer can "see". We're going to do some assuming here once more: let's assume the drive(s) on which you want to install are visible, and are empty (containing no other partitions). <references/> ===Software RAID partitioning=== If you're to use software RAID, you now have to select the free space on the first drive, press &lt;enter&gt;, and then tell what you want to do with the free space: create a new partition, tell which size you want it to be (see table above), give the type of partition (primary), and give where on the disk it'll sit (the beginning). Next, a screen comes up that details how the partition you're requesting will be created. Here we make some changes: under "use as" we're going to select "physical volume for RAID". This clears all the other options in this screen, except for the "bootable" flag, which must be "on" for the first partition that we'll mount as ''/boot''. Now select "Done setting up the partition". Next, go to the free space on the second disk, and do ''exactly'' the same, to create an identical physical volume for RAID - if it's the first partition, select the "bootable" flag as well (we'll want to be able to boot from this second disk if the first disk fails, right?). Then go back to the rest of the free space on the first disk, make the second physical volume for RAID, duplicate it on the second disk. Then, go back to the rest of the free space on the first disk, make the third physical volume for RAID, and again duplicate it on the second disk. If you now go back to the "partition disks" overview, you'll see all the partitions you've specified listed on their respective disks. But at the top an extra option has appeared, called "configure software RAID". When you now select this option, the installer will ask if it may write the changes you've made to disk. This actually creates the partition tables on the disks. ===Hardware RAID partitioning=== Now, if you have hardware RAID, then on your first (boot) disk just make 3 partitions, in the following manner: Select the free space on the intended boot disk, press &lt;enter&gt;, select "create a new partition", and fill out the desired size (100MB). Type is primary, location is beginning of the disk, and in the details of the partition, we only need to change the Mount point to "/boot", and set the Bootable flag to "On". Then we're "Done setting up this partition". The second partition is made the same way, but the desired size is 3GB, the Mount point is "/", and the Bootable flag remains off. Again, we're "Done setting up this partition". The third partition is again a primary partition, it takes up the entire rest of the disk, but the type is not ext3, but "physical volume for LVM". Again, we're "Done setting up this partition". But now from the main partitioner screen, we can access "Configure the Logical Volume Manager". The installer asks if it can write out the choices made to the disk, and then enters the LVM setup screen, which begins with a summary explaining that you have one Free Physical Volume, and nothing more. We now create a Volume Group (VG), which (in accordance to our partitioning standard) we'll call "system". In this VG, we'll add all Physical Volumes (being the one partition we've designated so in the previous step) using the space bar. Now we repeat the following process seven times: * select "Create Logical Volume" * select Volume Group "System" * give the LV Name (from the table, e.g. swap, var etc) * give the LV size (from the table, e.g. 1GB for swap etc) After this, we can select "Finish", the partitioner creates the seven LVs, and we're back at the partitioner screen, where there are now 7 extra "disks", with names such as ''LVM VG system, LV appslog - 3.2GB Linux device mapper''. Each of these "disks" has one block of empty space, which we now assign: seven times we repeat the following process: * select the unassigned chunk of empty space of an LV (e.g. appslog) and press &lt;enter&gt;; * Change "Use as: do not use" into the desired filesystem (ext3 - only the LV "swap" gets as filesystem type "swap area") * Change the mount point from "none" to the one corresponding with the name of the LV (note: the swap LV has no mountpoint; the appslog mountpoint must be entered manually as "/var/appslog") * If so desired, a label can be assigned to the partition (we usually don't) * select "Done setting up the partition" Once all this is done, we can look over the configuration once more, and then select "Finish partitioning and write changes to disk". A summary configuration screen will show, and we'll affirm with "yes" that these partitions can indeed be formatted. After some formatting screens flashing by (unless your partitions are particularly big, your system is particularly slow, or something goes wrong) the installation procedure continues. ==Final installer steps== Next comes one '''VERY''' important question: what to use as root password? We cannot stress this enough: choose a SAFE password! Do NOT go for an easy-to-remember one, go for STRONG and SAFE. There are tools to help you generate strong passwords, like [http://www.pctools.com/guides/password/ this page]: use them! We strongly suggest 10 characters or more, including letters, mixed case, and numbers, so something like ''SuCRe4hecH'' (do NOT use this, generate your own!). Next, give the full name of the principal user of this server (your own, we assume), give the login-name (your given name, we assume), and a corresponding password. Again, use a SAFE password. As long as you don't make your principal user equivalent to root, you might go for a slightly weaker password (8 characters instead of 10), but we rather suggest you make the password just as strong (and different from!) the root password. After entering the details of these two users "root" and "you", the Debian installer will ask you how it can contact the Debian archives, in the dialoge "configure the package manager". For the NetInstall version of Debian, this is as good as mandatory. So here, we say "yes, use a Network Mirror", and in the following list select the country in which we are (in our case: the Netherlands), so the installer can present us with a number of network mirrors "close by". We select ftp.nl.debian.org. Next screen: should you be behind a proxy server, then it's possible to specify that here. And then the test: the system will say "scanning the mirror..." and try to contact the specified mirror. If it does not succeed, then there is either a network problem, a problem with this box's network card, or you've not specified the mirror or proxy correctly - so fix it. You'll know the network mirror has succesfully been contacted when the next dialogue appears - currently "configuring popularity-contest". Answer this question as you please. And then one of the last "big" questions: Software Selection. In this dialogue, you can easily select bundles of software to be installed. The choices are currently: * Desktop environment * Web server * Print server * DNS server * File server * Mail server * SQL database * Laptop * Standard system (selected by default) We have to make a little confession here: we've never before used this option in the installer. In fact, we even deselect the Standard System, so as to minimize the number of software packages that the base installation of our server contains. This makes it more work to manually add packages later, but we feel it gives us more control and understanding of our systems. So if you are like us: deselect the Standard System entry, and select Continue. The next dialogue handles the installation of the [http://www.gnu.org/software/grub/ ''grub'' bootloader]. Unless your disks weren't empty and you're attempting to make this system multiboot, you'll most likely get a question if you'll allow the installer to install ''grub'' into the boot sector of the first hard disk. We'll confirm with "Yes". After the installation of grub is completed, the CD-ROM is ejected, and the system is ready to reboot into Debian Etch. Remove the CD and select "Continue" ==Finishing up the installation== The system should reboot into Debian. This means you should see the following boot sequence: * your machine's standard POST messages * then, a blue grub menu on a black screen, with two entries: ** Debian GNU/Linux, kernel 2.6.&lt;something&gt; ** Debian GNU/Linux, kernel 2.6.&lt;something&gt (single-user mode); * then, after a default time-out, the first grub option will go into effect, and the Linux kernel is started. Lots of cryptic messages in grey-on-black will scroll by, until the last few lines read: "Debian GNU/Linux 4.0 &lt;hostname&gt; tty1" and "&lt;hostname&gt; login:" If your system does not reach this login, and/or some horrible error messages appear anywhere in this boot sequence, then you've got some extra work ahead. For now we'll assume you've reached the login prompt without problem. Log in as the principal user (try to avoid logging in as root! That's BAD practice!). Once logged in, save a copy of the boot messages using ''sudo dmesg > boot.txt'' or whatever you like. Then look through the boot messages, e.g. with ''vi -R boot.txt''. Furthermore, [[Using Aptitude | use Aptitude]] to make sure ''all'' your software is updated to the latest version. Done! Your base system is ready. You probably now want to [[essential system software | install essential software]], [[make your own kernel]] and [[connect your server to the Internet]]. 66adeb050c4c0f83e4a6c961037af9e07635eb60 2 1410 1415 2008-04-20T17:58:43Z Saruman! 2 Initial writeup wikitext text/x-wiki <big>'''Saruman!'''</big> I'm part of the [[SaruTeam | Administrators team]] of this site. As you can read under the team description, I work as a technical consultant infrastructure at a large IT company. As such, I help customers with Unix and Linux servers, networks, security, virtualization and documentation - although occasionally I have to work with Microsoft Windows networks as well. My qualifications are, amongst others, [http://www.lpi.org/ LPI certifications] ([http://www.lpi.org/en/lpi/english/certification/the_lpic_program LPIC1 and LPIC2] - LPIC 3 is too difficult for me, I fear) In my spare time (if any), I listen to progressive rock music (especially work by [http://www.the-company.com/ Fish]), organize my music in my oversized iTunes library, ride a hi-tech hybrid car, read sci-fi and fantasy (not nearly often enough, though :-(, and play a bit with my digital camera, a [http://www.canon-europe.com/For_Home/Product_Finder/Cameras/Digital_SLR/EOS_20th_Anniversary/2004-2007.asp Canon EOS350D]. I'm married and have one daughter. bf0962b1655292801cff6148cab6b287e66caf0b 0 1411 1417 2008-04-20T18:44:58Z Saruman! 2 Draft (Dutch) wikitext text/x-wiki <big>'''PoPToP VPN Server'''</big> Het Microsoft PPTP protocol is een relatief onveilig protocol (op pptpclient.sourceforge.net staat een uitleg). Desalniettemin kan het wenselijk zijn om een Linux-server te voorzien van een VPN-server op basis van het PPTP protocol; meestal zal dit zijn omdat een klant een VPN-oplossing wil, maar geen client VPN software geïnstalleerd wil hebben (en de Microsoft PPTP-software zit standaard bij elke Windows client [ik geloof sinds Windows 98]). Iedere beveiligingsexpert die het zout in de pap waard is zal je adviseren geen PPTP te gebruiken, maar IPsec of OpenVPN (gebaseerd op SSL). Weet je desondanks zéker dat de Linux-server PPTP-VPN moet ondersteunen, waarschuw dan de klant schriftelijk voor de risico's, en begin daarna pas met onderstaande. Voorbereiding 1.Begin met een Linux-server die zijn basis-opzet gehad heeft. Log in en su naar root. Zorg dat de catalogus van aptitude is bijgewerkt (met “u”); check dat alle software op de Linux-server up-to-date is t.ov. deze catalogus (met “shift-u” en “g”). 2.Gebruik aptitude om de volgende pakketten te installeren, voorzover ze niet al geïnstalleerd zijn: - ppp (minstens versie 2.4.4) - pptp-linux (client software, niet expliciet nodig) - pptpd (versie 1.3.0 of hoger) 3.Zorg dat de kernel gecompileerd is met ppp-support als module. In menuconfig vind je dit onder device drivers > Network device support > PPP (Point-to-Point protocol) support. Doe hierbij ook “PPP support for async serial ports” als module. NB beide schijnen niet statisch gecompileerd te kunnen worden, want dan werkt de pptpd niet? Tevens moet je onder cryptographic options de opties SHA1 en ARC4 aan hebben staan. 4.Bewerk /etc/pptpd.conf. Het belangrijkste zijn de onderste regels: welke IP-nummers moeten er gebruikt worden voor de server en voor de VPN clients. Het is mogelijk maar één IPnummer in te vullen voor de server; de clients krijgen elk een eigen IPnummer uit de opgegeven reeks. Een voorbeeld is dus: localip 192.168.0.1 remoteip 192.168.0.201-210 Hiermee reserveer je 10 IPnummers voor clients; elke client heeft zijn pptp-verbinding met 192.168.0.1. Het is mogelijk een range te pakken búiten de LAN range, maar dan moet je op de client een gateway opgeven. Handiger is het om een klein stukje vrije range van het LAN zelf te nemen. 5.Herstart de pptpd server middels /etc/init.d/pptpd restart 6.Voeg gebruikers toe aan /etc/ppp/chap-secrets. De format is: <gebruikersnaam> pptpd “<password>“ * Merk op dat gebruikersnamen case sensitive zijn! Als je dus als gebruikersnaam “jans” intypt, dan kun je NIET met “JanS” inloggen! 7.Voeg aan het eind van /etc/ppp/pptpd-options de tekst toe: # Disable Van Jacobson compression # (needed on some networks with Windows 9x/ME/XP clients, see posting to # poptop-server on 14th April 2005 by Pawel Pokrywka and followups, # http://marc.theaimsgroup.com/?t=111343175400006&r=1&w=2 ) novj novjccomp # turn off logging to stderr, since this may be redirected to pptpd, # which may trigger a loopback nologfd 8.check of de firewall verkeer van de VPN clients kan doorlaten; een VPN-verbinding is in het algemeen verkeer vanaf een ppp<x> interface (ppp0 e.d.). 8049e5e92d67a5bbce69355416fc1a6737e04c71 0 1412 1425 2008-04-28T17:17:39Z Saruman! 2 Seeding of this page wikitext text/x-wiki RAID does not always have to be hardware-based; it's [http://linas.org/linux/raid.html available in modern Linux] as software-based RAID, and the implementation is really very good. 89a70988b9d385fbe9ead1d7ed2331f7d1726393 0 1414 1440 2008-05-17T13:25:36Z Saruman! 2 Starting page wikitext text/x-wiki ==Essential system software== The following packages we deem essential for any Debian (home) server: [[OpenSSH server]] 1797ccbd0bf1f04d35535c489a600a11c64a5708 1442 1440 2008-05-17T17:11:20Z Insomnia 3 /* Essential system software */ wikitext text/x-wiki ==Essential system software== The following packages we deem essential for any Debian (home) server: [[OpenSSH server]] [[crontab]] 649fa84475ee5dc4bf7b32c0ac1a195cce1eefef 1443 1442 2008-05-17T17:13:41Z Insomnia 3 /* Essential system software */ wikitext text/x-wiki ==Essential system software== The following packages we deem essential for any Debian (home) server: [[OpenSSH server]]<br> [[Crontab]] b6b26dddf5e2bce3648835656a10504fbddde787 1444 1443 2008-05-17T17:33:46Z Saruman! 2 extra entries wikitext text/x-wiki ==Essential system software== The following packages we deem quite essential for any Debian (home) server: [[OpenSSH server]]<br> [[Crontab]]<br> [[iproute2]]<br> [[Compilation software]]<br> [[Sudo]]<br> [[IPtables and firewall]]<br> [[IPsec software]]<br> f1e4c679941af69b34914ea4fe890ba3732e8092 0 1416 1445 2008-05-17T17:57:17Z Insomnia 3 wikitext text/x-wiki ==Crontab== To schedule a task you can use cron. Every user has it's own crontab if the user has the right to use it. Also system has a crontab witch has 3 default entry's in /etc/crontab # /etc/crontab: system-wide crontab # Unlike any other crontab you don't have to run the `crontab' # command to install the new version when you edit this file # and files in /etc/cron.d. These files also have username fields, # that none of the other crontabs do. SHELL=/bin/sh PATH=/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin # m h dom mon dow user command 17 * * * * root cd / && run-parts --report /etc/cron.hourly 25 6 * * * root test -x /usr/sbin/anacron || ( cd / && run-parts --report /etc/cron.daily ) 47 6 * * 7 root test -x /usr/sbin/anacron || ( cd / && run-parts --report /etc/cron.weekly ) 52 6 1 * * root test -x /usr/sbin/anacron || ( cd / && run-parts --report /etc/cron.monthly ) # you can schedule tasks directly in the 3 folders. To see the current users crontab >crontab -l To see a users crontab >crontab -u 'username' -l To edit the current users crontab >crontab -e Now you can schedule your task # +---------------- minute (0 - 59) # | +------------- hour (0 - 23) # | | +---------- day of month (1 - 31) # | | | +------- month (1 - 12) # | | | | +---- day of week (0 - 6) (Sunday=0 or 7) # | | | | | * * * * * command to be executed fcaeb24e90e6284d30dc736a39189ca47fdf9e93 1446 1445 2008-05-17T18:10:38Z Insomnia 3 /* Crontab */ wikitext text/x-wiki ==Crontab== To schedule a task you can use cron. Every user has it's own crontab if the user has the right to use it. Also system has a crontab witch has 3 default entry's in /etc/crontab # /etc/crontab: system-wide crontab # Unlike any other crontab you don't have to run the `crontab' # command to install the new version when you edit this file # and files in /etc/cron.d. These files also have username fields, # that none of the other crontabs do. SHELL=/bin/sh PATH=/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin # m h dom mon dow user command 17 * * * * root cd / && run-parts --report /etc/cron.hourly 25 6 * * * root test -x /usr/sbin/anacron || ( cd / && run-parts --report /etc/cron.daily ) 47 6 * * 7 root test -x /usr/sbin/anacron || ( cd / && run-parts --report /etc/cron.weekly ) 52 6 1 * * root test -x /usr/sbin/anacron || ( cd / && run-parts --report /etc/cron.monthly ) # you can schedule tasks directly in the 3 folders. To see the current users crontab >crontab -l To see a users crontab >crontab -u 'username' -l To edit the current users crontab >crontab -e Now you can schedule your task # +---------------- minute (0 - 59) # | +------------- hour (0 - 23) # | | +---------- day of month (1 - 31) # | | | +------- month (1 - 12) # | | | | +---- day of week (0 - 6) (Sunday=0 or 7) # | | | | | * * * * * command to be executed (full path to command/script) cb6d55cbf563e059f3df9e5a7e131ea7acb0e2a1 1447 1446 2008-05-17T18:40:32Z 82.161.20.132 0 /* Crontab */ wikitext text/x-wiki ==Crontab== To schedule a task you can use cron. Every user has it's own crontab. Also system has a crontab witch has 3 default entry's in /etc/crontab # /etc/crontab: system-wide crontab # Unlike any other crontab you don't have to run the `crontab' # command to install the new version when you edit this file # and files in /etc/cron.d. These files also have username fields, # that none of the other crontabs do. SHELL=/bin/sh PATH=/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin # m h dom mon dow user command 17 * * * * root cd / && run-parts --report /etc/cron.hourly 25 6 * * * root test -x /usr/sbin/anacron || ( cd / && run-parts --report /etc/cron.daily ) 47 6 * * 7 root test -x /usr/sbin/anacron || ( cd / && run-parts --report /etc/cron.weekly ) 52 6 1 * * root test -x /usr/sbin/anacron || ( cd / && run-parts --report /etc/cron.monthly ) # you can schedule tasks directly in the 3 folders. To see the current users crontab >crontab -l To see a users crontab >crontab -u 'username' -l To edit the current users crontab >crontab -e Now you can schedule your task # +---------------- minute (0 - 59) # | +------------- hour (0 - 23) # | | +---------- day of month (1 - 31) # | | | +------- month (1 - 12) # | | | | +---- day of week (0 - 6) (Sunday=0 or 7) # | | | | | * * * * * command to be executed (full path to command/script) e3fb0917461f518094eeceeb1a0195b44af7beb7 1456 1447 2008-05-18T10:02:53Z Saruman! 2 /* Crontab */ expanded introduction wikitext text/x-wiki Linux has it's own scheduler, named cron (derived from Greek chronos (χρόνος), meaning time). The Debian package contains the version written by Paul Vixie. Cron operates by having a daemon ''crond'' running in the background, that checks once every minute to see if there are scheduled tasks to run. Tasks can be scheduled by each user by making entries in a file named a ''crontab''. Each user has his own crontab, that cron saves in ''/var/spool/cron/crontabs/&lt;username&gt;''. Furthermore, there's a general crontab in ''/etc'', aptly named ''crontab''. This crontab under Debian has 3 default entries: <pre> # /etc/crontab: system-wide crontab # Unlike any other crontab you don't have to run the `crontab' # command to install the new version when you edit this file # and files in /etc/cron.d. These files also have username fields, # that none of the other crontabs do. SHELL=/bin/sh PATH=/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin # m h dom mon dow user command 17 * * * * root cd / && run-parts --report /etc/cron.hourly 25 6 * * * root test -x /usr/sbin/anacron || ( cd / && run-parts --report /etc/cron.daily ) 47 6 * * 7 root test -x /usr/sbin/anacron || ( cd / && run-parts --report /etc/cron.weekly ) 52 6 1 * * root test -x /usr/sbin/anacron || ( cd / && run-parts --report /etc/cron.monthly ) # </pre> you can schedule tasks directly in the 3 folders. To see the current users crontab >crontab -l To see a users crontab >crontab -u 'username' -l To edit the current users crontab >crontab -e Now you can schedule your task # +---------------- minute (0 - 59) # | +------------- hour (0 - 23) # | | +---------- day of month (1 - 31) # | | | +------- month (1 - 12) # | | | | +---- day of week (0 - 6) (Sunday=0 or 7) # | | | | | * * * * * command to be executed (full path to command/script) 120687dfc93cf7977768f00b60c3dd51b9d035de 0 1417 1449 2008-05-17T18:58:24Z Insomnia 3 wikitext text/x-wiki == '''LM sensors''' == turn on i2c support in your kernel -device drivers\i2c support And turn on the appropiate device drivers in the kernel -device drivers\hardware monitoring\ ite87 -Asus asb100 - amd athlon temp install the package lm-sensors Apt-get install lm-sensors ># sensors-detect -> wil give you a view of the found sensors (say YES to all questions) Driver `eeprom' (should be inserted): Detects correctly: * Bus `SMBus PIIX4 adapter at 0b00' Busdriver `i2c-piix4', I2C address 0x50 Chip `eeprom' (confidence: 6) * Bus `SMBus PIIX4 adapter at 0b00' Busdriver `i2c-piix4', I2C address 0x51 Chip `eeprom' (confidence: 6) EEPROMs are *NOT* sensors! They are data storage chips commonly found on memory modules (SPD), in monitors (EDID), or in some laptops, for example. Driver `k8temp' (should be inserted): Detects correctly: * ISA bus, undetermined address (Busdriver `i2c-isa') Chip `AMD K8 thermal sensors' (confidence: 9) Driver `it87' (should be inserted): Detects correctly: * ISA bus address 0x0228 (Busdriver `i2c-isa') Chip `ITE IT8716F Super IO Sensors' (confidence: 9) The script will give you the appropiate line to insert in /etc/modules Make shure that the modules are configured in your kernel #----cut here---- # I2C adapter drivers i2c-piix4 # Chip drivers # Warning: the required module eeprom is not currently installed # on your system. For status of 2.6 kernel ports check # http://www.lm-sensors.org/wiki/Devices. If driver is built # into the kernel, or unavailable, comment out the following line. eeprom # Warning: the required module k8temp is not currently installed # on your system. For status of 2.6 kernel ports check # http://www.lm-sensors.org/wiki/Devices. If driver is built # into the kernel, or unavailable, comment out the following line. k8temp # Warning: the required module it87 is not currently installed # on your system. For status of 2.6 kernel ports check # http://www.lm-sensors.org/wiki/Devices. If driver is built # into the kernel, or unavailable, comment out the following line. it87 #----cut here---- ># sensors will give you the readout of the sensors it8716-isa-0228 Adapter: ISA adapter VCore: +1.01 V (min = +0.00 V, max = +4.08 V) VDDR: +3.38 V (min = +3.57 V, max = +4.08 V) ALARM +3.3V: +0.00 V (min = +0.00 V, max = +4.08 V) ALARM +5V: +4.89 V (min = +0.00 V, max = +6.80 V) +12V: +11.97 V (min = +0.00 V, max = +16.32 V) in5: +0.00 V (min = +0.00 V, max = +4.08 V) ALARM in6: +0.00 V (min = +0.00 V, max = +4.08 V) ALARM 5VSB: +4.89 V (min = +0.00 V, max = +6.85 V) VBat: +3.22 V fan1: 1588 RPM (min = 3245 RPM) fan2: 0 RPM (min = 3245 RPM) temp1: +27°C (low = -1°C, high = +127°C) sensor = diode temp2: +32°C (low = -17°C, high = +127°C) sensor = thermistor temp3: +25°C (low = -1°C, high = +127°C) sensor = thermistor vid: +1.550 V k8temp-pci-00c3 Adapter: PCI adapter Core0 Temp: +7°C Core0 Temp: -1°C Core1 Temp: +8°C Core1 Temp: +9°C The read out of the CPU temp is still an issue. As you can see it gives the wrong values 6fb3fb0f17ca906e735862ceaee1976224695044 0 1418 1451 2008-05-17T19:45:46Z Saruman! 2 Page creation wikitext text/x-wiki ==Message of the Day== The MOTD file stands for Message of the Day; it appears at the beginning of every console and terminal session. To create a MOTD file is extremely simple: # backup the current MOTD file (most likely the original Debian banner) by using ''sudo cp /etc/motd /etc/motd.org'' # edit the MOTD file with your favorite editor: ''sudo vi /etc/motd'' # make a backup of this MOTD file by using ''sudo cp /etc/motd /etc/motd.bak'' If you neglect to make a backup of your pretty MOTD file, you run the risk of it being overwritten as soon as you upgrade your Debian kernel image (which you're required to do at least several times per year to keep up with security patches). A nice MOTD file could look like this: <pre> Linux oberon.saruman.biz ########################################################################################### ########################################################################################### ### ### ### OOOOOOO BBBBBBBBB EEEEEEEEEE RRRRRRRR OOOOOOO NNN NNN ### ### OOOOOOOOOOO BBBBBBBBBBB EEEEEEEEEE RRRRRRRRRR OOOOOOOOOOO NNNN NNN ### ### OOO OOO BBB BBB EEE RRR RRR OOO OOO NNNNN NNN ### ### OOO OOO BBB BBB EEE RRR RRR OOO OOO NNNNNN NNN ### ### OOO OOO BBBBBBBBBBB EEEEEE RRRRRRRRRR OOO OOO NNN NNN NNN ### ### OOO OOO BBBBBBBBBBB EEEEEE RRRRRRRR OOO OOO NNN NNN NNN ### ### OOO OOO BBB BBB EEE RRR RRR OOO OOO NNN NNNNNN ### ### OOO OOO BBB BBB EEE RRR RRR OOO OOO NNN NNNNN ### ### OOOOOOOOOOO BBBBBBBBBBB EEEEEEEEEE RRR RRR OOOOOOOOOOO NNN NNNN ### ### OOOOOOO BBBBBBBBB EEEEEEEEEE RRR RRR OOOOOOO NNN NNN ### ### ### ########################################################################################### ########################################################################################### Unauthorised login prohibited by law. Unless you are explicitly allowed access by the administrator of the Saruman.biz domain, you may NOT log into this system. </pre> 1f1977daad5a72a393b8704bc58802b9eadde851 0 1419 1452 2008-05-17T19:49:45Z Insomnia 3 wikitext text/x-wiki == '''SMART''' == Install smartmontools >apt-get install smartmontools Now you have 2 utility program's (smartctl and smartd). With smartctl you can read out your hard disks >smartctl -a /dev/hda This will give you all info of your hard disk. For sata disk you will have to give the -d option >smartctl -d ata -a /dev/hda Fore more options on smartctl use -h Now we can configure the smart daemon in /etc/smartd.conf f024f2a64501a915c62a8c7730ada045c304a735 1454 1452 2008-05-17T23:16:19Z 82.161.20.132 0 wikitext text/x-wiki == '''SMART''' == Install smartmontools >apt-get install smartmontools Now you have 2 utility program's (smartctl and smartd). With smartctl you can read out your hard disks >smartctl -a /dev/hda This will give you all info of your hard disk. For sata disk you will have to give the -d option >smartctl -d ata -a /dev/hda Fore more options on smartctl use -h Now we can configure the smart daemon in /etc/smartd.conf This config file gives you a good explination of the different options you can use I use the following options /dev/sda -d ata -a -o on -S on -s (S/../.././02|L/../../6/03) /dev/sda -d ata -H -m admin@linuz.nl d5679970c5c58aaa5d36258263dcf11fdb26d5b4 12 1420 1453 2008-05-17T20:05:06Z Saruman! 2 Help page started wikitext text/x-wiki If you need some help on editing, the main source of info is [http://meta.wikimedia.org/wiki/Help:Contents here, on the Wikimedia page]. 8bce1b9ea1d68d542964beaa4ef44709ffc626a6 0 1421 1459 2008-05-18T19:32:39Z Saruman! 2 Page started wikitext text/x-wiki To set up a site-to-site tunnel using IPsec, we start with a [[Debian Etch base server]]. Use ''[[APT and aptitude | aptitude]]'' to update all packages on the server to the latest version. e1830023f64cbaff240af64514d4a54a3a4a5837 0 1419 1460 1454 2008-05-18T20:10:12Z Insomnia 3 changed text wikitext text/x-wiki == '''SMART''' == If you want to read out the smart status of your hard disk you can use smartmontools. >apt-get install smartmontools Now you have 2 utility program's (smartctl and smartd). With smartctl you can read out your hard disks >smartctl -a /dev/hda This will give you all info of your hard disk. For sata disk you will have to give the -d option >smartctl -d ata -a /dev/hda Fore more options on smartctl use -h Now we can configure the smart daemon in /etc/smartd.conf. This daemon will monitor your hard disks. This config file gives you a good explination of the different options you can use I use the following options /dev/sda -d ata -a -o on -S on -s (S/../.././02|L/../../6/03) /dev/sda -d ata -H -m admin@linuz.nl 413a10cfcd6aede8743ac858eb21e295b939be36 0 1421 1461 1459 2008-05-18T20:13:58Z Saruman! 2 Preparations added wikitext text/x-wiki First off: what subject are we going to cover? Well, this page will cover how to set up a tunnel between two (Debian) Linux servers that both are connected to the Internet, so as to form a VPN tunnel between the two (private) networks that these two servers are ''also'' connected to. The tunnel will be set up using a Pre-Shared Key (PSK) and will transport all traffic. This scenario is not uncommon, in fact it's the scenario for which most material on the Internet can be found. And a very complete explanation of the basics of IPsec tunneling can be found [http://ipsec-howto.org/ here]. Still, here's ''our'' view of this material. ==Preparations== To set up a site-to-site tunnel using IPsec, we start with a [[Debian Etch base server]]. Use ''[[APT and aptitude | aptitude]]'' to update all packages on the server to the latest version. Then check that your kernel [[Roll your own kernel | is compiled]] with the right options for IPsec. These options can be found under ''networking &gt; networking options'' and include at least (but may not be limited to): <pre> (*) PF_KEY sockets (NET_KEY) (*) IP: ESP transformation (INET_ESP) (*) IP: IPsec tunnel mode (INET_XFRM_MODE_TUNNEL) </pre> Of course, in newer versions of the kernel than the 2.6.25 from which we lifted these terms, these options could be named differently. Next off, it's time to install the necessary Debian packages. The two packages needed are: * racoon: this is a * ipsec-tools: Now, we have to decide whether we want c7c29f754c2ee18a2fae1a26916200c26a50cc1d 1464 1461 2008-05-18T20:54:02Z Saruman! 2 IPsec software installation added wikitext text/x-wiki First off: what subject are we going to cover? Well, this page will cover how to set up a tunnel between two (Debian) Linux servers that both are connected to the Internet, so as to form a VPN tunnel between the two (private) networks that these two servers are ''also'' connected to. The tunnel will be set up using a Pre-Shared Key (PSK) and will transport all traffic. This scenario is not uncommon, in fact it's the scenario for which most material on the Internet can be found. And a very complete explanation of the basics of IPsec tunneling can be found [http://ipsec-howto.org/ here]. Still, here's ''our'' view of this material. ==Preparations== To set up a site-to-site tunnel using IPsec, we start with a [[Debian Etch base server]]. Use ''[[APT and aptitude | aptitude]]'' to update all packages on the server to the latest version. Then check that your kernel is at least version 2.6, and [[Roll your own kernel | is compiled]] with the right options for IPsec. These options can be found under ''networking &gt; networking options'' and include at least (but may not be limited to): <pre> (*) PF_KEY sockets (NET_KEY) (*) IP: ESP transformation (INET_ESP) (*) IP: IPsec tunnel mode (INET_XFRM_MODE_TUNNEL) </pre> Of course, in newer versions of the kernel than the 2.6.25 from which we lifted these terms, these options could be named differently. Furthermore, your kernel must have <u>all</u> the cryptographic options enabled for the compression/encryprion that your tunnels are supposed to use, e.g. AES, Blowfish et cetera. Next off, it's time to install the necessary Debian packages. The two packages needed are: * racoon: this is a tool for handling IKE (Internet Key Exchange) * ipsec-tools: this is a set of IPsec utilities. Now, since we run Debian, things are slightly different from any other distribution. The [http://packages.qa.debian.org/ipsec-tools Debian maintainer for racoon] has created a little "macro preprocessor" named ''racoon-tool'' which can make configuring racoon a little easier. However, since we a) like to have full control of a configuration, and b) don't like to veer too much off the well-trodden paths that collegue sysadmins might have taken and documented, we currentle do NOT use racoon-tool as the configuration means for racoon. So, when the APT package installation will ask, we will respond that we do NOT want to use racoon-tool. So, use [[APT and aptitude | aptitude]] to install both packages ''racoon'' and ''ipsec-tools''; in Etch both at version 0.6.6. Then, when aptitude starts installing racoon, it'll ask you if you want to configure racoon using "racoon-tool" or "direct"; choose "direct". If installation of the software has succeeded correctly, you can run the following commands: setkey -help racoon -help == Configuring the software == Now it's time to create a PSK, a Pre-shared key. This is a string of characters, preferably long and strong, e.g. an MD5 hash, something like ''84f1c066b584dc5871c930f73c5029c9''. Such a PSK can be generated with dd if=/dev/random count=16 bs=1 | xxd -ps (If you don't have the ''xxd'' package, install ''[[vim]]''; we consider that part of our [[essential system software | essential software]], and xxd comes with it.) This PSK must be stored somewhere on your system, as well as on the system on the other side of the tunnel (that's what the '''shared''' part of PSK stands for, anyway). To this end, create a file named ''psk.txt'' in directory ''/etc/racoon''. Into this file, write the PSK like # key for route to odeon.lan 82.1.2.32 0x84f1c066b584dc5871c930f73c5029c9 And, on the other side, # key for route to amber.lan 212.238.1.17 0x84f1c066b584dc5871c930f73c5029c9 Note that we precede the generated hex string with ''0x'' to signify to racoon that it's a hexadecimal key. If we don't do that, racoon will treat the string as a passphrase. Not a problem either, but at any rate, both sides must do the same. 72214fe7d5a3b2ba1c6cfa6de2e35702836eff15 0 1414 1462 1444 2008-05-18T20:40:00Z Saruman! 2 /* Essential system software */ added VIM wikitext text/x-wiki ==Essential system software== The following packages we deem quite essential for any Debian (home) server: [[OpenSSH server]]<br> [[vim]] which stands for VI iMproved<br> [[Crontab]]<br> [[iproute2]]<br> [[Compilation software]]<br> [[Sudo]]<br> [[IPtables and firewall]]<br> [[IPsec software]]<br> ae81961ed381925daed21ff66b58bcf61cc3fb3a 1490 1462 2008-05-26T04:34:18Z Saruman! 2 added big bag'o'utilities, moved sudo there wikitext text/x-wiki ==Essential system software== The following packages we deem quite essential for any Debian (home) server: [[Big Bag'o'utilities]] (not "a" package, but a collection of essential tools like ''less'' and ''sudo'')<br> [[OpenSSH server]]<br> [[vim]] which stands for VI iMproved<br> [[Crontab]]<br> [[iproute2]]<br> [[Compilation software]]<br> [[IPtables and firewall]]<br> [[IPsec software]]<br> 0fec93cf3b999b536fc4124b8349b05d5d847145 0 1422 1463 2008-05-18T20:41:07Z Saruman! 2 VIM page started wikitext text/x-wiki When you install ''vim'', you also get ''xxd'', a tool to make a hexdump, or convert a hex dump back to it's original binary form. 36c04184ca9388858572cac23d36feeaf975c934 1466 1463 2008-05-19T20:44:07Z Saruman! 2 added intro wikitext text/x-wiki ==Introduction== The screen-oriented text editor ''vim'' stems from ''vi'', written in '76 for an early BSD Unix release by [http://www.engin.umich.edu/alumni/engineer/04SS/achievements/advances.html#joy Bill Joy]. ''vi'' is old, nonintuitive, and complex. ''[http://en.wikipedia.org/wiki/Vim_%28text_editor%29 vim]'' stems from 1991, and stands for '''''V'''i '''IM'''proved'', but its improvements do not lessen it's nonintuitivity or complexity. So why do we feel that ''vim'' is an essential system tool? Well, it's because * vi can be found on just about any Linux and Unix system * vi is very powerful * with some practice, it's even usable. ==Installation and configuration== When you install ''vim'', you also get ''xxd'', a tool to make a hexdump, or convert a hex dump back to it's original binary form. eeb907f87eab55476b4e0245e8740ac463158dc9 1468 1466 2008-05-23T09:56:04Z Insomnia 3 using vim wikitext text/x-wiki ==Introduction== The screen-oriented text editor ''vim'' stems from ''vi'', written in '76 for an early BSD Unix release by [http://www.engin.umich.edu/alumni/engineer/04SS/achievements/advances.html#joy Bill Joy]. ''vi'' is old, nonintuitive, and complex. ''[http://en.wikipedia.org/wiki/Vim_%28text_editor%29 vim]'' stems from 1991, and stands for '''''V'''i '''IM'''proved'', but its improvements do not lessen it's nonintuitivity or complexity. So why do we feel that ''vim'' is an essential system tool? Well, it's because * vi can be found on just about any Linux and Unix system * vi is very powerful * with some practice, it's even usable. ==Installation and configuration== When you install ''vim'', you also get ''xxd'', a tool to make a hexdump, or convert a hex dump back to it's original binary form. ==Using VIM== Vim operates in 2 modus. A command mode and a insert mode. You start in command mode so almost every key is a command. You can switch to insert mode with ''i'' to return in command mode press ''esc'' or ( ''ctrl ['' ) Start in insert mode and typ some text. To save your progress return in command mode with ''esc'' Now we can use the ''ex-commands'' typ '':w'' to save the document. or use these commands. :w Save :w 'filename' Save with this filename :q quit vim :q! quit without save :wq save and quit e113dbf79a29d5844a040914a1c4988a89de8099 1471 1468 2008-05-23T20:42:07Z Insomnia 3 wikitext text/x-wiki ==Introduction== The screen-oriented text editor ''vim'' stems from ''vi'', written in '76 for an early BSD Unix release by [http://www.engin.umich.edu/alumni/engineer/04SS/achievements/advances.html#joy Bill Joy]. ''vi'' is old, nonintuitive, and complex. ''[http://en.wikipedia.org/wiki/Vim_%28text_editor%29 vim]'' stems from 1991, and stands for '''''V'''i '''IM'''proved'', but its improvements do not lessen it's nonintuitivity or complexity. So why do we feel that ''vim'' is an essential system tool? Well, it's because * vi can be found on just about any Linux and Unix system * vi is very powerful * with some practice, it's even usable. ==Installation and configuration== When you install ''vim'', you also get ''xxd'', a tool to make a hexdump, or convert a hex dump back to it's original binary form. ==Using VIM== Vim operates in 2 modus. A command mode and a insert mode. You start in command mode so almost every key is a command. You can switch to insert mode with ''i'' to return in command mode press ''esc'' or ( ''ctrl ['' ) Start in insert mode and typ some text. To save your progress return in command mode with ''esc'' Now we can use the ''ex-commands'' typ '':w'' to save the document. or use these commands. :w Save :w 'filename' Save with this filename :q quit vim :q! quit without save :wq save and quit ==over modal editors==<br> ==cursor positioning<br> ==searching<br> ==text insertion a Appends text after cursor. Terminated by escape key. A Appends text at the end of the line. Terminated the escape key. i Inserts text before cursor. Terminated by the escape key. I Inserts text at the beginning of the line. Terminated by the escape key. o Opens new line below the current line for text insertion. Terminated by the escape key. O Opens new line above the current line for text insertion. Terminated by the escape key. DEL Overwrites last character during text insertion. ESC Stops text insertion. The escape key on the DECstations is the F11 key 16edc5e0c61d5bb1be43579b3dbea55aff18fb28 1479 1471 2008-05-25T09:25:44Z Saruman! 2 added movement table + alternative editor note wikitext text/x-wiki ==Introduction== The screen-oriented text editor ''vim'' stems from ''vi'', written in '76 for an early BSD Unix release by [http://www.engin.umich.edu/alumni/engineer/04SS/achievements/advances.html#joy Bill Joy]. ''vi'' is old, nonintuitive, and complex. ''[http://en.wikipedia.org/wiki/Vim_%28text_editor%29 vim]'' stems from 1991, and stands for '''''V'''i '''IM'''proved'', but its improvements do not lessen it's nonintuitivity or complexity. So why do we feel that ''vim'' is an essential system tool? Well, it's because * vi can be found on just about any Linux and Unix system * vi is very powerful * with some practice, it's even usable. ==Installation and configuration== When you install ''vim'', you also get ''xxd'', a tool to make a hexdump, or convert a hex dump back to it's original binary form. ==Using VIM== Vim operates in 2 modus. A command mode and a insert mode. You start in command mode so almost every key is a command. You can switch to insert mode with ''i'' to return in command mode press ''esc'' or ( ''ctrl ['' ) Start in insert mode and typ some text. To save your progress return in command mode with ''esc'' Now we can use the ''ex-commands'' typ '':w'' to save the document. or use these commands. :w Save :w 'filename' Save with this filename :q quit vim :q! quit without save :wq save and quit ==About modal editors== ==Cursor positioning== {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Key(s) !style="background:#ffdead;"|Movement |- |j |down one line, same column |- |k |up one line, same column |- |h |one character back |- |l,&lt;space&gt; |one character forward |- |b |one word back (to beginning of previous word) |- |e |one word back (to end of previous word) |- |w |one word forward |- |&lt;enter&gt; |beginning of next line |- |0 (zero) |beginning of line |- |$ |end of line |- |''n''G |to beginning of line ''n''; if no number given, the last line of the file |- |:''n'' |also to beginning of line ''n'' (but this is visible as command) |- |} ==Searching== {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Key(s) !style="background:#ffdead;"|Movement |- |/''pattern'' |Moves the cursor to the next occurrence of ''pattern''; will wrap around to the beginning of the file from the last occurence |- |?''pattern'' |Moves the cursor backward to the previous occurrence of ''pattern''; will wrap around to the end of the file from the first occurence |- |n |repeats last pattern search (either / or ?) |} ==Text insertion== a Appends text after cursor. Terminated by escape key. A Appends text at the end of the line. Terminated the escape key. i Inserts text before cursor. Terminated by the escape key. I Inserts text at the beginning of the line. Terminated by the escape key. o Opens new line below the current line for text insertion. Terminated by the escape key. O Opens new line above the current line for text insertion. Terminated by the escape key. DEL Overwrites last character during text insertion. ESC Stops text insertion. The escape key on the DECstations is the F11 key ==Notes== In Debian Etch, the default editor is nano instead of vim. This can be changed in the following way: sudo update-alternatives --set editor /usr/bin/vim.tiny Now '''all''' commands that invoke an editor will use ''vi'' instead of ''vim''. Is that a good thing? We're not sure, but we do want to keep our ''vi'' skills up to par, so we do this. eb196c6eabc6dc28a3aee5b35c0cf5da262a84bc 1488 1479 2008-05-25T15:49:33Z 82.161.20.132 0 add tabel wikitext text/x-wiki ==Introduction== The screen-oriented text editor ''vim'' stems from ''vi'', written in '76 for an early BSD Unix release by [http://www.engin.umich.edu/alumni/engineer/04SS/achievements/advances.html#joy Bill Joy]. ''vi'' is old, nonintuitive, and complex. ''[http://en.wikipedia.org/wiki/Vim_%28text_editor%29 vim]'' stems from 1991, and stands for '''''V'''i '''IM'''proved'', but its improvements do not lessen it's nonintuitivity or complexity. So why do we feel that ''vim'' is an essential system tool? Well, it's because * vi can be found on just about any Linux and Unix system * vi is very powerful * with some practice, it's even usable. ==Installation and configuration== When you install ''vim'', you also get ''xxd'', a tool to make a hexdump, or convert a hex dump back to it's original binary form. ==Using VIM== Vim operates in 2 modus. A command mode and a insert mode. You start in command mode so almost every key is a command. You can switch to insert mode with ''i'' to return in command mode press ''esc'' or ( ''ctrl ['' ) Start in insert mode and typ some text. To save your progress return in command mode with ''esc'' Now we can use the ''ex-commands'' typ '':w'' to save the document. or use these commands. {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Command !style="background:#ffdead;"|Output |- |:w |Save |- |:w |'filename' Save with this filename |- |:q |quit vim |- |:q! |quit without save |- |:wq |save and quit |} ==About modal editors== ==Cursor positioning== {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Key(s) !style="background:#ffdead;"|Movement |- |j |down one line, same column |- |k |up one line, same column |- |h |one character back |- |l,&lt;space&gt; |one character forward |- |b |one word back (to beginning of previous word) |- |e |one word back (to end of previous word) |- |w |one word forward |- |&lt;enter&gt; |beginning of next line |- |0 (zero) |beginning of line |- |$ |end of line |- |''n''G |to beginning of line ''n''; if no number given, the last line of the file |- |:''n'' |also to beginning of line ''n'' (but this is visible as command) |- |} ==Searching== {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Key(s) !style="background:#ffdead;"|Movement |- |/''pattern'' |Moves the cursor to the next occurrence of ''pattern''; will wrap around to the beginning of the file from the last occurence |- |?''pattern'' |Moves the cursor backward to the previous occurrence of ''pattern''; will wrap around to the end of the file from the first occurence |- |n |repeats last pattern search (either / or ?) |} ==Text insertion== a Appends text after cursor. Terminated by escape key. A Appends text at the end of the line. Terminated the escape key. i Inserts text before cursor. Terminated by the escape key. I Inserts text at the beginning of the line. Terminated by the escape key. o Opens new line below the current line for text insertion. Terminated by the escape key. O Opens new line above the current line for text insertion. Terminated by the escape key. DEL Overwrites last character during text insertion. ESC Stops text insertion. The escape key on the DECstations is the F11 key ==Notes== In Debian Etch, the default editor is nano instead of vim. This can be changed in the following way: sudo update-alternatives --set editor /usr/bin/vim.tiny Now '''all''' commands that invoke an editor will use ''vi'' instead of ''vim''. Is that a good thing? We're not sure, but we do want to keep our ''vi'' skills up to par, so we do this. 37bf4bd010ac2951ba0b30a25033b855409e8d4f 1489 1488 2008-05-25T18:30:54Z Saruman! 2 added deletion table + updated insertion table wikitext text/x-wiki ==Introduction== The screen-oriented text editor ''vim'' stems from ''vi'', written in '76 for an early BSD Unix release by [http://www.engin.umich.edu/alumni/engineer/04SS/achievements/advances.html#joy Bill Joy]. ''vi'' is old, nonintuitive, and complex. ''[http://en.wikipedia.org/wiki/Vim_%28text_editor%29 vim]'' stems from 1991, and stands for '''''V'''i '''IM'''proved'', but its improvements do not lessen it's nonintuitivity or complexity. So why do we feel that ''vim'' is an essential system tool? Well, it's because * vi can be found on just about any Linux and Unix system * vi is very powerful * with some practice, it's even usable. ==Installation and configuration== To get ''vim'', simply use ''sudo apt-get install vim'' or ''sudo aptitude'', and find ''vim'' in the available packages. Nice to know: when you install ''vim'', you also get ''xxd'', a tool to make a hexdump, or convert a hex dump back to it's original binary form. In Debian Etch, the default editor is nano instead of vim. This can be changed in the following way: sudo update-alternatives --set editor /usr/bin/vim.tiny Now '''all''' commands that invoke an editor will use ''vim'' instead of ''nano''. Is that a good thing? We're not sure, but we do want to keep our ''vi'' skills up to par, so we do this. ==Using VIM== Vim operates in two modes: a command mode and an insert mode. You start in command mode, so almost every key is a command. You can switch to insert mode with ''i'' or ''a''; to return in command mode press ''&lt;esc&gt;'' or ( ''&lt;ctrl&gt; ['' ) Start in insert mode and typ some text. To save your progress return in command mode with ''&lt;esc&gt;'' Now we can use the ''exit-commands'' typ '':w'' to save the document. or use these commands. {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Command !style="background:#ffdead;"|Output |- |:w |Save |- |:w ''filename'' |Save with this filename |- |:q |quit vim |- |:q! |quit without save |- |:wq |save and quit |} ==About modal editors== ==Cursor positioning== {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Key(s) !style="background:#ffdead;"|Movement |- |j |down one line, same column |- |k |up one line, same column |- |h |one character back |- |l,&lt;space&gt; |one character forward |- |b |one word back (to beginning of previous word) |- |e |one word back (to end of previous word) |- |w |one word forward |- |&lt;enter&gt; |beginning of next line |- |0 (zero) |beginning of line |- |$ |end of line |- |''n''G |to beginning of line ''n''; if no number given, the last line of the file |- |:''n'' |also to beginning of line ''n'' (but this is visible as command) |- |} ==Searching== {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Key(s) !style="background:#ffdead;"|Search |- |/''pattern'' |Moves the cursor to the next occurrence of ''pattern''; will wrap around to the beginning of the file from the last occurence |- |?''pattern'' |Moves the cursor backward to the previous occurrence of ''pattern''; will wrap around to the end of the file from the first occurence |- |n |repeats last pattern search (either forward or backward) |- |} ==Text insertion== {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Key(s) !style="background:#ffdead;"|Effect |- |a |appends text after cursor & switches to Insert mode |- |A |appends text at the end of the line & switches to Insert mode |- |i |inserts text before cursor & switches to Insert mode |- |I |inserts text at the beginning of the line & switches to Insert mode |- |o |opens new line below the current line for text insertion & switches to Insert mode |- |O |opens new line above the current line for text insertion & switches to Insert mode |- |&lt;del&gt; |overwrites last character during text insertion |- |&lt;esc&gt; |stops text insertion. The escape key on the DECstations is the &lt;F11&gt; key |- |} ==Text deletion== {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Key(s) !style="background:#ffdead;"|Effect |- |x |deletes character under the cursor |- |dd |deletes current line |- |dw |deletes word under the cursor |- |d) |deletes to the end of the current sentence (up to and including the dot) |- |D |deletes to the end of the current line |- |d$ |same (deletes to the end of the current line) |- |P |"paste", puts back text from the previous deletion at the position of the cursor |- |} 136aa2b859ab9224a0dd86e1f31249c74410e6e1 1494 1489 2008-05-28T07:30:06Z 192.168.67.181 0 wikitext text/x-wiki ==Introduction== The screen-oriented text editor ''vim'' stems from ''vi'', written in '76 for an early BSD Unix release by [http://www.engin.umich.edu/alumni/engineer/04SS/achievements/advances.html#joy Bill Joy]. ''vi'' is old, nonintuitive, and complex. ''[http://en.wikipedia.org/wiki/Vim_%28text_editor%29 vim]'' stems from 1991, and stands for '''''V'''i '''IM'''proved'', but its improvements do not lessen it's nonintuitivity or complexity. So why do we feel that ''vim'' is an essential system tool? Well, it's because * vi can be found on just about any Linux and Unix system * vi is very powerful * with some practice, it's even usable. ===About modal editors=== ==Installation and configuration== To get ''vim'', simply use ''sudo apt-get install vim'' or ''sudo aptitude'', and find ''vim'' in the available packages. Nice to know: when you install ''vim'', you also get ''xxd'', a tool to make a hexdump, or convert a hex dump back to it's original binary form. In Debian Etch, the default editor is nano instead of vim. This can be changed in the following way: which vim.basic sudo update-alternatives --set editor /usr/bin/vim.basic (The first line is to check that you really have vim.basic in place) Now '''all''' commands that invoke an editor will use ''vim'' instead of ''nano''. Is that a good thing? We're not sure, but we do want to keep our ''vi'' skills up to par, so we do this. ==Using vim== Vim operates in two modes: a command mode and an insert mode. You start in command mode, so almost every key is a command. Several commands you can issue will bring you into '''--INSERT--''' moode, e.g. ''i'' or ''a''; to return in command mode press ''&lt;esc&gt;'' or ( ''&lt;ctrl&gt; ['' ). It can be confusing to remember if you're in command mode or insert mode (even though there's a bright marker in the left bottom of the ''vim'' screen :-). So remember: when you're in insert mode, ''&lt;esc&gt;'' will bring you to command mode; when you're already in command mode, ''&lt;esc&gt;'' does nothing (no harm done). So press ''&lt;esc&gt;'' two or three times, and you're sure to be in command mode. Another thing to remember: if you're in command mode and you start entering a number ''before'' a command, the command will get repeated that many times. The most used feature of this is deleting lines. Deleting the current line is done with the command ''dd''; deleting (for example) twelve lines can be accomplished using ''12dd''. Another example is the use of a number in front of G: command ''12G'' (use &lt;shift&gt;-g) will bring you to the beginning of the 12th line. A special number is zero; pressing 0 as the first character in a command means immediately going to the beginning of the line. ===Exiting vim=== {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Command !style="background:#ffdead;"|Output |- |:w |Save |- |:w ''filename'' |Save with this filename |- |:q |quit vim |- |:q! |quit without save |- |:wq |save and quit |} ===Cursor positioning=== {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Key(s) !style="background:#ffdead;"|Movement |- |h |one character back |- |j |down one line, same column |- |k |up one line, same column |- |l,&lt;space&gt; |one character forward |- |b |one word back (to beginning of previous word) |- |e |one word back (to end of previous word) |- |w |one word forward |- |&lt;enter&gt; |beginning of next line |- |0 (zero) |beginning of line |- |$ |end of line |- |''n''G |to beginning of line ''n''; if no number given, the last line of the file |- |:''n'' |also to beginning of line ''n'' (but this is visible as command) |- |} Note that h,j,k,l is one block on your (US) keyboard ===Searching=== {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Key(s) !style="background:#ffdead;"|Search |- |/''pattern'' |Moves the cursor to the next occurrence of ''pattern''; will wrap around to the beginning of the file from the last occurence |- |?''pattern'' |Moves the cursor backward to the previous occurrence of ''pattern''; will wrap around to the end of the file from the first occurence |- |n |repeats last pattern search (either forward or backward) |- |} ===Text insertion=== {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Key(s) !style="background:#ffdead;"|Effect |- |a |appends text after cursor & switches to Insert mode |- |A |appends text at the '''end''' of the line & switches to Insert mode |- |i |inserts text before cursor & switches to Insert mode |- |I |inserts text at the '''beginning''' of the line & switches to Insert mode |- |o |opens new line below the current line for text insertion & switches to Insert mode |- |O |opens new line '''above''' the current line for text insertion & switches to Insert mode |- |&lt;del&gt; |overwrites last character during text insertion |- |&lt;esc&gt; |stops text insertion. The escape key on the DECstations is the &lt;F11&gt; key |- |} ===Text deletion=== {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Key(s) !style="background:#ffdead;"|Effect |- |x |deletes character under the cursor |- |dd |deletes current line |- |dw |deletes word under the cursor |- |d) |deletes to the end of the current sentence (up to and including the dot) |- |D |deletes to the end of the current line |- |d$ |same (deletes to the end of the current line) |- |p |"paste", puts the buffer (e.g. text from the previous deletion) after the position of the cursor |- |P |"Paste", puts the buffer (e.g. text from the previous deletion) '''before''' the position of the cursor |- |} 6c5fefbc8979255bafcaa543df8f52b0d64c352e 0 1 1465 1458 2008-05-19T17:12:46Z Saruman! 2 added essential system software wikitext text/x-wiki <big>'''Welcome to SaruWiki.'''</big> This Wiki is intended to document bits and bobs about [http://www.kernel.org/ Linux] (and some Unix) in general, and [http://www.debian.org Debian] in particular. In it, [[SaruTeam|we]] wish to collect the tips and tricks of both [[SaruTeam|our own team of Linux admins]] and those of other interested users. Consult the [http://meta.wikimedia.org/wiki/Help:Contents User's Guide] for information on using this wiki's software. ---- <big>'''Main Content'''</big> * Setting up a [[Debian Etch base server]] is a howto on the installation of a very basic Linux box under Etch (it's actually not even a server yet). * The use of [[APT and aptitude]] is crucial to the concept of a Debian machine. * [[Roll your own kernel]] discusses the pros and cons of compiling your own kernel, and how to do it. * [[essential system software | Essential system software]] lists all (sets of) packages that we deem, well, essential. * The [[Firewall section]] is where we discuss "IPtables" (netfilter) and how we use it for firewalling. * The [[native IPsec tunnel]] section describes how to configure an IPsec tunnel. * Using ''md'' for [[software RAID]] contains our ideas and observations on redundancy. * [[Hardware monitoring]] is important for your server's health and reliability. * [[Database 101]] introduces you to MySQL. * [[Vmware_server|VMware Server basics]] gives some pointers on how to install VMware Server on a Debian server box. * Make your server a [[Microsoft PPTP server | Microsoft client compatible VPN Server ]]. ---- '''Note''': the Wiki admins reserve the right to edit or remove any content they feel is not suitable for this site, not relevant, (too) inaccurate or otherwise not in line with the intentions and spirit of the admin team. 0ebcf7107e949c7ceb4c411678fc8854333ca60c 1500 1465 2008-05-30T16:57:06Z Saruman! 2 iframe added wikitext text/x-wiki <big>'''Welcome to SaruWiki.'''</big> This Wiki is intended to document bits and bobs about [http://www.kernel.org/ Linux] (and some Unix) in general, and [http://www.debian.org Debian] in particular. In it, [[SaruTeam|we]] wish to collect the tips and tricks of both [[SaruTeam|our own team of Linux admins]] and those of other interested users. Consult the [http://meta.wikimedia.org/wiki/Help:Contents User's Guide] for information on using this wiki's software. ---- <big>'''Main Content'''</big> * Setting up a [[Debian Etch base server]] is a howto on the installation of a very basic Linux box under Etch (it's actually not even a server yet). * The use of [[APT and aptitude]] is crucial to the concept of a Debian machine. * [[Roll your own kernel]] discusses the pros and cons of compiling your own kernel, and how to do it. * [[essential system software | Essential system software]] lists all (sets of) packages that we deem, well, essential. * The [[Firewall section]] is where we discuss "IPtables" (netfilter) and how we use it for firewalling. * The [[native IPsec tunnel]] section describes how to configure an IPsec tunnel. * Using ''md'' for [[software RAID]] contains our ideas and observations on redundancy. * [[Hardware monitoring]] is important for your server's health and reliability. * [[Database 101]] introduces you to MySQL. * [[Vmware_server|VMware Server basics]] gives some pointers on how to install VMware Server on a Debian server box. * Make your server a [[Microsoft PPTP server | Microsoft client compatible VPN Server ]]. ---- '''Note''': the Wiki admins reserve the right to edit or remove any content they feel is not suitable for this site, not relevant, (too) inaccurate or otherwise not in line with the intentions and spirit of the admin team. ---- <iframe src="http://www.google.com/talk/service/badge/Show?tk=z01q6amlqld8jocej2ca891jl9dunqqra83nhehaoqpednb5skkur0fv70jsuavce4ii9ms5e9afdr8qmpsc1d9upni4jom8g1em3p1cvq1p5eo1ugv162fosgprdv867iuememlcogfle8n3dmcf97durjld85avnh8k5lm1&amp;w=200&amp;h=60" allowtransparency="true" frameborder="0" height="60" width="200"></iframe> 6f999595a701335c47cbef6e36d107ae60be7b84 1501 1500 2008-05-30T20:30:24Z Saruman! 2 changed SaruChat iframe to websiteFram wikitext text/x-wiki <big>'''Welcome to SaruWiki.'''</big> This Wiki is intended to document bits and bobs about [http://www.kernel.org/ Linux] (and some Unix) in general, and [http://www.debian.org Debian] in particular. In it, [[SaruTeam|we]] wish to collect the tips and tricks of both [[SaruTeam|our own team of Linux admins]] and those of other interested users. Consult the [http://meta.wikimedia.org/wiki/Help:Contents User's Guide] for information on using this wiki's software. ---- <big>'''Main Content'''</big> * Setting up a [[Debian Etch base server]] is a howto on the installation of a very basic Linux box under Etch (it's actually not even a server yet). * The use of [[APT and aptitude]] is crucial to the concept of a Debian machine. * [[Roll your own kernel]] discusses the pros and cons of compiling your own kernel, and how to do it. * [[essential system software | Essential system software]] lists all (sets of) packages that we deem, well, essential. * The [[Firewall section]] is where we discuss "IPtables" (netfilter) and how we use it for firewalling. * The [[native IPsec tunnel]] section describes how to configure an IPsec tunnel. * Using ''md'' for [[software RAID]] contains our ideas and observations on redundancy. * [[Hardware monitoring]] is important for your server's health and reliability. * [[Database 101]] introduces you to MySQL. * [[Vmware_server|VMware Server basics]] gives some pointers on how to install VMware Server on a Debian server box. * Make your server a [[Microsoft PPTP server | Microsoft client compatible VPN Server ]]. ---- '''Note''': the Wiki admins reserve the right to edit or remove any content they feel is not suitable for this site, not relevant, (too) inaccurate or otherwise not in line with the intentions and spirit of the admin team. ---- <websiteFrame> src="http://www.google.com/talk/service/badge/Show?tk=z01q6amlqld8jocej2ca891jl9dunqqra83nhehaoqpednb5skkur0fv70jsuavce4ii9ms5e9afdr8qmpsc1d9upni4jom8g1em3p1cvq1p5eo1ugv162fosgprdv867iuememlcogfle8n3dmcf97durjld85avnh8k5lm1&amp;w=200&amp;h=60" allowtransparency="true" border="0" height="60" width="200" name="GoogleChat with Saruman!" </websiteFrame> 6ac253501a4f940185ec8e5423dac0f61c55f37f 1502 1501 2008-05-30T20:32:59Z Saruman! 2 Adapted websiteFrame wikitext text/x-wiki <big>'''Welcome to SaruWiki.'''</big> This Wiki is intended to document bits and bobs about [http://www.kernel.org/ Linux] (and some Unix) in general, and [http://www.debian.org Debian] in particular. In it, [[SaruTeam|we]] wish to collect the tips and tricks of both [[SaruTeam|our own team of Linux admins]] and those of other interested users. Consult the [http://meta.wikimedia.org/wiki/Help:Contents User's Guide] for information on using this wiki's software. ---- <big>'''Main Content'''</big> * Setting up a [[Debian Etch base server]] is a howto on the installation of a very basic Linux box under Etch (it's actually not even a server yet). * The use of [[APT and aptitude]] is crucial to the concept of a Debian machine. * [[Roll your own kernel]] discusses the pros and cons of compiling your own kernel, and how to do it. * [[essential system software | Essential system software]] lists all (sets of) packages that we deem, well, essential. * The [[Firewall section]] is where we discuss "IPtables" (netfilter) and how we use it for firewalling. * The [[native IPsec tunnel]] section describes how to configure an IPsec tunnel. * Using ''md'' for [[software RAID]] contains our ideas and observations on redundancy. * [[Hardware monitoring]] is important for your server's health and reliability. * [[Database 101]] introduces you to MySQL. * [[Vmware_server|VMware Server basics]] gives some pointers on how to install VMware Server on a Debian server box. * Make your server a [[Microsoft PPTP server | Microsoft client compatible VPN Server ]]. ---- '''Note''': the Wiki admins reserve the right to edit or remove any content they feel is not suitable for this site, not relevant, (too) inaccurate or otherwise not in line with the intentions and spirit of the admin team. ---- <websiteFrame> website=http://www.google.com/talk/service/badge/Show?tk=z01q6amlqld8jocej2ca891jl9dunqqra83nhehaoqpednb5skkur0fv70jsuavce4ii9ms5e9afdr8qmpsc1d9upni4jom8g1em3p1cvq1p5eo1ugv162fosgprdv867iuememlcogfle8n3dmcf97durjld85avnh8k5lm1&amp;w=200&amp;h=60 allowtransparency=true border=0 height=60 width=200 name=GoogleChatwithSaruman! </websiteFrame> fa2993d8ae2ee4e26a86ef577f6a84ce6a833b24 1503 1502 2008-05-30T20:41:39Z Saruman! 2 equalsign = &#61; wikitext text/x-wiki <big>'''Welcome to SaruWiki.'''</big> This Wiki is intended to document bits and bobs about [http://www.kernel.org/ Linux] (and some Unix) in general, and [http://www.debian.org Debian] in particular. In it, [[SaruTeam|we]] wish to collect the tips and tricks of both [[SaruTeam|our own team of Linux admins]] and those of other interested users. Consult the [http://meta.wikimedia.org/wiki/Help:Contents User's Guide] for information on using this wiki's software. ---- <big>'''Main Content'''</big> * Setting up a [[Debian Etch base server]] is a howto on the installation of a very basic Linux box under Etch (it's actually not even a server yet). * The use of [[APT and aptitude]] is crucial to the concept of a Debian machine. * [[Roll your own kernel]] discusses the pros and cons of compiling your own kernel, and how to do it. * [[essential system software | Essential system software]] lists all (sets of) packages that we deem, well, essential. * The [[Firewall section]] is where we discuss "IPtables" (netfilter) and how we use it for firewalling. * The [[native IPsec tunnel]] section describes how to configure an IPsec tunnel. * Using ''md'' for [[software RAID]] contains our ideas and observations on redundancy. * [[Hardware monitoring]] is important for your server's health and reliability. * [[Database 101]] introduces you to MySQL. * [[Vmware_server|VMware Server basics]] gives some pointers on how to install VMware Server on a Debian server box. * Make your server a [[Microsoft PPTP server | Microsoft client compatible VPN Server ]]. ---- '''Note''': the Wiki admins reserve the right to edit or remove any content they feel is not suitable for this site, not relevant, (too) inaccurate or otherwise not in line with the intentions and spirit of the admin team. ---- <websiteFrame> website=http://www.google.com/talk/service/badge/Show?tk&#61;z01q6amlqld8jocej2ca891jl9dunqqra83nhehaoqpednb5skkur0fv70jsuavce4ii9ms5e9afdr8qmpsc1d9upni4jom8g1em3p1cvq1p5eo1ugv162fosgprdv867iuememlcogfle8n3dmcf97durjld85avnh8k5lm1&amp;w=200&amp;h=60 border=0 height=60 width=200 name=GoogleChatwithSaruman! allowtransparency=true </websiteFrame> cc01a8f0a2813ef8fb62414f6cd00a81c20b758c 1504 1503 2008-05-30T20:56:04Z Saruman! 2 added mediawiki wikitext text/x-wiki <big>'''Welcome to SaruWiki.'''</big> This Wiki is intended to document bits and bobs about [http://www.kernel.org/ Linux] (and some Unix) in general, and [http://www.debian.org Debian] in particular. In it, [[SaruTeam|we]] wish to collect the tips and tricks of both [[SaruTeam|our own team of Linux admins]] and those of other interested users. Consult the [http://meta.wikimedia.org/wiki/Help:Contents User's Guide] for information on using this wiki's software. ---- <big>'''Main Content'''</big> * Setting up a [[Debian Etch base server]] is a howto on the installation of a very basic Linux box under Etch (it's actually not even a server yet). * The use of [[APT and aptitude]] is crucial to the concept of a Debian machine. * [[Roll your own kernel]] discusses the pros and cons of compiling your own kernel, and how to do it. * [[essential system software | Essential system software]] lists all (sets of) packages that we deem, well, essential. * The [[Firewall section]] is where we discuss "IPtables" (netfilter) and how we use it for firewalling. * The [[native IPsec tunnel]] section describes how to configure an IPsec tunnel. * Using ''md'' for [[software RAID]] contains our ideas and observations on redundancy. * [[Hardware monitoring]] is important for your server's health and reliability. * [[Database 101]] introduces you to MySQL. * [[Vmware_server|VMware Server basics]] gives some pointers on how to install VMware Server on a Debian server box. * Make your server a [[Microsoft PPTP server | Microsoft client compatible VPN Server ]]. * How to install [[Mediawiki Installation | Mediawiki]] on your Debian server - like what you're looking at now. ---- '''Note''': the Wiki admins reserve the right to edit or remove any content they feel is not suitable for this site, not relevant, (too) inaccurate or otherwise not in line with the intentions and spirit of the admin team. ---- <websiteFrame> website=http://www.google.com/talk/service/badge/Show?tk&#61;z01q6amlqld8jocej2ca891jl9dunqqra83nhehaoqpednb5skkur0fv70jsuavce4ii9ms5e9afdr8qmpsc1d9upni4jom8g1em3p1cvq1p5eo1ugv162fosgprdv867iuememlcogfle8n3dmcf97durjld85avnh8k5lm1&amp;w=200&amp;h=60 border=0 height=60 width=200 name=GoogleChatwithSaruman! allowtransparency=true </websiteFrame> a5b59b76e8ea947eddd7257b0d8229ae5194361c 1511 1504 2008-06-08T12:54:28Z Saruman! 2 added System boot procedure section wikitext text/x-wiki <big>'''Welcome to SaruWiki.'''</big> This Wiki is intended to document bits and bobs about [http://www.kernel.org/ Linux] (and some Unix) in general, and [http://www.debian.org Debian] in particular. In it, [[SaruTeam|we]] wish to collect the tips and tricks of both [[SaruTeam|our own team of Linux admins]] and those of other interested users. Consult the [http://meta.wikimedia.org/wiki/Help:Contents User's Guide] for information on using this wiki's software. ---- <big>'''Main Content'''</big> * Setting up a [[Debian Etch base server]] is a howto on the installation of a very basic Linux box under Etch (it's actually not even a server yet). * The use of [[APT and aptitude]] is crucial to the concept of a Debian machine. * [[Roll your own kernel]] discusses the pros and cons of compiling your own kernel, and how to do it. * [[essential system software | Essential system software]] lists all (sets of) packages that we deem, well, essential. * The [[system boot procedure]] section explains what we can customise in the standard ways Debian boots. * The [[Firewall section]] is where we discuss "IPtables" (netfilter) and how we use it for firewalling. * The [[native IPsec tunnel]] section describes how to configure an IPsec tunnel. * Using ''md'' for [[software RAID]] contains our ideas and observations on redundancy. * [[Hardware monitoring]] is important for your server's health and reliability. * [[Database 101]] introduces you to MySQL. * [[Vmware_server|VMware Server basics]] gives some pointers on how to install VMware Server on a Debian server box. * Make your server a [[Microsoft PPTP server | Microsoft client compatible VPN Server ]]. * How to install [[Mediawiki Installation | Mediawiki]] on your Debian server - like what you're looking at now. ---- '''Note''': the Wiki admins reserve the right to edit or remove any content they feel is not suitable for this site, not relevant, (too) inaccurate or otherwise not in line with the intentions and spirit of the admin team. ---- <websiteFrame> website=http://www.google.com/talk/service/badge/Show?tk&#61;z01q6amlqld8jocej2ca891jl9dunqqra83nhehaoqpednb5skkur0fv70jsuavce4ii9ms5e9afdr8qmpsc1d9upni4jom8g1em3p1cvq1p5eo1ugv162fosgprdv867iuememlcogfle8n3dmcf97durjld85avnh8k5lm1&amp;w=200&amp;h=60 border=0 height=60 width=200 name=GoogleChatwithSaruman! allowtransparency=true </websiteFrame> 855e7e944fecdaee81fb7d3510aa70067e26820e 0 1423 1467 2008-05-22T21:15:52Z Saruman! 2 Apt/aptitude page started wikitext text/x-wiki ==Using APT and Aptitude== Your Debian system can easily be expanded, and also kept up-to-date with the latest security fixes, if you use Debian's beautiful [http://www.debian.org/doc/manuals/apt-howto/ch1.en.html APT (Advanced Packaging Technology)] tools. Of all available [http://en.wikipedia.org/wiki/Advanced_Packaging_Tool APT-based tools], we usually use the following: * apt-get, the command line utilities that go with APT; or * aptitude, a [http://en.wikipedia.org/wiki/Curses_%28programming_library%29 curses-based] frontend for APT. These APT-based tools are incredibly powerful and flexible, but we're not going to explain them fully here (for tuturials and whatnot, go [http://www.debian.org/doc/manuals/apt-howto/ here]). What we need to establish now, is how to configure APT, and how to use it. APT gets its information from a configuration file that can be found in ''/etc/apt''. Of these, the most important is ''sources.list'' because it defines what packages and updates can be installed from where, and even what version of Debian we want to maintain. For now let's just suffice to say that in the sources.list, you need to remove the references to the CD-ROm with which you installed the system, and specify which on-line repository you wish to use for installing and updating packages. To this end, open ''/etc/apt/sources.list'' with [[Vim | your favourite text editor]] while you are logged in as root. References to the CD-ROM look a bit like this: deb cdrom:[Debian GNU/Linux testing _Etch_ - Official Beta i386 CD Binary-1 20070317-21:45]/ etch contrib main Disable this line by putting a hash (#) in front of it (you could have more than one line beginning with ''deb cdrom:''). Now make sure you have a section that references one or more on-line repositories. This could make your ''sources.list'' look like this: <pre> # deb cdrom:[Debian GNU/Linux testing _Etch_ - Official Beta i386 CD Binary-1 20070317-21:45]/ etch contrib main deb ftp://ftp.nl.debian.org/debian/ etch main contrib deb-src ftp://ftp.nl.debian.org/debian/ etch main contrib deb http://security.debian.org/ etch/updates main contrib deb-src http://security.debian.org/ etch/updates main contrib # deb ftp://ftp.nl.debian.org/debian-volatile etch/volatile main contrib </pre> When you want to update, change, add software, or even remove software, you better update your APT system by running one of the following commands: * sudo apt-get update * sudo aptitude update * sudo aptitude, then press ''u'' Note: if you haven't installed [[sudo]] yet, then you can only run the commands as root, and they are then: ''apt-get update'', ''aptitude update'', and ''aptitude'' then ''u''. 1131134b934c5eac83d2046df8554b671e4c1956 0 1409 1469 1438 2008-05-23T19:41:31Z Saruman! 2 changed link wikitext text/x-wiki <big>'''Debian Etch Base Server setup'''</big> ==Getting the hardware== {| class="wikitable" border="1" |- |Note: in the following we're assuming you'll be assembling an x86 or x64 type of machine, as it has about the best price/performance ratio you could wish. Hardware costs for other platforms, e.g. IBM's Series p or HP 9000, can be much higher, while platforms like ARM are just not very powerful. Also, the availability of components and of help can be less than with the ubiquietous x86/x64 platforms. |} Naturally, before we can begin to install the operating system, we need to obtain the necessary hardware. Which hardware you require depends on what you want the server for; a testserver on which you will test only a single feature for a short while does not need the same quality of hardware as does a server that's supposed to act as a homeserver for many tasks for a long time. We'll assume your server will be like ours: a home server that must perform many tasks with sufficient performance for a few users, that's reliable and will last for a couple of years. So build or obtain a server with at least the following hardware: * a spacious casing with big, quiet cooling fans, like the [http://www.coolermaster.com/products/product.php?act=detail&id=317 one we have]; * an efficient, heavy-duty power supply that's rated high enough for your devices, and has a decent efficiency. For example, a [http://www.corsair.com/products/power_supplies.aspx Corsair HX520] power supply; * a server class motherboard, e.g. an [http://www.intel.com/products/server/index.htm?iid=home+hdr_nav2_server Intel] or [http://uk.asus.com/products.aspx?l1=9&l2=39&l3=263 AMD] based single-processor motherboard. DO NOT go for the cheapest motherboard you can find: if you pay peanuts, that's what you get. Server class motherboards have the quality, stability and durability you'll need from it, and usually also most of the needed peripherals, like multiple ethernet network cards on-board. Usually a Linux server doesn not require much in the way of video performance (and the screen will be used rarely, if ever), so any old integrated graphics will do. * a matching CPU - or multiple, if you think you need the power and the selected motherboard has the sockets. * a CD-ROM- or DVD-player * ''multiple'' harddisks - you'll want redundancy, because every harddisk fails at some time. The drive with your data on it will fail fatally when it is most inconvenient to you, and any data on it that you consider valuable will likely be lost forever. To make Murphy's work somewhat harder for him, we're going to store our data redundantly, so that if any drive in the server fails, we'll not lose our data or our server. Thus, get yourself at least two harddisks for your operating system, at least 40GiB in size (don't think you'll be able to buy smaller ones nowadays), and spanking new (NEVER use old harddisks for your production server, new ones are just too cheap to run that risk!). * (multipe) network card(s) (NICs) if your motherboard does not have enough NICs integrated on-board. You'll want a NIC for your network, and another one for your Internet connection; and possible a third one for the wireless segment of your network. Now build a machine out of the above, or have someone build it for you. ==Preparation of the hardware== (Note: in the following we're again assuming you're running an x86/x64 type of machine. Hardware requirements and preparation for other platforms, e.g. IBM's Series p or HP 9000, can differ significantly) Next, check the assembled hardware: * is the configuration complete? If it does not have a CD/DVDplayer from which it can boot, then installing the software gets more difficult - at least get an USB external DVDdrive or something like that. * are all components connected properly (memory DIMMs seated correctly in their sockets, AGP card inserted correctly into the AGP slot, et cetera) and are all cable connections made (multiple power cables to the motherboard, one power cable plus one data cable to each hard disk, etcetera)? Following this, you may hook up the machine. It's going to need power, and you will need at least a keyboard and a monitor attached. And if you want to use a Graphic User Interface to install, a mouse is required also. When you've ensured that everything is safe, you can turn on the machine, and continue to check it: * do all fans start to run when you turn on the machine? (if not, then '''quickly''' turn off your machine and correct the problem!) * does/do the hard disk(s) spin up? * do the power button and reset button operate correctly? * are the power led, HDD led and other display gadgetry functional? * when you let the machine power up, does it emit a single beep? And does it then show a Power-On Self Test screen (POST)? * Does it show the correct amount of memory in the POST screen? The correct number & speed of the CPU(s)? * Does the machine recognise all controller cards (SCSI, S-ATA etc)? And all attached DVD-drives and hard disks? * are all BIOSes/firmwares up to date? * If you have a hardware RAID controller, are your RAID arrays built already? * does the machine attempt to boot from at least the hard disk? ...et cetera. If there is any problem, or you want to update the BIOS or firmwares, it's best to do it before the operating system is installed. This Wiki, however, is not the place (yet) to get the information on how to accomplish these type of tasks. The last steps in the preparation of the hardware, are * to ensure that the machine can boot from CD/DVD, so that you can start installing Debian from it. It is possible to install Debian over the network, but that requires setting up a [http://www.debian-administration.org/articles/478 PXE Boot server] which is (currently) outside the scope of this wiki. * to connect the hardware to the Internet, so that it can get all required updates etcetera; please do ''not'' connect the box ''straight'' to the Internet, but make sure that it's safely behind a firewall, or failing that, a NAT router. By now the system should be almost ready to receive it's Operating System. But first we have an issue to tackle: that of redundancy. ==Software or hardware RAID== Your hard disks will fail. They absolutely will. It is never a question of "if", only of "when". So what will you do when the hard disk containing your complete operating system fails (besides pulling your hair out, that is)? What we propose is this: hard disks are pretty cheap nowadays, so let's use [http://en.wikipedia.org/wiki/Redundant_array_of_independent_disks RAID technology] to make our hard drive space resilient against failure of a whole drive. So first make sure that you have ''two'' disks of equal size instead of only one. Had you already been planning to use multiple disks already, then make sure you have at least ''one'' disk more than your space requirements prescribe; the space on that extra drive will provide the needed redundancy. Next, [[RAID fundamentals under Linux | click here]] to learn a bit more about RAID, to make the decision to use hardware-based and/or software-based RAID, and to plan your RAID arrays. In this example, we'll assume you're using hardware RAID on a RAID controller that's supported by the Debian installation software. This means that the installation software will "see" your RAID array(s) and present them as usable drives. ==Planning your network names== If your machine must become a part of an existing network, then it's almost certain that you already have a DNS domain in place; in that case: obtain the DNS suffix your machine will get (the DNS domain your machine will "belong" to). However, it's also possible that this machine is going to be the first machine in your new network, in which case the whole issue of DNS suffixes is wide open. If you need more information on DNS, go [[http://www.isc.org/sw/bind/arm95/Bv9ARM-all.html#id2564824 here]]. For now we'll assume you have (or will quickly obtain) a working knowledge of the DNS system. Here is our tip on choosing a DNS domain for your home network: * do '''not''' use a publicly registered domain name (e.g. "cocacola.com") for any machine that's not primarily intended to serve the public on the Internet; * for machines serving a private network, we urge you to use Top Level Domain name "lan" (to signify your machine is on a Local Area Network or LAN) * for the Domain Name itself, we suggest you use a level 2 name, like "saruman.lan", and not a level 3 name, like "mister.saruman.lan". This is only a short section on DNS, but remember that once a proper DNS system is in place, it's pretty much work to change it. At any rate, this section has most likely showed you that you need to put some thought into the DNS Domain Name design of your home network. OK, with this out of the way, we can get to installing the OS. ==Operating System installation== To install an Operating System (OS), it's kinda instrumental that you have one. Here, we're going to use [http://www.debian.org/intro/about Debian], the biggest [http://www.debian.org/intro/about#free Free] OS that we know of. Free stands for Freedom, but incidentally that Freedom also means it's gratis, an appealing aspect of Free. To get your own copy of Debian, go to their [http://www.debian.org/distrib/ download site] and obtain the latest [http://www.debian.org/releases/ Stable] image - in this wiki it's Debian 4.0, or "Etch" as it's also known. Besides the choice which release of Debian you want to run, you also have to know for which platform you're downloading (in our case: either ''amd64'' or ''i386'' depending on your hardware platform) and what kind of install you wish - if you have a working, fast Internet connection available at the time of install, then we recommend getting the [[http://www.debian.org/CD/netinst/ netinst] CD image; it's a relatively small CD, that'll be able to get you going, but gets most of the software you'll need straight from the 'net at install time. So, since in the example at hand we're installing on a Xeon server on which we wish to install 32-bits software, we'll download [http://cdimage.debian.org/debian-cd/4.0_r3/i386/iso-cd/debian-40r3-i386-netinst.iso debian-40r3-i386-netinst.iso], the latest netinstall image at the time of writing. Burn this to a CD-recordable and boot your prepared hardware platform from this CD. After booting from the CD, a friendly prompt invites you to indicate how you want to boot the CD. Your choices are listed under &lt;F3&gt;; we're going to use the standard Command Line installation, so we type "install"&lt;enter&gt; or just simply &lt;enter&gt;. {| class="wikitable" border="1" |- |We could easily use "installgui", in which case we'd have a nice fresh Graphical User Interface for our installation. ''We're'' not going to, because we're real men, and [http://isg.ee.ethz.ch/tools/realmen/ Real Men Don't Click]. Also, we've found that from the GUI it's hard to switch to a second console and then back. We could also opt for "expert" as installation method, because it gives a much finer grain of control, but we usually don't need that control, and can do without the barrage of extra questions that the "expert" installation method pose. Finally, we could opt for "expertgui", where we have both the barrage of extra questions ''and'' the GUI, neither of which we need. |} After the Linux kernel finishes initializing the machine, a simple text-based installer appears that immediately starts asking questions. Answer them according to your needs. Our example system uses the following choices: * Language: english * country: other &gt; Netherlands * keymap: American English (since we have a keyboard with US layout) Some installation software loads, and we get to the next phase: if you have multiple NICs in your machine (which we believe you ''should'' have!!), and if they're detected properly, then you're required to indicate which of the detected network interface cards (NIC) is going to be the "primary" NIC. {| class="wikitable" border="1" |- |Here, trouble could begin. If your machine has network cards that are '''not''' supported, then you'll see '''no''' cards here - but then how are you going to do a NetInstall? A solution would be to (temporarily) install a NIC that ''is'' supported, like a cheap Realtek card, or an old 3Com 905 card. Then, when the whole system is installed, up and running, you could compile a new kernel that contains support for your actual NICs, and when these work, remove the temporary NIC. For now, we'll assume that at least one of your NICs is recognised properly by the Debian installation routine. |} Select the card that's connected and has (indirect) access to Internet (again: it should ''not'' be connected straight to the wild wild web, but sit safely behind a firewall, at least until we've installed our own firewall); if at all possible, let it be the NIC that'll be connected to your home network itself, on the ''inside'' of your server. Let's assume that this NIC is designated ''eth0'' by the Debian installation. This card will now be configured using DHCP, so if you're on a network with a DHCP-server, the network will work straight away. If it's not, you can either configure the network manually or fix your DHCP-server and connection between it and ''eth0''. Next is one of the hardest questions that any OS installation is going to ask you: what will be the host name of the system? You could change it at any time in the future, but with lots of hassle, so you better choose wisely. Here are our tips: * do '''not''' name your machine after the user that's going to use it, e.g. "bernie-pc" (at some time in the future, Bernie's machine will be moved to Alice, so then Alice is working on "bernie-pc" which makes the situation quite unclear); * do '''not''' name your machine after the department or workgroup that's using it most, e.g. "accounting-srv" (same reasoning); * do '''not''' name your machine after it's main function, e.g. "printserver" (at some time in the future, the main function is moved to another machine, and/or an alternative function will become the main function of the machine); * do '''not''' name your machine after it's location, e.g. "srv-boston" (at some time in the future, the box will be moved to another location); * do '''not''' name your machine after it's hardware configuration, e.g. "ibmx346" (at some time in the future, either another xSeries x346 will be wheeled in, or the machine will be upgraded to accomodate increased use or overcome hardware problems - your "ibmx346" could suddenly be running on an xSeries x3650). What we feel are safe names for ''any'' machine in your network are true names, perhaps linked to a common theme: names of European cities, names of movie characters, names of countries or holiday destinations et cetera. Immediately following comes the question of the Domain Name. This is about a DNS domain, so effectively the installation program is asking which DNS suffix the host name should have; if the DHCP-server already provided something it'll be suggested, but you can override it if need be. In the preparatory phase, you'll have decided on continuation of your current DNS schema, or starting a new one. Either way, put the chosen DNS suffix in and press &lt;enter&gt;. ==Partitioning== Next comes the question of partitioning, or how to divide the available disk space into chunks for the server to use. This is a tricky subject, because if you put all storage space into one partition, then some day a runaway process will fill up the entire disk with useless logs, and the system will crash. On the other hand, if you divvy up all space into little chunks, then some application is going to need space in one of those partitions where there is none, even though there may be plenty in other partitions. To prevent both problems from occuring, we're going to use [http://tldp.org/HOWTO/LVM-HOWTO/whatisvolman.html Logical Volume Management (LVM)] so that we can provision enough space to start our server, but keep some space in reserve to apply when needed, where it'll be needed. So, we at Saruman.biz have put together a recommended standard partitioning scheme. The basis is this: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Partition !style="background:#ffdead;"|MD !style="background:#ffdead;"|LVG !style="background:#ffdead;"|LV-name !style="background:#ffdead;"|Size <br> (physical machine) !style="background:#ffdead;"|Size (VM) !style="background:#ffdead;"|File System !style="background:#ffdead;"|Mount point |- | 1 | /dev/md0 | &nbsp; | &nbsp; | 100MiB | 100MiB | ext3 | /boot |- | 2 | /dev/md1 | &nbsp; | &nbsp; | 3GiB | 1GiB | ext3 | / |- | rowspan="7" valign="top" | 3 | rowspan="7" valign="top" | /dev/md2 | rowspan="7" valign="top" style="background:lightgrey"| system | style="background:lightgrey" | swap | 1GiB<ref name="swap">Rule of thumb: twice the size of the machine's RAM, but no less than 256MiB and no more than 2GiB</ref> | 256MiB<ref name="swap"/> | swap | &nbsp; |- | style="background:lightgrey" | var | 2GiB | 1GiB | ext3 | /var |- | style="background:lightgrey" | appslog | 3GiB | - | ext3 | /var/appslog |- | style="background:lightgrey" | home | 1GiB<ref name="home">Note that this heavily depends on the purpose of the machine; if it is not to house any users, then (almost) no space is needed for /home. But on the other hand if e.g. a virtual user is to be used for keeping mailstores, or other service users need home space, then /home needs to be big enough for that.</ref> | 512MiB<ref name="home"/> | ext3 | /home |- | style="background:lightgrey" | usr | 3GiB | 3GiB | ext3 | /usr |- | style="background:lightgrey" | tmp | 1GiB | 512MiB | ext3 | /tmp |- | style="background:lightgrey" | opt | 1GiB | - | ext3 | /opt |- ! colspan="4" style="text-align:right"| Total ! 18.1GiB ! 6.9GiB ! colspan="2" | |- |} As you can see, the partition table works as follows: we assume that we wind up with 3 partitions, either on three separate software RAID arrays (''md0'' through ''md2'') or on one single hardware RAID array (in which case the 2nd column ''MD'' does not apply). The size of the partitions depends on your machine's make: for standard physical machines the 5th column does sensible suggestions, even though you could choose to have different sizes and of course different divisions altogether. If your machine happens to be a virtual one, running inside a [http://www.vmware.com/products/server/ VMware Server] or [http://www.vmware.com/products/vi/esx/ VMware ESX host], or the like, then you might want to start out with more modest partitions. The same holds for small servers that must run off Flash drives. Anyways, we're now at the Debian installation screen that lets us partition our disks. We're ''not'' going to use any of the "guided" partitionings, we go for "manual". Choosing that brings us to a screen showing all drives that the installation routine has detected, and all partitions on those drives that the installer can "see". We're going to do some assuming here once more: let's assume the drive(s) on which you want to install are visible, and are empty (containing no other partitions). <references/> ===Software RAID partitioning=== If you're to use software RAID, you now have to select the free space on the first drive, press &lt;enter&gt;, and then tell what you want to do with the free space: create a new partition, tell which size you want it to be (see table above), give the type of partition (primary), and give where on the disk it'll sit (the beginning). Next, a screen comes up that details how the partition you're requesting will be created. Here we make some changes: under "use as" we're going to select "physical volume for RAID". This clears all the other options in this screen, except for the "bootable" flag, which must be "on" for the first partition that we'll mount as ''/boot''. Now select "Done setting up the partition". Next, go to the free space on the second disk, and do ''exactly'' the same, to create an identical physical volume for RAID - if it's the first partition, select the "bootable" flag as well (we'll want to be able to boot from this second disk if the first disk fails, right?). Then go back to the rest of the free space on the first disk, make the second physical volume for RAID, duplicate it on the second disk. Then, go back to the rest of the free space on the first disk, make the third physical volume for RAID, and again duplicate it on the second disk. If you now go back to the "partition disks" overview, you'll see all the partitions you've specified listed on their respective disks. But at the top an extra option has appeared, called "configure software RAID". When you now select this option, the installer will ask if it may write the changes you've made to disk. This actually creates the partition tables on the disks. ===Hardware RAID partitioning=== Now, if you have hardware RAID, then on your first (boot) disk just make 3 partitions, in the following manner: Select the free space on the intended boot disk, press &lt;enter&gt;, select "create a new partition", and fill out the desired size (100MB). Type is primary, location is beginning of the disk, and in the details of the partition, we only need to change the Mount point to "/boot", and set the Bootable flag to "On". Then we're "Done setting up this partition". The second partition is made the same way, but the desired size is 3GB, the Mount point is "/", and the Bootable flag remains off. Again, we're "Done setting up this partition". The third partition is again a primary partition, it takes up the entire rest of the disk, but the type is not ext3, but "physical volume for LVM". Again, we're "Done setting up this partition". But now from the main partitioner screen, we can access "Configure the Logical Volume Manager". The installer asks if it can write out the choices made to the disk, and then enters the LVM setup screen, which begins with a summary explaining that you have one Free Physical Volume, and nothing more. We now create a Volume Group (VG), which (in accordance to our partitioning standard) we'll call "system". In this VG, we'll add all Physical Volumes (being the one partition we've designated so in the previous step) using the space bar. Now we repeat the following process seven times: * select "Create Logical Volume" * select Volume Group "System" * give the LV Name (from the table, e.g. swap, var etc) * give the LV size (from the table, e.g. 1GB for swap etc) After this, we can select "Finish", the partitioner creates the seven LVs, and we're back at the partitioner screen, where there are now 7 extra "disks", with names such as ''LVM VG system, LV appslog - 3.2GB Linux device mapper''. Each of these "disks" has one block of empty space, which we now assign: seven times we repeat the following process: * select the unassigned chunk of empty space of an LV (e.g. appslog) and press &lt;enter&gt;; * Change "Use as: do not use" into the desired filesystem (ext3 - only the LV "swap" gets as filesystem type "swap area") * Change the mount point from "none" to the one corresponding with the name of the LV (note: the swap LV has no mountpoint; the appslog mountpoint must be entered manually as "/var/appslog") * If so desired, a label can be assigned to the partition (we usually don't) * select "Done setting up the partition" Once all this is done, we can look over the configuration once more, and then select "Finish partitioning and write changes to disk". A summary configuration screen will show, and we'll affirm with "yes" that these partitions can indeed be formatted. After some formatting screens flashing by (unless your partitions are particularly big, your system is particularly slow, or something goes wrong) the installation procedure continues. ==Final installer steps== Next comes one '''VERY''' important question: what to use as root password? We cannot stress this enough: choose a SAFE password! Do NOT go for an easy-to-remember one, go for STRONG and SAFE. There are tools to help you generate strong passwords, like [http://www.pctools.com/guides/password/ this page]: use them! We strongly suggest 10 characters or more, including letters, mixed case, and numbers, so something like ''SuCRe4hecH'' (do NOT use this, generate your own!). Next, give the full name of the principal user of this server (your own, we assume), give the login-name (your given name, we assume), and a corresponding password. Again, use a SAFE password. As long as you don't make your principal user equivalent to root, you might go for a slightly weaker password (8 characters instead of 10), but we rather suggest you make the password just as strong (and different from!) the root password. After entering the details of these two users "root" and "you", the Debian installer will ask you how it can contact the Debian archives, in the dialoge "configure the package manager". For the NetInstall version of Debian, this is as good as mandatory. So here, we say "yes, use a Network Mirror", and in the following list select the country in which we are (in our case: the Netherlands), so the installer can present us with a number of network mirrors "close by". We select ftp.nl.debian.org. Next screen: should you be behind a proxy server, then it's possible to specify that here. And then the test: the system will say "scanning the mirror..." and try to contact the specified mirror. If it does not succeed, then there is either a network problem, a problem with this box's network card, or you've not specified the mirror or proxy correctly - so fix it. You'll know the network mirror has succesfully been contacted when the next dialogue appears - currently "configuring popularity-contest". Answer this question as you please. And then one of the last "big" questions: Software Selection. In this dialogue, you can easily select bundles of software to be installed. The choices are currently: * Desktop environment * Web server * Print server * DNS server * File server * Mail server * SQL database * Laptop * Standard system (selected by default) We have to make a little confession here: we've never before used this option in the installer. In fact, we even deselect the Standard System, so as to minimize the number of software packages that the base installation of our server contains. This makes it more work to manually add packages later, but we feel it gives us more control and understanding of our systems. So if you are like us: deselect the Standard System entry, and select Continue. The next dialogue handles the installation of the [http://www.gnu.org/software/grub/ ''grub'' bootloader]. Unless your disks weren't empty and you're attempting to make this system multiboot, you'll most likely get a question if you'll allow the installer to install ''grub'' into the boot sector of the first hard disk. We'll confirm with "Yes". After the installation of grub is completed, the CD-ROM is ejected, and the system is ready to reboot into Debian Etch. Remove the CD and select "Continue" ==Finishing up the installation== The system should reboot into Debian. This means you should see the following boot sequence: * your machine's standard POST messages * then, a blue grub menu on a black screen, with two entries: ** Debian GNU/Linux, kernel 2.6.&lt;something&gt; ** Debian GNU/Linux, kernel 2.6.&lt;something&gt (single-user mode); * then, after a default time-out, the first grub option will go into effect, and the Linux kernel is started. Lots of cryptic messages in grey-on-black will scroll by, until the last few lines read: "Debian GNU/Linux 4.0 &lt;hostname&gt; tty1" and "&lt;hostname&gt; login:" If your system does not reach this login, and/or some horrible error messages appear anywhere in this boot sequence, then you've got some extra work ahead. For now we'll assume you've reached the login prompt without problem. Log in as the principal user (try to avoid logging in as root! That's BAD practice!). Once logged in, save a copy of the boot messages using ''sudo dmesg > boot.txt'' or whatever you like. Then look through the boot messages, e.g. with ''vi -R boot.txt''. Furthermore, [[APT_and_aptitude | use Aptitude]] to make sure ''all'' your software is updated to the latest version. Done! Your base system is ready. You probably now want to [[essential system software | install essential software]], [[make your own kernel]] and [[connect your server to the Internet]]. ce715f216de82286c4dc82cd411fc892e81b0401 6 1424 1470 2008-05-23T20:35:44Z Saruman! 2 sudo make me a sandwich - okay wikitext text/x-wiki sudo make me a sandwich - okay b12b016bdeae284f4ba2600568011967a67ccb85 0 1425 1472 2008-05-23T20:58:38Z Saruman! 2 wikitext text/x-wiki Sudo (''Super User Do'') is your friend in many cases where security is involved. It is perhaps best described with this picture:<br> [[Image:sudo.jpg|Make me a sandwich. - What? Make it yourself. - Sudo make me a sandwich. - Okay.]]<br> So what does this command sudo do? In short, it allows a user to run a command with the security privileges of a different user. It is most often used to run programs that require root privileges, while the user himself is not logged in as root. To install sudo on a [[Debian_Etch_base_server | freshly installed server]], you really have to be root, so either log in at the console as root, or log in as your user account and then run the command ''su -''; the minus after the su command makes you inherit the whole profile of the superuser (root). When you now type in ''whoami'', you'll see that the system believes you really are root now.<br> With the superpowers of root, you can now install the ''sudo'' package by invoking [[APT_and_aptitude | APT]] in the following manner: apt-get install sudo After this command installs the ''sudo'' package for you, you can configure it by editing the newly-appeared file ''/etc/sudoers''. It is possible to edit this file ''sudoers'' with any editor (if you're root), but you better use ''visudo''. This command by default invokes ''[[Vim | vi]]'' as the editor (actually, ''[[Vim]]'' on Debian), and makes sure you don't screw up the ''sudoers'' file while editing it. If you try to save it with a syntax error in it, then ''visudo'' will warn you about the error, and ask you if you want to exit without saving, go back and edit the error, or save the file with the error in it anyways (dangerous, because if ''visudo'' believes there is a syntax error, then so will ''sudo'', so it won't run, so nobody on this system can sudo anymore until the syntax error is fixed). We strongly encourage you to ''NOT'' log in as root if it can be avoided at all, and ''sudo'' helps you a lot. Most of the time, you're administering your system by just looking at all kinds of files, mostly logfiles. These are often world-readable anyway, so you don't have to be root to read them anyway. 19e3dfc597cd84c2752fc436d6d17265a28525c5 0 1426 1473 2008-05-24T18:33:26Z Saruman! 2 wikitext text/x-wiki ==Project List== The following projects need to be done on the SaruWiki Admin Team home servers ===Priority 1=== # Create a startup script for setting ''/proc/sys'' # Create a startup script for setting network routes # Create an IPtables parser script (the ''"Iceditch"'' project) # Installation of a certificate authority # Reconfiguration of ''OpenSSH'' to use certificates instead of passwords # Installation and configuration of ''[http://www.debian-administration.org/articles/585 OpenLDAP]'' to replace ''passwd'' # Reconfiguration of ''SaMBa'' to use ''OpenLDAP'' # Reconfiguration of ''Horde3'' to use ''OpenLDAP'' # Reconfiguration of ''postfix/courier'' Virtual Mailbox setup to use ''OpenLDAP'' ===Priority 2=== # Configuration of WebDAV on Apache2 # The following projects are research projects only # ''IET'' iSCSI Enterprise Target 85e3f233a04ec5b77d4a0d231f6ba137dece177c 1474 1473 2008-05-24T19:08:56Z Saruman! 2 Page started wikitext text/x-wiki ==Project List== The following projects need to be done on the SaruWiki Admin Team home servers ===Priority 1=== # Create a startup script for setting ''/proc/sys'' # Create a startup script for setting network routes # Create an IPtables parser script (the ''"Iceditch"'' project) # Installation and configuration of ''[http://www.debian-administration.org/articles/585 OpenLDAP]'' to replace ''passwd'' # Reconfiguration of ''SaMBa'' to use ''OpenLDAP'' # Reconfiguration of ''Horde3'' to use ''OpenLDAP'' # Reconfiguration of ''postfix/courier'' Virtual Mailbox setup to use ''OpenLDAP'' ===Priority 2=== # Installation of a certificate authority # Reconfiguration of ''OpenSSH'' to use certificates instead of passwords # Configuration of WebDAV on Apache2 ===Priority 3=== - no prio 3 projects at the moment- ==Priority 4== The following projects are research projects only, so they're listed under Prio 4: # ''IET'' iSCSI Enterprise Target 77458341ad0b8ba82794f6d6fa4a3a9f38d90134 1475 1474 2008-05-24T19:16:19Z Saruman! 2 added HTB and iSCSI initiator wikitext text/x-wiki ==Project List== The following projects need to be done on the SaruWiki Admin Team home servers ===Priority 1=== # Create a startup script for setting ''/proc/sys'' # Create a startup script for setting network routes # Create an IPtables parser script (the ''"Iceditch"'' project) # Installation and configuration of ''[http://www.debian-administration.org/articles/585 OpenLDAP]'' to replace ''passwd'' # Reconfiguration of ''SaMBa'' to use ''OpenLDAP'' # Reconfiguration of ''Horde3'' to use ''OpenLDAP'' # Reconfiguration of ''postfix/courier'' Virtual Mailbox setup to use ''OpenLDAP'' ===Priority 2=== # Installation of a certificate authority # Reconfiguration of ''OpenSSH'' to use certificates instead of passwords ===Priority 3=== # Configuration of WebDAV on Apache2 # Configure traffic shaping measures, e.g. [http://werner.orkz.net/howtos/HTB%20bandwidth%20limiting%20in%20Linux%20HOWTO.html HTB] ===Priority 4=== The following projects are research projects only, so they're listed under Prio 4: # ''[http://iscsitarget.sourceforge.net IET]'' iSCSI Enterprise Target: have a Linux server become an iSCSI target # ''[http://www.howtoforge.com/iscsi_on_linux iSCSI initiator on Linux] 305c36f944935621edd8afb42be0b9edb0ace908 1481 1475 2008-05-25T10:01:21Z Saruman! 2 added VoIP wikitext text/x-wiki ==Project List== The following projects need to be done on the SaruWiki Admin Team home servers ===Priority 1=== # Create a startup script for setting ''/proc/sys'' # Create a startup script for setting network routes # Create an IPtables parser script (the ''"Iceditch"'' project) # Installation and configuration of ''[http://www.debian-administration.org/articles/585 OpenLDAP]'' to replace ''passwd'' # Reconfiguration of ''SaMBa'' to use ''OpenLDAP'' # Reconfiguration of ''Horde3'' to use ''OpenLDAP'' # Reconfiguration of ''postfix/courier'' Virtual Mailbox setup to use ''OpenLDAP'' ===Priority 2=== # Installation of a certificate authority # Reconfiguration of ''OpenSSH'' to use certificates instead of passwords # Installation of [http://www.asterisk.org/ Asterisk], to use [http://www.xs4all.nl/helpdesk/bellen/ XS4all VoIP] ===Priority 3=== # Configuration of WebDAV on Apache2 # Configure traffic shaping measures, e.g. [http://werner.orkz.net/howtos/HTB%20bandwidth%20limiting%20in%20Linux%20HOWTO.html HTB] ===Priority 4=== The following projects are research projects only, so they're listed under Prio 4: # ''[http://iscsitarget.sourceforge.net IET]'' iSCSI Enterprise Target: have a Linux server become an iSCSI target # ''[http://www.howtoforge.com/iscsi_on_linux iSCSI initiator on Linux] 80e3385767949613ebe0b968567db381d392128c 1482 1481 2008-05-25T10:23:33Z Saruman! 2 added Digium card to VoIP project, and added MythTV project wikitext text/x-wiki ==Project List== The following projects need to be done on the SaruWiki Admin Team home servers ===Priority 1=== # Create a startup script for setting ''/proc/sys'' # Create a startup script for setting network routes # Create an IPtables parser script (the ''"Iceditch"'' project) # Installation and configuration of ''[http://www.debian-administration.org/articles/585 OpenLDAP]'' to replace ''passwd'' # Reconfiguration of ''SaMBa'' to use ''OpenLDAP'' # Reconfiguration of ''Horde3'' to use ''OpenLDAP'' # Reconfiguration of ''postfix/courier'' Virtual Mailbox setup to use ''OpenLDAP'' ===Priority 2=== # Installation of a certificate authority # Reconfiguration of ''OpenSSH'' to use certificates instead of passwords # Installation of [http://www.asterisk.org/ Asterisk], to use [http://www.xs4all.nl/helpdesk/bellen/ XS4all VoIP] together with [http://www.telec.nl/producten/p55455/digium_pci_4-poort_a_b-kaart_1x_fxo_3x_fxs_(tdm431b).html KPN analog telephone lines]. ===Priority 3=== # Configuration of WebDAV on Apache2 # Configure traffic shaping measures, e.g. [http://werner.orkz.net/howtos/HTB%20bandwidth%20limiting%20in%20Linux%20HOWTO.html HTB] # Configure [http://www.mythtv.org/ MythTV] ===Priority 4=== The following projects are research projects only, so they're listed under Prio 4: # ''[http://iscsitarget.sourceforge.net IET]'' iSCSI Enterprise Target: have a Linux server become an iSCSI target # ''[http://www.howtoforge.com/iscsi_on_linux iSCSI initiator on Linux] d00c6a57343083346e7352bddc0726780bf4e641 1495 1482 2008-05-30T06:55:28Z Saruman! 2 added asterisk project page wikitext text/x-wiki ==Project List== The following projects need to be done on the SaruWiki Admin Team home servers ===Priority 1=== # Create a startup script for setting ''/proc/sys'' # Create a startup script for setting network routes # Create an IPtables parser script (the ''"Iceditch"'' project) # Installation and configuration of ''[http://www.debian-administration.org/articles/585 OpenLDAP]'' to replace ''passwd'' # Reconfiguration of ''SaMBa'' to use ''OpenLDAP'' # Reconfiguration of ''Horde3'' to use ''OpenLDAP'' # Reconfiguration of ''postfix/courier'' Virtual Mailbox setup to use ''OpenLDAP'' ===Priority 2=== # Installation of a certificate authority # Reconfiguration of ''OpenSSH'' to use certificates instead of passwords # Installation of [http://www.asterisk.org/ Asterisk], to use [http://www.xs4all.nl/helpdesk/bellen/ XS4all VoIP] together with [http://www.telec.nl/producten/p55455/digium_pci_4-poort_a_b-kaart_1x_fxo_3x_fxs_(tdm431b).html KPN analog telephone lines] => [[project page | Asterisk Project Page]] ===Priority 3=== # Configuration of WebDAV on Apache2 # Configure traffic shaping measures, e.g. [http://werner.orkz.net/howtos/HTB%20bandwidth%20limiting%20in%20Linux%20HOWTO.html HTB] # Configure [http://www.mythtv.org/ MythTV] ===Priority 4=== The following projects are research projects only, so they're listed under Prio 4: # ''[http://iscsitarget.sourceforge.net IET]'' iSCSI Enterprise Target: have a Linux server become an iSCSI target # ''[http://www.howtoforge.com/iscsi_on_linux iSCSI initiator on Linux] 9f5a8404603a3a91b2502551ca92515b5300f879 1498 1495 2008-05-30T07:17:49Z Saruman! 2 reverting project page creation wikitext text/x-wiki ==Project List== The following projects need to be done on the SaruWiki Admin Team home servers ===Priority 1=== # Create a startup script for setting ''/proc/sys'' # Create a startup script for setting network routes # Create an IPtables parser script (the ''"Iceditch"'' project) # Installation and configuration of ''[http://www.debian-administration.org/articles/585 OpenLDAP]'' to replace ''passwd'' # Reconfiguration of ''SaMBa'' to use ''OpenLDAP'' # Reconfiguration of ''Horde3'' to use ''OpenLDAP'' # Reconfiguration of ''postfix/courier'' Virtual Mailbox setup to use ''OpenLDAP'' ===Priority 2=== # Installation of a certificate authority # Reconfiguration of ''OpenSSH'' to use certificates instead of passwords # Installation of [http://www.asterisk.org/ Asterisk], to use [http://www.xs4all.nl/helpdesk/bellen/ XS4all VoIP] together with [http://www.telec.nl/producten/p55455/digium_pci_4-poort_a_b-kaart_1x_fxo_3x_fxs_(tdm431b).html KPN analog telephone lines]. ===Priority 3=== # Configuration of WebDAV on Apache2 # Configure traffic shaping measures, e.g. [http://werner.orkz.net/howtos/HTB%20bandwidth%20limiting%20in%20Linux%20HOWTO.html HTB] # Configure [http://www.mythtv.org/ MythTV] ===Priority 4=== The following projects are research projects only, so they're listed under Prio 4: # ''[http://iscsitarget.sourceforge.net IET]'' iSCSI Enterprise Target: have a Linux server become an iSCSI target # ''[http://www.howtoforge.com/iscsi_on_linux iSCSI initiator on Linux] d00c6a57343083346e7352bddc0726780bf4e641 0 1427 1476 2008-05-24T20:32:23Z Saruman! 2 Page started wikitext text/x-wiki ==PRO's and Con's== There are both advantages and disadvantages to compiling your own Linux kernel. This is an attempt at siding the pro's and con's, as we see them ===PRO=== * It's fun! (no, really!) * Better performance than a stock Debian kernel, because of system specific optimizations * Better hardware support, because we can use a newer kernel with newer drivers * Extra features, because we can use a newer kernel with those newer features ===CON=== * No automatic security system à la [[APT_and_aptitude | APT]]: if there's a security issue in the kernel that you're using, you'll have to find out about it, and then compile a new kernel. As con's go, this is a pretty big one, we reckon. Still, we run our own kernels... * You'll need to delve into hardware specific things, expressed in obscure kernel-hacking terms (what's "sparse memory support" for, anyway?) * Like everything, this takes time to master, and time to implement. Time spent on kernel compiling tasks (be it learning or executing) cannot be spent on other tasks ==Prerequisites== To compile your own kernel, you'll need some software. First up, you'll need to install the following packages, using [[APT_and_aptitude | "apt-get install &lt;package&gt;" or ''aptitude'']]. This is the list of packages we advise you to install: bzip2 ftp make libncurses5-dev (lus all its dependencies, including the ''gcc'' GNU C Compiler) Now it's time to get that kernel. To get it on a [[Debian_Etch_base_server | base server]], there are many ways; we'll outline two of them. ===Putting a kernel source on your server using WinSCP=== This is pretty easy, although it requires the following things # First up, you'll need to have the [[OpenSSH_server | SSH server]] installed (which we presuppose anyway) # Next, you'll need a computer on your network running Microsoft Windows, on which you need to install [http://winscp.net/eng/download.php WinSCP]. # After installing WinSCP, you start it up, fill in the host name or IP number of your server, your user name (as it exists on the Debian server, and which must have rights to use the SSH server), and click "save" (we advise you never to save your password in WinSCP for security reasons). # After saving the SSH account, you can find it under "stored sessions"; select it and click "login". A login window should appear, and you're asked for your password. After providing that, you're presented with a GUI, that allows you to copy and move files from and to the server. While you can theoretically save to and read from any location on the server, restrictions apply that have to do with the rights of the ordinary user that you are, so for simplicity we assume you'll put files in your home directory (e.g. ''/home/saruman''), and then from a shell on the server move the files to the proper location. # Now, you download the kernel source from the famous [http://kernel.org/ kernel.org]. From a European location, the latest v2.6 kernel source can be found [http://www.eu.kernel.org/pub/linux/kernel/v2.6/ in here]. Download the newest file that is named "linux-2.6.xxxxxx.tar.bz2" (like [http://www.eu.kernel.org/pub/linux/kernel/v2.6/linux-2.6.25.4.tar.gz linux-2.6.25.4.tar.bz2]), or alternatively, the same file in .gz instead of .bz2. The bz2 files are compressed slightly better, but uncompressing it requires the bzip2 program, which is not available on every Unix platform - fortunately it is on Debian. # Use WinSCP to upload the kernel source file to your home directory on the server ===Getting the kernel source on your server straight from the 'Net=== ===Extracting the kernel source=== # Log on to the server using your user account, either onto the console, or on an SSH shell (e.g. using PuTTy on a Windows client) # 0f3a4b5d5714c6b3bea0ac41d6ad51a8a8da0bc8 1477 1476 2008-05-24T21:35:57Z Saruman! 2 expounded "getting the kernel" wikitext text/x-wiki ==PRO's and Con's== There are both advantages and disadvantages to compiling your own Linux kernel. This is an attempt at siding the pro's and con's, as we see them ===PRO=== * It's fun! (no, really!) * Better performance than a stock Debian kernel, because of system specific optimizations * Better hardware support, because we can use a newer kernel with newer drivers * Extra features, because we can use a newer kernel with those newer features ===CON=== * No automatic security system à la [[APT_and_aptitude | APT]]: if there's a security issue in the kernel that you're using, you'll have to find out about it, and then compile a new kernel. As con's go, this is a pretty big one, we reckon. Still, we run our own kernels... * You'll need to delve into hardware specific things, expressed in obscure kernel-hacking terms (what's "sparse memory support" for, anyway?) * Like everything, this takes time to master, and time to implement. Time spent on kernel compiling tasks (be it learning or executing) cannot be spent on other tasks ==Prerequisites== To compile your own kernel, you'll need some software. First up, you'll need to install the following packages, using [[APT_and_aptitude | "apt-get install &lt;package&gt;" or ''aptitude'']]. This is the list of packages we advise you to install (if they're not installed already): sudo bzip2 ftp make libncurses5-dev (plus all its dependencies, including the ''gcc'' GNU C Compiler) Now it's time to get that kernel. To get it on a [[Debian_Etch_base_server | base server]], there are many ways; we'll outline two of them. ===Putting a kernel source on your server using WinSCP=== This is pretty easy, although it requires the following things # First up, you'll need to have the [[OpenSSH_server | SSH server]] installed (which we presuppose anyway) # Next, you'll need a computer on your network running Microsoft Windows, on which you need to install [http://winscp.net/eng/download.php WinSCP]. # After installing WinSCP, you start it up, fill in the host name or IP number of your server, your user name (as it exists on the Debian server, and which must have rights to use the SSH server), and click "save" (we advise you never to save your password in WinSCP for security reasons). # After saving the SSH account, you can find it under "stored sessions"; select it and click "login". A login window should appear, and you're asked for your password. After providing that, you're presented with a GUI, that allows you to copy and move files from and to the server. While you can theoretically save to and read from any location on the server, restrictions apply that have to do with the rights of the ordinary user that you are, so for simplicity we assume you'll put files in your home directory (e.g. ''/home/saruman''), and then from a shell on the server move the files to the proper location. # Now, you download the kernel source from the famous [http://kernel.org/ kernel.org]. From a European location, the latest v2.6 kernel source can be found [http://www.eu.kernel.org/pub/linux/kernel/v2.6/ in here]. Download the newest file that is named "linux-2.6.xxxxxx.tar.bz2" (like [http://www.eu.kernel.org/pub/linux/kernel/v2.6/linux-2.6.25.4.tar.gz linux-2.6.25.4.tar.bz2]), or alternatively, the same file in .gz instead of .bz2. The bz2 files are compressed slightly better, but uncompressing it requires the bzip2 program, which is not available on every Unix platform - fortunately it is on Debian. # Use WinSCP to upload the kernel source file to your home directory on the server ===Getting the kernel source on your server straight from the 'Net=== # Log in to your server using your user account # use ''ftp ftp.eu.kernel.org'' to connect to the kernel website; use username "anonymous" and password "whatever" (when you use username anonymous, the password doesn't get checked). ## if you type the command "lcd" the program should respond with ''"/home/&lt;yourname&gt;"'', which is your home directory on your server ## if you type the command "pwd" the program should respond with ''"/"'', to indicate you're at the root folder of the kernel.org FTP server ## if you type the command "cd pub/linux/kernel/v2.6" the program should respond with "250 Directory successfully changed.". Type ''pwd'' to check. ## ''dir'' lets you see the contents of the remote directory, and ''dir linux-2.6.2*.bz2'' limits the listing to managable sizes ## ''get linux-2.6.25.4.tar.bz2'' will copy the indicated kernel source file to your home directory; the ''ftp'' client will end the transfer with a message like "226 File send OK." # now you can exit the ftp client with ''exit'' ===Extracting the kernel source=== # Log on to the server using your user account, either onto the console, or on an SSH shell (e.g. using PuTTy on a Windows client) # Move the kernel source file from your home directory to the directory ''/usr/src'', change the owner of the file to root:root, and unpack the file using bzip2 (or gzip if you've downloaded the .tar.gz file): sudo mv linux-2.6.25.4.tar.bz2 /usr/src cd /usr/src 631dd784994bd40460981165a67b59ef93075048 1478 1477 2008-05-25T08:01:29Z Saruman! 2 added note about module compilation wikitext text/x-wiki ==PRO's and Con's== There are both advantages and disadvantages to compiling your own Linux kernel. This is an attempt at siding the pro's and con's, as we see them ===PRO=== * It's fun! (no, really!) * Better performance than a stock Debian kernel, because of system specific optimizations * Better hardware support, because we can use a newer kernel with newer drivers <ref>note that if for instance the Debian stock kernel does not support your network card, then you really must do something with kernel compilation. You'd have the choice of either compiling a whole kernel, or compiling a module for your network card against the stock kernel</ref> * Extra features, because we can use a newer kernel with those newer features ===CON=== * No automatic security system à la [[APT_and_aptitude | APT]]: if there's a security issue in the kernel that you're using, you'll have to find out about it, and then compile a new kernel. As con's go, this is a pretty big one, we reckon. Still, we run our own kernels... * You'll need to delve into hardware specific things, expressed in obscure kernel-hacking terms (what's "sparse memory support" for, anyway?) * Like everything, this takes time to master, and time to implement. Time spent on kernel compiling tasks (be it learning or executing) cannot be spent on other tasks '''Notes''' <references/> ==Prerequisites== To compile your own kernel, you'll need some software. First up, you'll need to install the following packages, using [[APT_and_aptitude | "apt-get install &lt;package&gt;" or ''aptitude'']]. This is the list of packages we advise you to install (if they're not installed already): sudo bzip2 ftp make libncurses5-dev (plus all its dependencies, including the ''gcc'' GNU C Compiler) Now it's time to get that kernel. To get it on a [[Debian_Etch_base_server | base server]], there are many ways; we'll outline two of them. ===Putting a kernel source on your server using WinSCP=== This is pretty easy, although it requires the following things # First up, you'll need to have the [[OpenSSH_server | SSH server]] installed (which we presuppose anyway) # Next, you'll need a computer on your network running Microsoft Windows, on which you need to install [http://winscp.net/eng/download.php WinSCP]. # After installing WinSCP, you start it up, fill in the host name or IP number of your server, your user name (as it exists on the Debian server, and which must have rights to use the SSH server), and click "save" (we advise you never to save your password in WinSCP for security reasons). # After saving the SSH account, you can find it under "stored sessions"; select it and click "login". A login window should appear, and you're asked for your password. After providing that, you're presented with a GUI, that allows you to copy and move files from and to the server. While you can theoretically save to and read from any location on the server, restrictions apply that have to do with the rights of the ordinary user that you are, so for simplicity we assume you'll put files in your home directory (e.g. ''/home/saruman''), and then from a shell on the server move the files to the proper location. # Now, you download the kernel source from the famous [http://kernel.org/ kernel.org]. From a European location, the latest v2.6 kernel source can be found [http://www.eu.kernel.org/pub/linux/kernel/v2.6/ in here]. Download the newest file that is named "linux-2.6.xxxxxx.tar.bz2" (like [http://www.eu.kernel.org/pub/linux/kernel/v2.6/linux-2.6.25.4.tar.gz linux-2.6.25.4.tar.bz2]), or alternatively, the same file in .gz instead of .bz2. The bz2 files are compressed slightly better, but uncompressing it requires the bzip2 program, which is not available on every Unix platform - fortunately it is on Debian. # Use WinSCP to upload the kernel source file to your home directory on the server ===Getting the kernel source on your server straight from the 'Net=== # Log in to your server using your user account # use ''ftp ftp.eu.kernel.org'' to connect to the kernel website; use username "anonymous" and password "whatever" (when you use username anonymous, the password doesn't get checked). ## if you type the command "lcd" the program should respond with ''"/home/&lt;yourname&gt;"'', which is your home directory on your server ## if you type the command "pwd" the program should respond with ''"/"'', to indicate you're at the root folder of the kernel.org FTP server ## if you type the command "cd pub/linux/kernel/v2.6" the program should respond with "250 Directory successfully changed.". Type ''pwd'' to check. ## ''dir'' lets you see the contents of the remote directory, and ''dir linux-2.6.2*.bz2'' limits the listing to managable sizes ## ''get linux-2.6.25.4.tar.bz2'' will copy the indicated kernel source file to your home directory; the ''ftp'' client will end the transfer with a message like "226 File send OK." # now you can exit the ftp client with ''exit'' ===Extracting the kernel source=== # Log on to the server using your user account, either onto the console, or on an SSH shell (e.g. using PuTTy on a Windows client) # Move the kernel source file from your home directory to the directory ''/usr/src'', change the owner of the file to root:root, and unpack the file using bzip2 (or gzip if you've downloaded the .tar.gz file): sudo mv linux-2.6.25.4.tar.bz2 /usr/src cd /usr/src sudo tar xjvf linux-2.6.25.4.tar.bz2 sudo rm linux-2.6.25.4.tar.bz2 9c97b21e075a98f416df0445a881baf35dbcf3aa 1480 1478 2008-05-25T09:35:54Z Saruman! 2 /* Extracting the kernel source */ kernel config file introduced wikitext text/x-wiki ==PRO's and Con's== There are both advantages and disadvantages to compiling your own Linux kernel. This is an attempt at siding the pro's and con's, as we see them ===PRO=== * It's fun! (no, really!) * Better performance than a stock Debian kernel, because of system specific optimizations * Better hardware support, because we can use a newer kernel with newer drivers <ref>note that if for instance the Debian stock kernel does not support your network card, then you really must do something with kernel compilation. You'd have the choice of either compiling a whole kernel, or compiling a module for your network card against the stock kernel</ref> * Extra features, because we can use a newer kernel with those newer features ===CON=== * No automatic security system à la [[APT_and_aptitude | APT]]: if there's a security issue in the kernel that you're using, you'll have to find out about it, and then compile a new kernel. As con's go, this is a pretty big one, we reckon. Still, we run our own kernels... * You'll need to delve into hardware specific things, expressed in obscure kernel-hacking terms (what's "sparse memory support" for, anyway?) * Like everything, this takes time to master, and time to implement. Time spent on kernel compiling tasks (be it learning or executing) cannot be spent on other tasks '''Notes''' <references/> ==Prerequisites== To compile your own kernel, you'll need some software. First up, you'll need to install the following packages, using [[APT_and_aptitude | "apt-get install &lt;package&gt;" or ''aptitude'']]. This is the list of packages we advise you to install (if they're not installed already): sudo bzip2 ftp make libncurses5-dev (plus all its dependencies, including the ''gcc'' GNU C Compiler) Now it's time to get that kernel. To get it on a [[Debian_Etch_base_server | base server]], there are many ways; we'll outline two of them. ===Putting a kernel source on your server using WinSCP=== This is pretty easy, although it requires the following things # First up, you'll need to have the [[OpenSSH_server | SSH server]] installed (which we presuppose anyway) # Next, you'll need a computer on your network running Microsoft Windows, on which you need to install [http://winscp.net/eng/download.php WinSCP]. # After installing WinSCP, you start it up, fill in the host name or IP number of your server, your user name (as it exists on the Debian server, and which must have rights to use the SSH server), and click "save" (we advise you never to save your password in WinSCP for security reasons). # After saving the SSH account, you can find it under "stored sessions"; select it and click "login". A login window should appear, and you're asked for your password. After providing that, you're presented with a GUI, that allows you to copy and move files from and to the server. While you can theoretically save to and read from any location on the server, restrictions apply that have to do with the rights of the ordinary user that you are, so for simplicity we assume you'll put files in your home directory (e.g. ''/home/saruman''), and then from a shell on the server move the files to the proper location. # Now, you download the kernel source from the famous [http://kernel.org/ kernel.org]. From a European location, the latest v2.6 kernel source can be found [http://www.eu.kernel.org/pub/linux/kernel/v2.6/ in here]. Download the newest file that is named "linux-2.6.xxxxxx.tar.bz2" (like [http://www.eu.kernel.org/pub/linux/kernel/v2.6/linux-2.6.25.4.tar.gz linux-2.6.25.4.tar.bz2]), or alternatively, the same file in .gz instead of .bz2. The bz2 files are compressed slightly better, but uncompressing it requires the bzip2 program, which is not available on every Unix platform - fortunately it is on Debian. # Use WinSCP to upload the kernel source file to your home directory on the server ===Getting the kernel source on your server straight from the 'Net=== # Log in to your server using your user account # use ''ftp ftp.eu.kernel.org'' to connect to the kernel website; use username "anonymous" and password "whatever" (when you use username anonymous, the password doesn't get checked). ## if you type the command "lcd" the program should respond with ''"/home/&lt;yourname&gt;"'', which is your home directory on your server ## if you type the command "pwd" the program should respond with ''"/"'', to indicate you're at the root folder of the kernel.org FTP server ## if you type the command "cd pub/linux/kernel/v2.6" the program should respond with "250 Directory successfully changed.". Type ''pwd'' to check. ## ''dir'' lets you see the contents of the remote directory, and ''dir linux-2.6.2*.bz2'' limits the listing to managable sizes ## ''get linux-2.6.25.4.tar.bz2'' will copy the indicated kernel source file to your home directory; the ''ftp'' client will end the transfer with a message like "226 File send OK." # now you can exit the ftp client with ''exit'' ===Extracting the kernel source=== # Log on to the server using your user account, either onto the console, or on an SSH shell (e.g. using PuTTy on a Windows client) # Move the kernel source file from your home directory to the directory ''/usr/src'', change the owner of the file to root:root, and unpack the file using bzip2 (or gzip if you've downloaded the .tar.gz file): sudo mv linux-2.6.25.4.tar.bz2 /usr/src cd /usr/src sudo tar xjvf linux-2.6.25.4.tar.bz2 sudo rm linux-2.6.25.4.tar.bz2 cd /usr/src/linux-2.6.25.4 Note that because we extract the kernel source using sudo, all of the extracted files are also owned by root. ===Creating a kernel configuration file=== First up, when you get to compiling the kernel, the compilation process will use this file: ''/usr/src/linux-2.6.25.4/.config''. It contains all directives for the compilation process: what parts to include, what to exclude, which parts of the kernel must be compiled as modules, etcetera. But the extracted kernel source does not contain this ''.config'' file. This means you have to create one yourself. For this, you have the following options: * create .config from scratch * get a .config for your kernel version from elsewhere (another one of your machines, perhaps), put it in ''/usr/src/linux-2.6.25.4/'', and edit it if necessary * get a .config from another (older) kernel version from elsewhere, upgrade it to your current kernel version, and then edit it some more if necessary defab26ea9d9bb46ca6bd84aeeb70783f3a0bbf5 1483 1480 2008-05-25T10:36:20Z Saruman! 2 added SaruWiki kernel config page wikitext text/x-wiki ==PRO's and Con's== There are both advantages and disadvantages to compiling your own Linux kernel. This is an attempt at siding the pro's and con's, as we see them ===PRO=== * It's fun! (no, really!) * Better performance than a stock Debian kernel, because of system specific optimizations * Better hardware support, because we can use a newer kernel with newer drivers <ref>note that if for instance the Debian stock kernel does not support your network card, then you really must do something with kernel compilation. You'd have the choice of either compiling a whole kernel, or compiling a module for your network card against the stock kernel</ref> * Extra features, because we can use a newer kernel with those newer features ===CON=== * No automatic security system à la [[APT_and_aptitude | APT]]: if there's a security issue in the kernel that you're using, you'll have to find out about it, and then compile a new kernel. As con's go, this is a pretty big one, we reckon. Still, we run our own kernels... * You'll need to delve into hardware specific things, expressed in obscure kernel-hacking terms (what's "sparse memory support" for, anyway?) * Like everything, this takes time to master, and time to implement. Time spent on kernel compiling tasks (be it learning or executing) cannot be spent on other tasks '''Notes''' <references/> ==Prerequisites== To compile your own kernel, you'll need some software. First up, you'll need to install the following packages, using [[APT_and_aptitude | "apt-get install &lt;package&gt;" or ''aptitude'']]. This is the list of packages we advise you to install (if they're not installed already): sudo bzip2 ftp make libncurses5-dev (plus all its dependencies, including the ''gcc'' GNU C Compiler) Now it's time to get that kernel. To get it on a [[Debian_Etch_base_server | base server]], there are many ways; we'll outline two of them. ===Putting a kernel source on your server using WinSCP=== This is pretty easy, although it requires the following things # First up, you'll need to have the [[OpenSSH_server | SSH server]] installed (which we presuppose anyway) # Next, you'll need a computer on your network running Microsoft Windows, on which you need to install [http://winscp.net/eng/download.php WinSCP]. # After installing WinSCP, you start it up, fill in the host name or IP number of your server, your user name (as it exists on the Debian server, and which must have rights to use the SSH server), and click "save" (we advise you never to save your password in WinSCP for security reasons). # After saving the SSH account, you can find it under "stored sessions"; select it and click "login". A login window should appear, and you're asked for your password. After providing that, you're presented with a GUI, that allows you to copy and move files from and to the server. While you can theoretically save to and read from any location on the server, restrictions apply that have to do with the rights of the ordinary user that you are, so for simplicity we assume you'll put files in your home directory (e.g. ''/home/saruman''), and then from a shell on the server move the files to the proper location. # Now, you download the kernel source from the famous [http://kernel.org/ kernel.org]. From a European location, the latest v2.6 kernel source can be found [http://www.eu.kernel.org/pub/linux/kernel/v2.6/ in here]. Download the newest file that is named "linux-2.6.xxxxxx.tar.bz2" (like [http://www.eu.kernel.org/pub/linux/kernel/v2.6/linux-2.6.25.4.tar.gz linux-2.6.25.4.tar.bz2]), or alternatively, the same file in .gz instead of .bz2. The bz2 files are compressed slightly better, but uncompressing it requires the bzip2 program, which is not available on every Unix platform - fortunately it is on Debian. # Use WinSCP to upload the kernel source file to your home directory on the server ===Getting the kernel source on your server straight from the 'Net=== # Log in to your server using your user account # use ''ftp ftp.eu.kernel.org'' to connect to the kernel website; use username "anonymous" and password "whatever" (when you use username anonymous, the password doesn't get checked). ## if you type the command "lcd" the program should respond with ''"/home/&lt;yourname&gt;"'', which is your home directory on your server ## if you type the command "pwd" the program should respond with ''"/"'', to indicate you're at the root folder of the kernel.org FTP server ## if you type the command "cd pub/linux/kernel/v2.6" the program should respond with "250 Directory successfully changed.". Type ''pwd'' to check. ## ''dir'' lets you see the contents of the remote directory, and ''dir linux-2.6.2*.bz2'' limits the listing to managable sizes ## ''get linux-2.6.25.4.tar.bz2'' will copy the indicated kernel source file to your home directory; the ''ftp'' client will end the transfer with a message like "226 File send OK." # now you can exit the ftp client with ''exit'' ===Extracting the kernel source=== # Log on to the server using your user account, either onto the console, or on an SSH shell (e.g. using PuTTy on a Windows client) # Move the kernel source file from your home directory to the directory ''/usr/src'', change the owner of the file to root:root, and unpack the file using bzip2 (or gzip if you've downloaded the .tar.gz file): sudo mv linux-2.6.25.4.tar.bz2 /usr/src cd /usr/src sudo tar xjvf linux-2.6.25.4.tar.bz2 sudo rm linux-2.6.25.4.tar.bz2 cd /usr/src/linux-2.6.25.4 Note that because we extract the kernel source using sudo, all of the extracted files are also owned by root. ==Kernel compilation== ===Creating a kernel configuration file=== First up, when you get to compiling the kernel, the compilation process will use this file: ''/usr/src/linux-2.6.25.4/.config''. It contains all directives for the compilation process: what parts to include, what to exclude, which parts of the kernel must be compiled as modules, etcetera. But the extracted kernel source does not contain this ''.config'' file. This means you have to create one yourself. For this, you have the following options: * create your .config [[Kernelconfig_from_scratch | from scratch]]; * get a .config for your kernel version from elsewhere (another one of your machines, perhaps), put it in ''/usr/src/linux-2.6.25.4/'', and [[Kernelconfig_editing | edit it if necessary]] - a good place to start would be the configuration of the Debian stock kernel. This .config file can be found on [http://merkel.debian.org/~jurij/ this Debian site]; another place to start would be from [[Kernel Config Files | this list of SaruWiki .config files]]; * get a .config from another (older) kernel version from elsewhere, [[Kernelconfig_upgrading | upgrade it to your current kernel version]], e.g. from another machine in your server park, and then [[Kernelconfig_editing | edit it some more]] if necessary. However you choose to go about it, you should wind up with a ''.config'' file for precisely the kernel that you've downloaded that fits your hardware and your feature requirements. ===The actual compiling=== ==="Installing" the kernel=== 3aea02b6c238f275a28eb297e09ff26e68323564 0 1428 1484 2008-05-25T10:51:39Z Saruman! 2 First four Saruman kernel configs entered wikitext text/x-wiki ==The Official SaruWiki Kernel Configuration Page== The following kernel configuration files have been used by the SaruWiki team: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Link !style="background:#ffdead;"|Kernel version !style="background:#ffdead;"|Remarks |- |[http://oberon.saruman.biz/kernelconfigs/2.6.18.1.config .config] |2.6.18.1 |for Pentium 4 on i875 chipset, Intel NICs, Intel P-ATA and S-ATA controllers, Iceditch Netfilter options, IPsec tunnel options, MD RAID1 & 5 support |- |[http://oberon.saruman.biz/kernelconfigs/2.6.20.config .config] |2.6.20 |for Pentium 4 on i875 chipset, Intel NICs, Intel P-ATA and S-ATA controllers, Iceditch Netfilter options, IPsec tunnel options, MD RAID1 & 5 support |- |[http://oberon.saruman.biz/kernelconfigs/2.6.22.2.config .config] |2.6.22.2 |for Pentium 4 on i875 chipset, Intel NICs, Intel P-ATA and S-ATA controllers, Iceditch Netfilter options, IPsec tunnel options, MD RAID1 & 5 support |- |[http://oberon.saruman.biz/kernelconfigs/2.6.24.5.config .config] |2.6.24.5 |for Pentium 4 on i875 chipset, Intel NICs, Intel P-ATA and S-ATA controllers, Iceditch Netfilter options, IPsec tunnel options, MD RAID1 & 5 support |- |} a1d6eff6cd35bad53bbf73f4ee4a2d01a98a05b7 0 1429 1485 2008-05-25T11:39:56Z Saruman! 2 page started wikitext text/x-wiki ==Creating a Kernel Config from scratch== If you've followed the "[[roll your own kernel]]" section, you wind up at a point where you have the Linux kernel source for a certain version of Linux, but no configuration file to compile that source into a viable kernel - more specifically, a kernel that is viable for your hardware and your purposes. Suppose you decide to make such a kernel configuration file from scratch, without any example file or other starting point. What do you have to do? First off, there are three main ways in which to create the required kernel configuration file: * the 038986926e4657b661e74159fa24d228c66f1013 1487 1485 2008-05-25T15:34:52Z Saruman! 2 config methods described wikitext text/x-wiki ==Creating a Kernel Config from scratch== If you've followed the "[[roll your own kernel]]" section, you wind up at a point where you have the Linux kernel source for a certain version of Linux, but no configuration file to compile that source into a viable kernel - more specifically, a kernel that is viable for your hardware and your purposes. Suppose you decide to make such a kernel configuration file from scratch, without any example file or other starting point. What do you have to do? First off, there are three main ways in which to create the required kernel configuration file: * when in the source directory (e.g. ''/usr/src/linux-2.6.25.4''), the command ''make config'' will prompt you with all the questions that need to be answered. Let me tell you: you don't want that. The list of questions to be answered is very, very long. I don't know any circumstance where you'd choose this method to configure the kernel over the following two. * [[Image:Menuconfig.PNG|right|thumb|150px|make menuconfig]]when in the source directory (e.g. ''/usr/src/linux-2.6.25.4''), the command ''make menconfig'' will start up a "curses-based" configuration menu. Here, you can enter submenus, and for each configurable item request help. This is the method we prefer for configuring a kernel. * when the server has an x-server available, the command ''make xconfig'' will open an X window, where you can configure the kernel almost exactly like with the previous method. The main difference is that you can click (radio)buttons to enable/disable features. Now, the task is on you to navigate through the whole set of kernel configuration menus, and change all settings from their default value that you need changed. This requires a lot of knowledge about all features that are available, both in hardware support and in features, and also it requires you to know enough to choose all features that you will be needing. 5d4bc139cca8a2c3a46e94e4b338c499465f5003 1493 1487 2008-05-26T19:19:13Z Saruman! 2 added lspci hw scanning wikitext text/x-wiki ==Creating a Kernel Config from scratch== If you've followed the "[[roll your own kernel]]" section, you wind up at a point where you have the Linux kernel source for a certain version of Linux, but no configuration file to compile that source into a viable kernel - more specifically, a kernel that is viable for your hardware and your purposes. Suppose you decide to make such a kernel configuration file from scratch, without any example file or other starting point. What do you have to do? First off, there are three main ways in which to create the required kernel configuration file: * when in the source directory (e.g. ''/usr/src/linux-2.6.25.4''), the command ''make config'' will prompt you with all the questions that need to be answered. Let me tell you: you don't want that. The list of questions to be answered is very, very long. I don't know any circumstance where you'd choose this method to configure the kernel over the following two. * [[Image:Menuconfig.PNG|right|thumb|150px|make menuconfig]]when in the source directory (e.g. ''/usr/src/linux-2.6.25.4''), the command ''make menconfig'' will start up a "curses-based" configuration menu. Here, you can enter submenus, and for each configurable item request help. This is the method we prefer for configuring a kernel. * when the server has an x-server available, the command ''make xconfig'' will open an X window, where you can configure the kernel almost exactly like with the previous method. The main difference is that you can click (radio)buttons to enable/disable features. Now, the task is on you to navigate through the whole set of kernel configuration menus, and change all settings from their default value that you need changed. This requires a lot of knowledge about all features that are available, both in hardware support and in features, and also it requires you to know enough to choose all features that you will be needing. A feature of interest is the following: to find out ''exactly'' which hardware components your system contains, in Linux terms, you can use the utility ''[[Big Bag'o'utilities | lspci]]'' This gives you a description of all the PCI devices in your server, which should include the chipset, videocard, network card, and most important of all, your storage controller. And if you issue the command in the form ''lspci -n'', then you get a numeric result (one line per device) like this: 00:00.0 0600: 8086:3590 (rev 0c) 00:00.1 ff00: 8086:3591 (rev 0c) 00:02.0 0604: 8086:3595 (rev 0c) 00:04.0 0604: 8086:3597 (rev 0c) 00:05.0 0604: 8086:3598 (rev 0c) (etcetera) This result can be pasted into the [http://kmuto.jp/debian/hcl/index.cgi Debian GNU/Linux device driver check page]. This site can translate the data into description of the devices, but more importantly it can tell you for each device which Linux driver works with it. fa9e9063a4dbad74997ba2126ad0e7b418d0497d 6 1430 1486 2008-05-25T15:22:12Z Saruman! 2 Linux kernel curses-based configuration menu wikitext text/x-wiki Linux kernel curses-based configuration menu 47a99bb154045423d67df9a67aa5b67de4dd3836 0 1431 1491 2008-05-26T04:47:47Z Saruman! 2 Collection started wikitext text/x-wiki All utilities listed below are command line utilities; install them using ''apt-get install'' or ''aptitude''. ''bzip2'' is a file compressor/decompressor<br> ''ccze'' can "colorize" output, e.g. ''tail -f /var/log/syslog | ccze''<br> ''ipcalc'' is an IP address/mask calculator<br> ''[[IProute | iproute]]'' helps viewing and setting the [http://lartc.org/ IP configuration]<br> ''iptraf'' is an IP traffic monitor<br> ''less'' is a utility [http://blog.platinumsolutions.com/node/47 to view text files];<br> ''pwgen'' is a password generator ''[[Sudo | sudo]]'' enables you to execute commands with another user's credentials<br> ''[[TCPdump | tcpdump]] is a network sniffer<br> ''unarj'' is a file decompressor for the .arj file format<br> ''unzip'' is a file decompressor for the .zip file format<br> ''unzoo'' is a file decompressor for the .zoo file format<br> 7bdddfa1913436743d4d3cda817c245dfd9a9e53 1509 1491 2008-06-04T19:30:37Z Saruman! 2 added apticron wikitext text/x-wiki All utilities listed below are command line utilities; install them using ''apt-get install'' or ''aptitude''. ''apticron'' checks your system daily, and mails you when there are updates for packages<br> ''bzip2'' is a file compressor/decompressor<br> ''ccze'' can "colorize" output, e.g. ''tail -f /var/log/syslog | ccze''<br> ''ipcalc'' is an IP address/mask calculator<br> ''[[IProute | iproute]]'' helps viewing and setting the [http://lartc.org/ IP configuration]<br> ''iptraf'' is an IP traffic monitor<br> ''less'' is a utility [http://blog.platinumsolutions.com/node/47 to view text files];<br> ''pwgen'' is a password generator ''[[Sudo | sudo]]'' enables you to execute commands with another user's credentials<br> ''[[TCPdump | tcpdump]] is a network sniffer<br> ''unarj'' is a file decompressor for the .arj file format<br> ''unzip'' is a file decompressor for the .zip file format<br> ''unzoo'' is a file decompressor for the .zoo file format<br> cbf996d555a7c775f4aa859603951ce02b4b7881 0 1432 1492 2008-05-26T09:07:58Z Insomnia 3 ssh/scp wikitext text/x-wiki To autenticate yourself to anither machine you can use keys. To generate a key pair use ssh-keygen -t rsa [root@server .ssh]# ssh-keygen -t rsa Generating public/private rsa key pair. Enter file in which to save the key (/root/.ssh/id_rsa): Enter passphrase (empty for no passphrase): Enter same passphrase again: Your identification has been saved in /root/.ssh/id_rsa. Your public key has been saved in /root/.ssh/id_rsa.pub. The key fingerprint is: Now copy the key to the other machine [root@server bin]$ scp /''path''/.ssh/id_rsa.pub remote_user@serverdomain.org:.ssh/authorized_keys The user is now know on the other machine 986d73a51e3d04a6343259c09d284e04f846e2bd 0 1433 1496 2008-05-30T07:01:58Z Saruman! 2 First outline wikitext text/x-wiki ==Asterisk Project page== This describes the project plan for our Asterisk implementation # obtain [http://www.oreilly.com/catalog/9780596510480/ Asterisk book (2nd edition)] => Jan # research modem/ISDN hardware support => Henri # research Digium support/value-for-money => Jan # research difference Debian Etch vs. stable Asterisk source files => Jan # Plan Asterisk configurations for Darktower & Oberon ## hardware inclusion (Digium? ISDN/modem? ## VoIP numbers to order with [http://www.xs4all.nl/allediensten/bellen/faq.php XS4all] <big>GO/NO-GO POINT</big> # Order Digium card => Jan # Install basic Asterisk software caf91782a789b6188963aff5cf24a7767ecc15b3 1497 1496 2008-05-30T07:02:31Z Saruman! 2 Protected "[[Project page]]": sorry, this is our project... [edit=sysop:move=sysop] wikitext text/x-wiki ==Asterisk Project page== This describes the project plan for our Asterisk implementation # obtain [http://www.oreilly.com/catalog/9780596510480/ Asterisk book (2nd edition)] => Jan # research modem/ISDN hardware support => Henri # research Digium support/value-for-money => Jan # research difference Debian Etch vs. stable Asterisk source files => Jan # Plan Asterisk configurations for Darktower & Oberon ## hardware inclusion (Digium? ISDN/modem? ## VoIP numbers to order with [http://www.xs4all.nl/allediensten/bellen/faq.php XS4all] <big>GO/NO-GO POINT</big> # Order Digium card => Jan # Install basic Asterisk software caf91782a789b6188963aff5cf24a7767ecc15b3 1499 1497 2008-05-30T07:25:15Z Saruman! 2 added 3 points wikitext text/x-wiki ==Asterisk Project page== This describes the project plan for our Asterisk implementation # obtain [http://www.oreilly.com/catalog/9780596510480/ Asterisk book (2nd edition)] => Jan # research modem/ISDN hardware support => Henri # research bandwidth requirements => Henri # research QoS necessity/possibility => Jan # research Digium support/value-for-money => Jan # research difference Debian Etch vs. stable Asterisk source files => Jan # Plan Asterisk configurations for Darktower & Oberon ## hardware inclusion (Digium? ISDN/modem? ## VoIP numbers to order with [http://www.xs4all.nl/allediensten/bellen/faq.php XS4all] <big>GO/NO-GO POINT</big> # Order Digium card => Jan # Install basic Asterisk software # Configure firewall ce064944664c865365e7b9a35c7d56313371f718 0 1434 1505 2008-05-30T20:57:35Z Saruman! 2 Page started wikitext text/x-wiki ==Installation of MediaWiki== An extra feature we added was support for iFrames by means of a little PHP script that we googled; the extension is called [[The websiteFrame PHP extension| websiteFrame.php]]. b673f294bb4555ec926e15843fd954f276f30a49 0 1435 1506 2008-05-30T21:04:33Z Saruman! 2 rough description wikitext text/x-wiki The sourcecode for the extension can be found [[websiteFrame.php Source Code | here]]. To add the extension: copy the souce code in a file named ''websiteFrame.php'', and put it in directory ''/etc/mediawiki-extensions/extensions-available''; then execute the following commands: cd /etc/mediawiki-extensions/extensions-enabled ln -s ../extensions-available/websiteFrame.php Now you can use an iFrame by putting in code like this: <pre> &lt;websiteFrame&gt; website=http://www.google.com/talk/service/badge/Show?tk&amp;#61;z01q6a-longcode-8k5lm1&amp;amp;w=200&amp;amp;h=60 border=0 height=60 width=200 name=GoogleChatwithSaruman! allowtransparency=true &lt;/websiteFrame&gt; </pre> Note that the "=" sign is replaced with ''&amp;#61;'' and the &amp; sign by ''&amp;amp;'' because the PHP script doesn't like them literally. 5dd93147723f00285ca7de4e931cee3648f92a9c 0 1436 1507 2008-05-30T21:07:31Z Saruman! 2 Source code listed wikitext text/x-wiki ==PHP Source Code== <pre> <?php # to activate the extension, include it from your LocalSettings.php # with: include("extensions/websiteFrame.php"); $wgExtensionFunctions[] = "wfwebsiteFrame"; function wfwebsiteFrame() { global $wgParser; $wgParser->setHook( "websiteFrame", "websiteFrame" ); } # the callback function for converting the input text to HTML output function websiteFrame($input) { # set default arguments $allParams['height'] = 800; $allParams['width'] = 800; $allParams['scroll'] = "no"; $allParams['border'] = "0"; # actually 'frameborder' $allParams['name'] = "Page1"; $allParams['align'] = "middle"; $allParams['allowtransparency'] = "false"; # get input args $aParams = explode("\n", $input); # ie 'website=http://www.whatever.com' foreach($aParams as $sParam) { $aParam = explode("=", $sParam); # ie $aParam[0] = 'website' and $aParam[1] = 'http://www.whatever.com' if( count( $aParam ) < 2 ) # no arguments passed continue; $sType = $aParam[0]; # ie 'website' $sArg = $aParam[1]; # ie 'http://www.whatever.com' switch ($sType) { case 'website': # clean up $sType = trim($sType); $sArg = trim($sArg); $allParams['website'] = $sArg; # http://www.whatever.com break; case 'height': # clean up $sType = trim($sType); $sArg = trim($sArg); $allParams['height'] = $sArg; # 80 break; case 'width': # clean up $sType = trim($sType); $sArg = trim($sArg); $allParams['width'] = $sArg; # 100 break; case 'scroll': # clean up $sType = trim($sType); $sArg = trim($sArg); $allParams['scroll'] = $sArg; # yes break; case 'border': # clean up $sType = trim($sType); $sArg = trim($sArg); $allParams['border'] = $sArg; # yes break; case 'name': # clean up $sType = trim($sType); $sArg = trim($sArg); $allParams['name'] = $sArg; # my iFrame break; case 'align': # clean up $sType = trim($sType); $sArg = trim($sArg); $allParams['align'] = $sArg; # my iFrame break; case 'allowtransparency': # clean up $sType = trim($sType); $sArg = trim($sArg); $allParams['allowtransparency'] = $sArg; # my iFrame break; } } # build output $output .= "<iframe src=\"".$allParams['website']."\" align=\"".$allParams['align']."\" name=\"".$allParams['name']."\" frameborder=\"".$allParams['border']."\" height=\"".$allParams['height']."\" scrolling=\"".$allParams['scroll']."\" width=\"".$allParams['width']."\" allowtransparency=\"".$allParams['allowtransparency']."\"></iframe>"; # return the output return $output; } ?> </pre> Note that it isn't hard to add support for another attribute; however, security can be an issue, especially when you allow anonymous editors to use this. acbb766f8f3b55952fafbbe938c81b2d3e183329 0 1439 1512 2008-06-08T13:15:18Z Saruman! 2 Started system boot with explaining sysctl invocation wikitext text/x-wiki ==Debian System Boot== When booting a Debian system, the scripts referenced in ''/etc/rcS.d'' always get executed. One of these scripts is referenced by the entry ''/etc/rcS.d/S30procps.sh''; this entry is a symlink to the script ''/etc/init.d/procps.sh'', and it sets up the ''/proc/sys'' virtual filesystem early on in the boot process of your Debian machine. This matters to us, system administrators, because if the script is invoked with "start", it runs the following command (a.o.): sysctl -q -p /etc/procsys.conf (well actually the last parameter is not included in the command, but since it's the default value for the location and name of the parameter file, it's totally equivalent). This matters to us, since there are a lot of things we can - and want to! - do with the ''/proc/sys'' filesystem. For these, see our separate page of [[Procsys recommendations|/proc/sys recommendations]]. Furthermore, remember that you can reinitialize the ''/proc/sys'' filesystem with the command /etc/init.d/procps.sh start (although just running ''sysctl -p'' works the same if you just want to effectuate edits to ''/etc/sysctl.conf'' :-) 016ef0ef7dbb998e395300529a2a8fe2ffb40268 0 1440 1513 2008-06-08T13:47:21Z Saruman! 2 Explained our standard sysctl.conf settings wikitext text/x-wiki ==/proc/sys settings recommendations== As could be seen from [[System boot procedure]] section, your Debian system can automatically have its kernel configured on boot, using the ''sysctl'' utility; all you have to do for that is to edit ../etc/sysctl.conf''. The file will usually be there already, but every line is commented out. Read the manuals (''man sysctl'' and ''man sysctl.conf'') to see how they work; we're not going to explain that here. What we're going to look at, is what settings we would want to make in ''sysctl.conf'', and more importantly, why. For this, we're going to discuss our own ''sysctl.conf'' line by line. ===IPV4 Network settings=== The ''/proc/sys'' virtual filesystem is a powerful way to manipulate the way your kernel handles network packages coming in (and going out) of your machine. For security purposes, we make the following settings - already in ''sysctl.conf'' notation: * net.ipv4.icmp_echo_ignore_broadcasts = 1<br>This setting makes sure our server will ''not'' respond to echo requests to a broadcast address. This is because when the source address of the echo request is forged, your server will be replying with echo replies to an innocent machine, that might well be flooded with echo replies it didn't request (this is a classic network dDOS attack). * net.ipv4.icmp_echo_ignore_all = 0<br>It is possible to make your server more "stealthily" by not having it respond to echo requests. However, since ''ping'' is one of our favourite diagnostic tools, we do not want to disable echo replies on our machines (you might, ofcourse). * net.ipv4.icmp_ignore_bogus_error_responses = 1<br> * net.ipv4.conf.all.accept_redirects = 0<br>An ICMP redirect is an error message sent by a router to the sender of an IP packet. Redirects are used when a router believes a packet is being routed sub-optimally and it would like to inform the sending host that it should forward subsequent packets to that same destination through a different gateway. However, no network should ''need'' ICMP redirect; though ICMP redirects serve to point out issues with sub optimal routing, network re-architecting should be favored over their use. Well designed networks should never lend themselves to the reliance on or desire for ICMP redirects for reasons of performance, consistency, reliability, and security. Therefore, we see no need to enable this setting on our routers/gateway servers. * net.ipv4.conf.all.rp_filter = 1<br>Enabling rp_filter means Reverse Path filtering; it enables the kernel to do Source Address Verification; this prevents spoofing attacks against our internal networks. If a network packet is incoming on an external interface with an internal source- and destination IP address (probably forged by an attacker), then the kernel will ''not'' allow the packet, based on it having invalid source address. This should never harm legitimate network traffic, but will stop certain network attacks. # (external addresses can still be spoofed) * net.ipv4.conf.all.accept_source_route = 0<br>Source Routed packets can ask for a specific route; however they can be misused to route packets around firewalled interfaces. To our knowledge, no sane network configuration requires Source Routing these days, so we (explicitly) disable it. * net.ipv4.tcp_syncookies = 0<br>By default SYNcookies are off, and we don't enable them either, but if you believe you're under a SYN attack, you might want to enable this setting (either for one time only, or permanently). Setting TCP SYN cookies enables SYN flood protection, but causes some problems as well, including masking legitimate overloading. WARNING - only enable SYN cookies if you really understand what it does! * net.ipv4.conf/all/log_martians = 0<br>Setting log_martians "on" means the kernel will log to the kernel log all packets (including their source addresses) that have no known route. If it is set off, those "martians" are dropped silently. We usually don't need logging on Martians, but you might want to enable it for diagnostic purposes. Note that we DON'T use ''sysctl.conf'' to enable forwarding on our multi-homed servers; it is too easy to make a mistake, and have a system with forwarding enabled and the firewall disabled. Therefor, we program our firewall to directly manipulate the forwarding property, and then only after the firewall is fully initilised. ===Other settings=== Nope, that's just it; we ''only'' make changes to the network settings :-) f549a7652fe0c35b9bd31b2676c6cc2f97a29cbb 1514 1513 2008-06-08T13:56:01Z Saruman! 2 wikitext text/x-wiki ==/proc/sys settings recommendations== As could be seen from [[System boot procedure]] section, your Debian system can automatically have its kernel configured on boot, using the ''sysctl'' utility; all you have to do for that is to edit ../etc/sysctl.conf''. The file will usually be there already, but every line is commented out. Read the manuals (''man sysctl'' and ''man sysctl.conf'') to see how they work; we're not going to explain that here. What we're going to look at, is what settings we would want to make in ''sysctl.conf'', and more importantly, why. For this, we're going to discuss our own ''sysctl.conf'' line by line. ===IPV4 Network settings=== The ''/proc/sys'' virtual filesystem is a powerful way to manipulate the way your kernel handles network packages coming in (and going out) of your machine. For security purposes, we make the following settings - already in ''sysctl.conf'' notation: * net.ipv4.icmp_echo_ignore_broadcasts = 1<br>This setting makes sure our server will ''not'' respond to echo requests to a broadcast address. This is because when the source address of the echo request is forged, your server will be replying with echo replies to an innocent machine, that might well be flooded with echo replies it didn't request (this is a classic network dDOS attack). * net.ipv4.icmp_echo_ignore_all = 0<br>It is possible to make your server more "stealthily" by not having it respond to echo requests. However, since ''ping'' is one of our favourite diagnostic tools, we do not want to disable echo replies on our machines (you might, ofcourse). * net.ipv4.icmp_ignore_bogus_error_responses = 1<br>Sometimes you will come across routers that send out invalid responses to broadcast frames. This is a violation of RFC 1122, Requirements for Internet Hosts -- Communication Layers". As a result, these events are logged by the kernel. To avoid filling up your logfile with unnecessary clutter, you can tell the kernel not to issue these warnings. * net.ipv4.conf.all.accept_redirects = 0<br>An ICMP redirect is an error message sent by a router to the sender of an IP packet. Redirects are used when a router believes a packet is being routed sub-optimally and it would like to inform the sending host that it should forward subsequent packets to that same destination through a different gateway. However, no network should ''need'' ICMP redirect; though ICMP redirects serve to point out issues with sub optimal routing, network re-architecting should be favored over their use. Well designed networks should never lend themselves to the reliance on or desire for ICMP redirects for reasons of performance, consistency, reliability, and security. Therefore, we see no need to enable this setting on our routers/gateway servers. * net.ipv4.conf.all.rp_filter = 1<br>Enabling rp_filter means Reverse Path filtering; it enables the kernel to do Source Address Verification; this prevents spoofing attacks against our internal networks. If a network packet is incoming on an external interface with an internal source- and destination IP address (probably forged by an attacker), then the kernel will ''not'' allow the packet, based on it having invalid source address. This should never harm legitimate network traffic, but will stop certain network attacks. (Note: external addresses can still be spoofed) * net.ipv4.conf.all.accept_source_route = 0<br>Source Routed packets can ask for a specific route; however they can be misused to route packets around firewalled interfaces. To our knowledge, no sane network configuration requires Source Routing these days, so we (explicitly) disable it. * net.ipv4.tcp_syncookies = 0<br>By default SYNcookies are off, and we don't enable them either, but if you believe you're under a SYN attack, you might want to enable this setting (either for one time only, or permanently). Setting TCP SYN cookies enables SYN flood protection, but causes some problems as well, including masking legitimate overloading. WARNING - only enable SYN cookies if you really understand what it does! * net.ipv4.conf/all/log_martians = 0<br>Setting log_martians "on" means the kernel will log to the kernel log all packets (including their source addresses) that have no known route. If it is set off, those "martians" are dropped silently. We usually don't need logging on Martians, but you might want to enable it for diagnostic purposes. Note that we DON'T use ''sysctl.conf'' to enable forwarding on our multi-homed servers; it is too easy to make a mistake, and have a system with forwarding enabled and the firewall disabled. Therefor, we program our firewall to directly manipulate the forwarding property, and then only after the firewall is fully initilised. ===Other settings=== Nope, that's just it; we ''only'' make changes to the network settings :-) c8ede9ebdc12a807bfcda5e96bac87fb9cd5ae34 1515 1514 2008-06-08T14:02:41Z Saruman! 2 typo with log_martians key wikitext text/x-wiki ==/proc/sys settings recommendations== As could be seen from [[System boot procedure]] section, your Debian system can automatically have its kernel configured on boot, using the ''sysctl'' utility; all you have to do for that is to edit ../etc/sysctl.conf''. The file will usually be there already, but every line is commented out. Read the manuals (''man sysctl'' and ''man sysctl.conf'') to see how they work; we're not going to explain that here. What we're going to look at, is what settings we would want to make in ''sysctl.conf'', and more importantly, why. For this, we're going to discuss our own ''sysctl.conf'' line by line. ===IPV4 Network settings=== The ''/proc/sys'' virtual filesystem is a powerful way to manipulate the way your kernel handles network packages coming in (and going out) of your machine. For security purposes, we make the following settings - already in ''sysctl.conf'' notation: * net.ipv4.icmp_echo_ignore_broadcasts = 1<br>This setting makes sure our server will ''not'' respond to echo requests to a broadcast address. This is because when the source address of the echo request is forged, your server will be replying with echo replies to an innocent machine, that might well be flooded with echo replies it didn't request (this is a classic network dDOS attack). * net.ipv4.icmp_echo_ignore_all = 0<br>It is possible to make your server more "stealthily" by not having it respond to echo requests. However, since ''ping'' is one of our favourite diagnostic tools, we do not want to disable echo replies on our machines (you might, ofcourse). * net.ipv4.icmp_ignore_bogus_error_responses = 1<br>Sometimes you will come across routers that send out invalid responses to broadcast frames. This is a violation of RFC 1122, Requirements for Internet Hosts -- Communication Layers". As a result, these events are logged by the kernel. To avoid filling up your logfile with unnecessary clutter, you can tell the kernel not to issue these warnings. * net.ipv4.conf.all.accept_redirects = 0<br>An ICMP redirect is an error message sent by a router to the sender of an IP packet. Redirects are used when a router believes a packet is being routed sub-optimally and it would like to inform the sending host that it should forward subsequent packets to that same destination through a different gateway. However, no network should ''need'' ICMP redirect; though ICMP redirects serve to point out issues with sub optimal routing, network re-architecting should be favored over their use. Well designed networks should never lend themselves to the reliance on or desire for ICMP redirects for reasons of performance, consistency, reliability, and security. Therefore, we see no need to enable this setting on our routers/gateway servers. * net.ipv4.conf.all.rp_filter = 1<br>Enabling rp_filter means Reverse Path filtering; it enables the kernel to do Source Address Verification; this prevents spoofing attacks against our internal networks. If a network packet is incoming on an external interface with an internal source- and destination IP address (probably forged by an attacker), then the kernel will ''not'' allow the packet, based on it having invalid source address. This should never harm legitimate network traffic, but will stop certain network attacks. (Note: external addresses can still be spoofed) * net.ipv4.conf.all.accept_source_route = 0<br>Source Routed packets can ask for a specific route; however they can be misused to route packets around firewalled interfaces. To our knowledge, no sane network configuration requires Source Routing these days, so we (explicitly) disable it. * net.ipv4.tcp_syncookies = 0<br>By default SYNcookies are off, and we don't enable them either, but if you believe you're under a SYN attack, you might want to enable this setting (either for one time only, or permanently). Setting TCP SYN cookies enables SYN flood protection, but causes some problems as well, including masking legitimate overloading. WARNING - only enable SYN cookies if you really understand what it does! * net.ipv4.conf.all.log_martians = 0<br>Setting log_martians "on" means the kernel will log to the kernel log all packets (including their source addresses) that have no known route. If it is set off, those "martians" are dropped silently. We usually don't need logging on Martians, but you might want to enable it for diagnostic purposes. Note that we DON'T use ''sysctl.conf'' to enable forwarding on our multi-homed servers; it is too easy to make a mistake, and have a system with forwarding enabled and the firewall disabled. Therefor, we program our firewall to directly manipulate the forwarding property, and then only after the firewall is fully initilised. ===Other settings=== Nope, that's just it; we ''only'' make changes to the network settings :-) d67d0bf4984c8ce28f516edd0c235ab2812ac632 0 1426 1516 1498 2008-06-08T14:46:21Z Saruman! 2 finished procsys project wikitext text/x-wiki ==Project List== The following projects need to be done on the SaruWiki Admin Team home servers ===Priority 1=== # Create a startup script for setting network routes # Create an IPtables parser script (the ''"Iceditch"'' project) # Installation and configuration of ''[http://www.debian-administration.org/articles/585 OpenLDAP]'' to replace ''passwd'' # Reconfiguration of ''SaMBa'' to use ''OpenLDAP'' # Reconfiguration of ''Horde3'' to use ''OpenLDAP'' # Reconfiguration of ''postfix/courier'' Virtual Mailbox setup to use ''OpenLDAP'' ===Priority 2=== # Installation of a certificate authority # Reconfiguration of ''OpenSSH'' to use certificates instead of passwords # Installation of [http://www.asterisk.org/ Asterisk], to use [http://www.xs4all.nl/helpdesk/bellen/ XS4all VoIP] together with [http://www.telec.nl/producten/p55455/digium_pci_4-poort_a_b-kaart_1x_fxo_3x_fxs_(tdm431b).html KPN analog telephone lines]. ===Priority 3=== # Configuration of WebDAV on Apache2 # Configure traffic shaping measures, e.g. [http://werner.orkz.net/howtos/HTB%20bandwidth%20limiting%20in%20Linux%20HOWTO.html HTB] # Configure [http://www.mythtv.org/ MythTV] ===Priority 4=== The following projects are research projects only, so they're listed under Prio 4: # ''[http://iscsitarget.sourceforge.net IET]'' iSCSI Enterprise Target: have a Linux server become an iSCSI target # ''[http://www.howtoforge.com/iscsi_on_linux iSCSI initiator on Linux] ===Finished projects=== # Create a startup script for setting ''/proc/sys'' - was already there, see [[Procsys recommendations]] fc2ed62d710372b81aef947391343f31bcb215fb 1524 1516 2008-06-22T20:47:44Z Saruman! 2 moved routing to "done" projects wikitext text/x-wiki ==Project List== The following projects need to be done on the SaruWiki Admin Team home servers ===Priority 1=== # Create an IPtables parser script (the ''"Iceditch"'' project, see the [[firewall section]]) # Installation and configuration of ''[http://www.debian-administration.org/articles/585 OpenLDAP]'' to replace ''passwd'' # Reconfiguration of ''SaMBa'' to use ''OpenLDAP'' # Reconfiguration of ''Horde3'' to use ''OpenLDAP'' # Reconfiguration of ''postfix/courier'' Virtual Mailbox setup to use ''OpenLDAP'' ===Priority 2=== # Installation of a certificate authority # Reconfiguration of ''OpenSSH'' to use certificates instead of passwords # Installation of [http://www.asterisk.org/ Asterisk], to use [http://www.xs4all.nl/helpdesk/bellen/ XS4all VoIP] together with [http://www.telec.nl/producten/p55455/digium_pci_4-poort_a_b-kaart_1x_fxo_3x_fxs_(tdm431b).html KPN analog telephone lines]. ===Priority 3=== # Configuration of WebDAV on Apache2 # Configure traffic shaping measures, e.g. [http://werner.orkz.net/howtos/HTB%20bandwidth%20limiting%20in%20Linux%20HOWTO.html HTB] # Configure [http://www.mythtv.org/ MythTV] ===Priority 4=== The following projects are research projects only, so they're listed under Prio 4: # ''[http://iscsitarget.sourceforge.net IET]'' iSCSI Enterprise Target: have a Linux server become an iSCSI target # ''[http://www.howtoforge.com/iscsi_on_linux iSCSI initiator on Linux] # (semi)dynamic persistant route addition by scripting something under ''/etc/network/if-up.d'' ===Finished projects=== # Create a startup script for setting ''/proc/sys'' - was already there, see [[Procsys recommendations]] # Create a startup script for setting network routes - using the available networking options, see [[networking section]]. We still could look into more elaborate scripts under ''/etc/network/if-up.d'' but that's a really low priority expansion on persistant routing. db25c2d69f0c437a4726b440b6f161bda2dc3996 0 1433 1517 1499 2008-06-15T10:20:00Z Saruman! 2 added XS4all specific links wikitext text/x-wiki ==Asterisk Project page== This describes the project plan for our Asterisk implementation # obtain [http://www.oreilly.com/catalog/9780596510480/ Asterisk book (2nd edition)] => Jan # research modem/ISDN hardware support => Henri # research bandwidth requirements => Henri # research QoS necessity/possibility => Jan Links: [http://www.voip-wiki.nl/doku.php?id=xs4all] and [http://www.xs4all.nl/helpdesk/bellen/anders.php] # research Digium support/value-for-money => Jan # research difference Debian Etch vs. stable Asterisk source files => Jan # Plan Asterisk configurations for Darktower & Oberon ## hardware inclusion (Digium? ISDN/modem? ## VoIP numbers to order with [http://www.xs4all.nl/allediensten/bellen/faq.php XS4all] <big>GO/NO-GO POINT</big> # Order Digium card => Jan # Install basic Asterisk software # Configure firewall 896fe3476c1269b23593477cb5032fe97081c4f4 1519 1517 2008-06-22T14:41:49Z Saruman! 2 added SIP phone wikitext text/x-wiki ==Asterisk Project page== This describes the project plan for our Asterisk implementation # obtain [http://www.oreilly.com/catalog/9780596510480/ Asterisk book (2nd edition)] => Jan # research modem/ISDN hardware support => Henri # research bandwidth requirements => Henri # research QoS necessity/possibility => Jan Links: [http://www.voip-wiki.nl/doku.php?id=xs4all] and [http://www.xs4all.nl/helpdesk/bellen/anders.php] # research Digium support/value-for-money => Jan # research difference Debian Etch vs. stable Asterisk source files => Jan # research features between Asterisk and SIP phone (SNOM320) # Plan Asterisk configurations for Darktower & Oberon ## hardware inclusion (Digium? ISDN/modem? SIP phone?) ## VoIP numbers to order with [http://www.xs4all.nl/allediensten/bellen/faq.php XS4all] <big>GO/NO-GO POINT</big> # Order Digium card, SIP phones => Jan # Install basic Asterisk software # Configure firewall 039716239699a814577acc6d6c64d26c98525416 1561 1519 2008-07-18T10:11:16Z Insomnia 3 added bandwidth link wikitext text/x-wiki ==Asterisk Project page== This describes the project plan for our Asterisk implementation # obtain [http://www.oreilly.com/catalog/9780596510480/ Asterisk book (2nd edition)] => Jan # research modem/ISDN hardware support => Henri # research [http://www.asteriskguru.com/tools/bandwidth_calculator.php/ bandwidth requirements] => Henri # research QoS necessity/possibility => Jan Links: [http://www.voip-wiki.nl/doku.php?id=xs4all] and [http://www.xs4all.nl/helpdesk/bellen/anders.php] # research Digium support/value-for-money => Jan # research difference Debian Etch vs. stable Asterisk source files => Jan # research features between Asterisk and SIP phone (SNOM320) # Plan Asterisk configurations for Darktower & Oberon ## hardware inclusion (Digium? ISDN/modem? SIP phone?) ## VoIP numbers to order with [http://www.xs4all.nl/allediensten/bellen/faq.php XS4all] <big>GO/NO-GO POINT</big> # Order Digium card, SIP phones => Jan # Install basic Asterisk software # Configure firewall 3d60eb9ace5ccbdb03fe85499dc435f1fd61f2fc 0 1409 1518 1469 2008-06-21T09:06:46Z Saruman! 2 /* Finishing up the installation */ fixed kernel-link wikitext text/x-wiki <big>'''Debian Etch Base Server setup'''</big> ==Getting the hardware== {| class="wikitable" border="1" |- |Note: in the following we're assuming you'll be assembling an x86 or x64 type of machine, as it has about the best price/performance ratio you could wish. Hardware costs for other platforms, e.g. IBM's Series p or HP 9000, can be much higher, while platforms like ARM are just not very powerful. Also, the availability of components and of help can be less than with the ubiquietous x86/x64 platforms. |} Naturally, before we can begin to install the operating system, we need to obtain the necessary hardware. Which hardware you require depends on what you want the server for; a testserver on which you will test only a single feature for a short while does not need the same quality of hardware as does a server that's supposed to act as a homeserver for many tasks for a long time. We'll assume your server will be like ours: a home server that must perform many tasks with sufficient performance for a few users, that's reliable and will last for a couple of years. So build or obtain a server with at least the following hardware: * a spacious casing with big, quiet cooling fans, like the [http://www.coolermaster.com/products/product.php?act=detail&id=317 one we have]; * an efficient, heavy-duty power supply that's rated high enough for your devices, and has a decent efficiency. For example, a [http://www.corsair.com/products/power_supplies.aspx Corsair HX520] power supply; * a server class motherboard, e.g. an [http://www.intel.com/products/server/index.htm?iid=home+hdr_nav2_server Intel] or [http://uk.asus.com/products.aspx?l1=9&l2=39&l3=263 AMD] based single-processor motherboard. DO NOT go for the cheapest motherboard you can find: if you pay peanuts, that's what you get. Server class motherboards have the quality, stability and durability you'll need from it, and usually also most of the needed peripherals, like multiple ethernet network cards on-board. Usually a Linux server doesn not require much in the way of video performance (and the screen will be used rarely, if ever), so any old integrated graphics will do. * a matching CPU - or multiple, if you think you need the power and the selected motherboard has the sockets. * a CD-ROM- or DVD-player * ''multiple'' harddisks - you'll want redundancy, because every harddisk fails at some time. The drive with your data on it will fail fatally when it is most inconvenient to you, and any data on it that you consider valuable will likely be lost forever. To make Murphy's work somewhat harder for him, we're going to store our data redundantly, so that if any drive in the server fails, we'll not lose our data or our server. Thus, get yourself at least two harddisks for your operating system, at least 40GiB in size (don't think you'll be able to buy smaller ones nowadays), and spanking new (NEVER use old harddisks for your production server, new ones are just too cheap to run that risk!). * (multipe) network card(s) (NICs) if your motherboard does not have enough NICs integrated on-board. You'll want a NIC for your network, and another one for your Internet connection; and possible a third one for the wireless segment of your network. Now build a machine out of the above, or have someone build it for you. ==Preparation of the hardware== (Note: in the following we're again assuming you're running an x86/x64 type of machine. Hardware requirements and preparation for other platforms, e.g. IBM's Series p or HP 9000, can differ significantly) Next, check the assembled hardware: * is the configuration complete? If it does not have a CD/DVDplayer from which it can boot, then installing the software gets more difficult - at least get an USB external DVDdrive or something like that. * are all components connected properly (memory DIMMs seated correctly in their sockets, AGP card inserted correctly into the AGP slot, et cetera) and are all cable connections made (multiple power cables to the motherboard, one power cable plus one data cable to each hard disk, etcetera)? Following this, you may hook up the machine. It's going to need power, and you will need at least a keyboard and a monitor attached. And if you want to use a Graphic User Interface to install, a mouse is required also. When you've ensured that everything is safe, you can turn on the machine, and continue to check it: * do all fans start to run when you turn on the machine? (if not, then '''quickly''' turn off your machine and correct the problem!) * does/do the hard disk(s) spin up? * do the power button and reset button operate correctly? * are the power led, HDD led and other display gadgetry functional? * when you let the machine power up, does it emit a single beep? And does it then show a Power-On Self Test screen (POST)? * Does it show the correct amount of memory in the POST screen? The correct number & speed of the CPU(s)? * Does the machine recognise all controller cards (SCSI, S-ATA etc)? And all attached DVD-drives and hard disks? * are all BIOSes/firmwares up to date? * If you have a hardware RAID controller, are your RAID arrays built already? * does the machine attempt to boot from at least the hard disk? ...et cetera. If there is any problem, or you want to update the BIOS or firmwares, it's best to do it before the operating system is installed. This Wiki, however, is not the place (yet) to get the information on how to accomplish these type of tasks. The last steps in the preparation of the hardware, are * to ensure that the machine can boot from CD/DVD, so that you can start installing Debian from it. It is possible to install Debian over the network, but that requires setting up a [http://www.debian-administration.org/articles/478 PXE Boot server] which is (currently) outside the scope of this wiki. * to connect the hardware to the Internet, so that it can get all required updates etcetera; please do ''not'' connect the box ''straight'' to the Internet, but make sure that it's safely behind a firewall, or failing that, a NAT router. By now the system should be almost ready to receive it's Operating System. But first we have an issue to tackle: that of redundancy. ==Software or hardware RAID== Your hard disks will fail. They absolutely will. It is never a question of "if", only of "when". So what will you do when the hard disk containing your complete operating system fails (besides pulling your hair out, that is)? What we propose is this: hard disks are pretty cheap nowadays, so let's use [http://en.wikipedia.org/wiki/Redundant_array_of_independent_disks RAID technology] to make our hard drive space resilient against failure of a whole drive. So first make sure that you have ''two'' disks of equal size instead of only one. Had you already been planning to use multiple disks already, then make sure you have at least ''one'' disk more than your space requirements prescribe; the space on that extra drive will provide the needed redundancy. Next, [[RAID fundamentals under Linux | click here]] to learn a bit more about RAID, to make the decision to use hardware-based and/or software-based RAID, and to plan your RAID arrays. In this example, we'll assume you're using hardware RAID on a RAID controller that's supported by the Debian installation software. This means that the installation software will "see" your RAID array(s) and present them as usable drives. ==Planning your network names== If your machine must become a part of an existing network, then it's almost certain that you already have a DNS domain in place; in that case: obtain the DNS suffix your machine will get (the DNS domain your machine will "belong" to). However, it's also possible that this machine is going to be the first machine in your new network, in which case the whole issue of DNS suffixes is wide open. If you need more information on DNS, go [[http://www.isc.org/sw/bind/arm95/Bv9ARM-all.html#id2564824 here]]. For now we'll assume you have (or will quickly obtain) a working knowledge of the DNS system. Here is our tip on choosing a DNS domain for your home network: * do '''not''' use a publicly registered domain name (e.g. "cocacola.com") for any machine that's not primarily intended to serve the public on the Internet; * for machines serving a private network, we urge you to use Top Level Domain name "lan" (to signify your machine is on a Local Area Network or LAN) * for the Domain Name itself, we suggest you use a level 2 name, like "saruman.lan", and not a level 3 name, like "mister.saruman.lan". This is only a short section on DNS, but remember that once a proper DNS system is in place, it's pretty much work to change it. At any rate, this section has most likely showed you that you need to put some thought into the DNS Domain Name design of your home network. OK, with this out of the way, we can get to installing the OS. ==Operating System installation== To install an Operating System (OS), it's kinda instrumental that you have one. Here, we're going to use [http://www.debian.org/intro/about Debian], the biggest [http://www.debian.org/intro/about#free Free] OS that we know of. Free stands for Freedom, but incidentally that Freedom also means it's gratis, an appealing aspect of Free. To get your own copy of Debian, go to their [http://www.debian.org/distrib/ download site] and obtain the latest [http://www.debian.org/releases/ Stable] image - in this wiki it's Debian 4.0, or "Etch" as it's also known. Besides the choice which release of Debian you want to run, you also have to know for which platform you're downloading (in our case: either ''amd64'' or ''i386'' depending on your hardware platform) and what kind of install you wish - if you have a working, fast Internet connection available at the time of install, then we recommend getting the [[http://www.debian.org/CD/netinst/ netinst] CD image; it's a relatively small CD, that'll be able to get you going, but gets most of the software you'll need straight from the 'net at install time. So, since in the example at hand we're installing on a Xeon server on which we wish to install 32-bits software, we'll download [http://cdimage.debian.org/debian-cd/4.0_r3/i386/iso-cd/debian-40r3-i386-netinst.iso debian-40r3-i386-netinst.iso], the latest netinstall image at the time of writing. Burn this to a CD-recordable and boot your prepared hardware platform from this CD. After booting from the CD, a friendly prompt invites you to indicate how you want to boot the CD. Your choices are listed under &lt;F3&gt;; we're going to use the standard Command Line installation, so we type "install"&lt;enter&gt; or just simply &lt;enter&gt;. {| class="wikitable" border="1" |- |We could easily use "installgui", in which case we'd have a nice fresh Graphical User Interface for our installation. ''We're'' not going to, because we're real men, and [http://isg.ee.ethz.ch/tools/realmen/ Real Men Don't Click]. Also, we've found that from the GUI it's hard to switch to a second console and then back. We could also opt for "expert" as installation method, because it gives a much finer grain of control, but we usually don't need that control, and can do without the barrage of extra questions that the "expert" installation method pose. Finally, we could opt for "expertgui", where we have both the barrage of extra questions ''and'' the GUI, neither of which we need. |} After the Linux kernel finishes initializing the machine, a simple text-based installer appears that immediately starts asking questions. Answer them according to your needs. Our example system uses the following choices: * Language: english * country: other &gt; Netherlands * keymap: American English (since we have a keyboard with US layout) Some installation software loads, and we get to the next phase: if you have multiple NICs in your machine (which we believe you ''should'' have!!), and if they're detected properly, then you're required to indicate which of the detected network interface cards (NIC) is going to be the "primary" NIC. {| class="wikitable" border="1" |- |Here, trouble could begin. If your machine has network cards that are '''not''' supported, then you'll see '''no''' cards here - but then how are you going to do a NetInstall? A solution would be to (temporarily) install a NIC that ''is'' supported, like a cheap Realtek card, or an old 3Com 905 card. Then, when the whole system is installed, up and running, you could compile a new kernel that contains support for your actual NICs, and when these work, remove the temporary NIC. For now, we'll assume that at least one of your NICs is recognised properly by the Debian installation routine. |} Select the card that's connected and has (indirect) access to Internet (again: it should ''not'' be connected straight to the wild wild web, but sit safely behind a firewall, at least until we've installed our own firewall); if at all possible, let it be the NIC that'll be connected to your home network itself, on the ''inside'' of your server. Let's assume that this NIC is designated ''eth0'' by the Debian installation. This card will now be configured using DHCP, so if you're on a network with a DHCP-server, the network will work straight away. If it's not, you can either configure the network manually or fix your DHCP-server and connection between it and ''eth0''. Next is one of the hardest questions that any OS installation is going to ask you: what will be the host name of the system? You could change it at any time in the future, but with lots of hassle, so you better choose wisely. Here are our tips: * do '''not''' name your machine after the user that's going to use it, e.g. "bernie-pc" (at some time in the future, Bernie's machine will be moved to Alice, so then Alice is working on "bernie-pc" which makes the situation quite unclear); * do '''not''' name your machine after the department or workgroup that's using it most, e.g. "accounting-srv" (same reasoning); * do '''not''' name your machine after it's main function, e.g. "printserver" (at some time in the future, the main function is moved to another machine, and/or an alternative function will become the main function of the machine); * do '''not''' name your machine after it's location, e.g. "srv-boston" (at some time in the future, the box will be moved to another location); * do '''not''' name your machine after it's hardware configuration, e.g. "ibmx346" (at some time in the future, either another xSeries x346 will be wheeled in, or the machine will be upgraded to accomodate increased use or overcome hardware problems - your "ibmx346" could suddenly be running on an xSeries x3650). What we feel are safe names for ''any'' machine in your network are true names, perhaps linked to a common theme: names of European cities, names of movie characters, names of countries or holiday destinations et cetera. Immediately following comes the question of the Domain Name. This is about a DNS domain, so effectively the installation program is asking which DNS suffix the host name should have; if the DHCP-server already provided something it'll be suggested, but you can override it if need be. In the preparatory phase, you'll have decided on continuation of your current DNS schema, or starting a new one. Either way, put the chosen DNS suffix in and press &lt;enter&gt;. ==Partitioning== Next comes the question of partitioning, or how to divide the available disk space into chunks for the server to use. This is a tricky subject, because if you put all storage space into one partition, then some day a runaway process will fill up the entire disk with useless logs, and the system will crash. On the other hand, if you divvy up all space into little chunks, then some application is going to need space in one of those partitions where there is none, even though there may be plenty in other partitions. To prevent both problems from occuring, we're going to use [http://tldp.org/HOWTO/LVM-HOWTO/whatisvolman.html Logical Volume Management (LVM)] so that we can provision enough space to start our server, but keep some space in reserve to apply when needed, where it'll be needed. So, we at Saruman.biz have put together a recommended standard partitioning scheme. The basis is this: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Partition !style="background:#ffdead;"|MD !style="background:#ffdead;"|LVG !style="background:#ffdead;"|LV-name !style="background:#ffdead;"|Size <br> (physical machine) !style="background:#ffdead;"|Size (VM) !style="background:#ffdead;"|File System !style="background:#ffdead;"|Mount point |- | 1 | /dev/md0 | &nbsp; | &nbsp; | 100MiB | 100MiB | ext3 | /boot |- | 2 | /dev/md1 | &nbsp; | &nbsp; | 3GiB | 1GiB | ext3 | / |- | rowspan="7" valign="top" | 3 | rowspan="7" valign="top" | /dev/md2 | rowspan="7" valign="top" style="background:lightgrey"| system | style="background:lightgrey" | swap | 1GiB<ref name="swap">Rule of thumb: twice the size of the machine's RAM, but no less than 256MiB and no more than 2GiB</ref> | 256MiB<ref name="swap"/> | swap | &nbsp; |- | style="background:lightgrey" | var | 2GiB | 1GiB | ext3 | /var |- | style="background:lightgrey" | appslog | 3GiB | - | ext3 | /var/appslog |- | style="background:lightgrey" | home | 1GiB<ref name="home">Note that this heavily depends on the purpose of the machine; if it is not to house any users, then (almost) no space is needed for /home. But on the other hand if e.g. a virtual user is to be used for keeping mailstores, or other service users need home space, then /home needs to be big enough for that.</ref> | 512MiB<ref name="home"/> | ext3 | /home |- | style="background:lightgrey" | usr | 3GiB | 3GiB | ext3 | /usr |- | style="background:lightgrey" | tmp | 1GiB | 512MiB | ext3 | /tmp |- | style="background:lightgrey" | opt | 1GiB | - | ext3 | /opt |- ! colspan="4" style="text-align:right"| Total ! 18.1GiB ! 6.9GiB ! colspan="2" | |- |} As you can see, the partition table works as follows: we assume that we wind up with 3 partitions, either on three separate software RAID arrays (''md0'' through ''md2'') or on one single hardware RAID array (in which case the 2nd column ''MD'' does not apply). The size of the partitions depends on your machine's make: for standard physical machines the 5th column does sensible suggestions, even though you could choose to have different sizes and of course different divisions altogether. If your machine happens to be a virtual one, running inside a [http://www.vmware.com/products/server/ VMware Server] or [http://www.vmware.com/products/vi/esx/ VMware ESX host], or the like, then you might want to start out with more modest partitions. The same holds for small servers that must run off Flash drives. Anyways, we're now at the Debian installation screen that lets us partition our disks. We're ''not'' going to use any of the "guided" partitionings, we go for "manual". Choosing that brings us to a screen showing all drives that the installation routine has detected, and all partitions on those drives that the installer can "see". We're going to do some assuming here once more: let's assume the drive(s) on which you want to install are visible, and are empty (containing no other partitions). <references/> ===Software RAID partitioning=== If you're to use software RAID, you now have to select the free space on the first drive, press &lt;enter&gt;, and then tell what you want to do with the free space: create a new partition, tell which size you want it to be (see table above), give the type of partition (primary), and give where on the disk it'll sit (the beginning). Next, a screen comes up that details how the partition you're requesting will be created. Here we make some changes: under "use as" we're going to select "physical volume for RAID". This clears all the other options in this screen, except for the "bootable" flag, which must be "on" for the first partition that we'll mount as ''/boot''. Now select "Done setting up the partition". Next, go to the free space on the second disk, and do ''exactly'' the same, to create an identical physical volume for RAID - if it's the first partition, select the "bootable" flag as well (we'll want to be able to boot from this second disk if the first disk fails, right?). Then go back to the rest of the free space on the first disk, make the second physical volume for RAID, duplicate it on the second disk. Then, go back to the rest of the free space on the first disk, make the third physical volume for RAID, and again duplicate it on the second disk. If you now go back to the "partition disks" overview, you'll see all the partitions you've specified listed on their respective disks. But at the top an extra option has appeared, called "configure software RAID". When you now select this option, the installer will ask if it may write the changes you've made to disk. This actually creates the partition tables on the disks. ===Hardware RAID partitioning=== Now, if you have hardware RAID, then on your first (boot) disk just make 3 partitions, in the following manner: Select the free space on the intended boot disk, press &lt;enter&gt;, select "create a new partition", and fill out the desired size (100MB). Type is primary, location is beginning of the disk, and in the details of the partition, we only need to change the Mount point to "/boot", and set the Bootable flag to "On". Then we're "Done setting up this partition". The second partition is made the same way, but the desired size is 3GB, the Mount point is "/", and the Bootable flag remains off. Again, we're "Done setting up this partition". The third partition is again a primary partition, it takes up the entire rest of the disk, but the type is not ext3, but "physical volume for LVM". Again, we're "Done setting up this partition". But now from the main partitioner screen, we can access "Configure the Logical Volume Manager". The installer asks if it can write out the choices made to the disk, and then enters the LVM setup screen, which begins with a summary explaining that you have one Free Physical Volume, and nothing more. We now create a Volume Group (VG), which (in accordance to our partitioning standard) we'll call "system". In this VG, we'll add all Physical Volumes (being the one partition we've designated so in the previous step) using the space bar. Now we repeat the following process seven times: * select "Create Logical Volume" * select Volume Group "System" * give the LV Name (from the table, e.g. swap, var etc) * give the LV size (from the table, e.g. 1GB for swap etc) After this, we can select "Finish", the partitioner creates the seven LVs, and we're back at the partitioner screen, where there are now 7 extra "disks", with names such as ''LVM VG system, LV appslog - 3.2GB Linux device mapper''. Each of these "disks" has one block of empty space, which we now assign: seven times we repeat the following process: * select the unassigned chunk of empty space of an LV (e.g. appslog) and press &lt;enter&gt;; * Change "Use as: do not use" into the desired filesystem (ext3 - only the LV "swap" gets as filesystem type "swap area") * Change the mount point from "none" to the one corresponding with the name of the LV (note: the swap LV has no mountpoint; the appslog mountpoint must be entered manually as "/var/appslog") * If so desired, a label can be assigned to the partition (we usually don't) * select "Done setting up the partition" Once all this is done, we can look over the configuration once more, and then select "Finish partitioning and write changes to disk". A summary configuration screen will show, and we'll affirm with "yes" that these partitions can indeed be formatted. After some formatting screens flashing by (unless your partitions are particularly big, your system is particularly slow, or something goes wrong) the installation procedure continues. ==Final installer steps== Next comes one '''VERY''' important question: what to use as root password? We cannot stress this enough: choose a SAFE password! Do NOT go for an easy-to-remember one, go for STRONG and SAFE. There are tools to help you generate strong passwords, like [http://www.pctools.com/guides/password/ this page]: use them! We strongly suggest 10 characters or more, including letters, mixed case, and numbers, so something like ''SuCRe4hecH'' (do NOT use this, generate your own!). Next, give the full name of the principal user of this server (your own, we assume), give the login-name (your given name, we assume), and a corresponding password. Again, use a SAFE password. As long as you don't make your principal user equivalent to root, you might go for a slightly weaker password (8 characters instead of 10), but we rather suggest you make the password just as strong (and different from!) the root password. After entering the details of these two users "root" and "you", the Debian installer will ask you how it can contact the Debian archives, in the dialoge "configure the package manager". For the NetInstall version of Debian, this is as good as mandatory. So here, we say "yes, use a Network Mirror", and in the following list select the country in which we are (in our case: the Netherlands), so the installer can present us with a number of network mirrors "close by". We select ftp.nl.debian.org. Next screen: should you be behind a proxy server, then it's possible to specify that here. And then the test: the system will say "scanning the mirror..." and try to contact the specified mirror. If it does not succeed, then there is either a network problem, a problem with this box's network card, or you've not specified the mirror or proxy correctly - so fix it. You'll know the network mirror has succesfully been contacted when the next dialogue appears - currently "configuring popularity-contest". Answer this question as you please. And then one of the last "big" questions: Software Selection. In this dialogue, you can easily select bundles of software to be installed. The choices are currently: * Desktop environment * Web server * Print server * DNS server * File server * Mail server * SQL database * Laptop * Standard system (selected by default) We have to make a little confession here: we've never before used this option in the installer. In fact, we even deselect the Standard System, so as to minimize the number of software packages that the base installation of our server contains. This makes it more work to manually add packages later, but we feel it gives us more control and understanding of our systems. So if you are like us: deselect the Standard System entry, and select Continue. The next dialogue handles the installation of the [http://www.gnu.org/software/grub/ ''grub'' bootloader]. Unless your disks weren't empty and you're attempting to make this system multiboot, you'll most likely get a question if you'll allow the installer to install ''grub'' into the boot sector of the first hard disk. We'll confirm with "Yes". After the installation of grub is completed, the CD-ROM is ejected, and the system is ready to reboot into Debian Etch. Remove the CD and select "Continue" ==Finishing up the installation== The system should reboot into Debian. This means you should see the following boot sequence: * your machine's standard POST messages * then, a blue grub menu on a black screen, with two entries: ** Debian GNU/Linux, kernel 2.6.&lt;something&gt; ** Debian GNU/Linux, kernel 2.6.&lt;something&gt (single-user mode); * then, after a default time-out, the first grub option will go into effect, and the Linux kernel is started. Lots of cryptic messages in grey-on-black will scroll by, until the last few lines read: "Debian GNU/Linux 4.0 &lt;hostname&gt; tty1" and "&lt;hostname&gt; login:" If your system does not reach this login, and/or some horrible error messages appear anywhere in this boot sequence, then you've got some extra work ahead. For now we'll assume you've reached the login prompt without problem. Log in as the principal user (try to avoid logging in as root! That's BAD practice!). Once logged in, save a copy of the boot messages using ''sudo dmesg > boot.txt'' or whatever you like. Then look through the boot messages, e.g. with ''vi -R boot.txt''. Furthermore, [[APT_and_aptitude | use Aptitude]] to make sure ''all'' your software is updated to the latest version. Done! Your base system is ready. You probably now want to [[essential system software | install essential software]], [[roll your own kernel]] and [[connect your server to the Internet]]. 37ad5c211dac2e53119a3dff2be1098a41da6957 0 1 1520 1511 2008-06-22T18:13:17Z Saruman! 2 added networking section wikitext text/x-wiki <big>'''Welcome to SaruWiki.'''</big> This Wiki is intended to document bits and bobs about [http://www.kernel.org/ Linux] (and some Unix) in general, and [http://www.debian.org Debian] in particular. In it, [[SaruTeam|we]] wish to collect the tips and tricks of both [[SaruTeam|our own team of Linux admins]] and those of other interested users. Consult the [http://meta.wikimedia.org/wiki/Help:Contents User's Guide] for information on using this wiki's software. ---- <big>'''Main Content'''</big> * Setting up a [[Debian Etch base server]] is a howto on the installation of a very basic Linux box under Etch (it's actually not even a server yet). * The use of [[APT and aptitude]] is crucial to the concept of a Debian machine. * [[Roll your own kernel]] discusses the pros and cons of compiling your own kernel, and how to do it. * [[Essential system software]] lists all (sets of) packages that we deem, well, essential. * The [[system boot procedure]] section explains what we can customise in the standard ways Debian boots. * The [[networking section]] treats subjects like setting persistent routes. * The [[firewall section]] is where we discuss "IPtables" (netfilter) and how we use it for firewalling. * The [[native IPsec tunnel]] section describes how to configure an IPsec tunnel. * Using ''md'' for [[software RAID]] contains our ideas and observations on redundancy. * [[Hardware monitoring]] is important for your server's health and reliability. * [[Database 101]] introduces you to MySQL. * [[Vmware_server|VMware Server basics]] gives some pointers on how to install VMware Server on a Debian server box. * Make your server a [[Microsoft PPTP server | Microsoft client compatible VPN Server ]]. * How to install [[Mediawiki Installation | Mediawiki]] on your Debian server - like what you're looking at now. ---- '''Note''': the Wiki admins reserve the right to edit or remove any content they feel is not suitable for this site, not relevant, (too) inaccurate or otherwise not in line with the intentions and spirit of the admin team. ---- <websiteFrame> website=http://www.google.com/talk/service/badge/Show?tk&#61;z01q6amlqld8jocej2ca891jl9dunqqra83nhehaoqpednb5skkur0fv70jsuavce4ii9ms5e9afdr8qmpsc1d9upni4jom8g1em3p1cvq1p5eo1ugv162fosgprdv867iuememlcogfle8n3dmcf97durjld85avnh8k5lm1&amp;w=200&amp;h=60 border=0 height=60 width=200 name=GoogleChatwithSaruman! allowtransparency=true </websiteFrame> d656558f6b9b317cd4c23b24b9f227347e2df9b6 0 1441 1521 2008-06-22T19:52:30Z Saruman! 2 First outline of nonperistent and persistent routing wikitext text/x-wiki ==Routes under Debian== When you need to add a networking route, there generally are two ways to do it: # manually adding a route at the command prompt: this means that the machine will "understand" the route for as long as it is running. However, when you reboot the machine, it will have "forgotten" the route. This is called a non-persistent route. # adding a route to the networking configuration files, so that it will be in place regardless of reboots or network restarts. This is called a persistent route. ===Manipulating non-persistent routes=== From the days of yore, the venerable ''route'' command enables us to view, add, change and delete routes. Its most known use is for printing the current routing table: #route -n Kernel IP routing table Destination Gateway Genmask Flags Metric Ref Use Iface 192.168.70.0 212.214.172.50 255.255.255.0 UG 0 0 0 eth1 192.168.67.0 * 255.255.255.0 U 0 0 0 eth0 212.214.172.0 * 255.255.255.0 U 0 0 0 eth1 default 212.214.172.1 0.0.0.0 UG 0 0 0 eth1 The addition of -n makes sure the ''route'' command does not try to substitute DNS names for IP addresses it knows. The second most used incarnation of ''route'' lies in the addition of a route, as has happened in the previous example. The route was added to the routing table using something like this: #route add -net 192.168.70.0 netmask 255.255.255.0 gw 212.214.172.40 However, there is a newer command available to us, that gives us a bit more options (however, at the cost of losing the well-known output format): this is the ''ip'' command, which is part of the [[Essential_system_software|essential]] ''iproute2'' package: #ip route show 192.168.70.0/24 via 212.214.172.50 dev eth1 src 192.168.67.10 192.168.67.0/24 dev eth0 proto kernel scope link src 192.168.67.10 212.214.172.0/24 dev eth1 proto kernel scope link src 212.214.172.50 default via 212.214.172.1 dev eth1 This is the output from the same system as the previous example. However, we see something interesting here: "ip" is capable of adding extra information to the route, like the first line shows (it's using "via"). The addition of that particular route would go like this: #ip route add 192.168.70.0/24 via 212.214.172.50 src 192.168.67.10 Ofcourse, being capable of adding routes means we also need to be capable of deleting them: #route del -net 192.168.70.0 netmask 255.255.255.0 #ip route del 192.168.70.0/24 As you can see, we only need to specify the target of the route to delete, not the options ===Manipulating persistent routes=== 2ed631a4ed52127f507f54ab99f4132fe8c49fc3 1522 1521 2008-06-22T20:18:47Z Saruman! 2 Elaborated persistent route section wikitext text/x-wiki ==Routes under Debian== When you need to add a networking route, there generally are two ways to do it: # manually adding a route at the command prompt: this means that the machine will "understand" the route for as long as it is running. However, when you reboot the machine, it will have "forgotten" the route. This is called a non-persistent route. # adding a route to the networking configuration files, so that it will be in place regardless of reboots or network restarts. This is called a persistent route. ===Manipulating non-persistent routes=== From the days of yore, the venerable ''route'' command enables us to view, add, change and delete routes. Its most known use is for printing the current routing table: #route -n Kernel IP routing table Destination Gateway Genmask Flags Metric Ref Use Iface 192.168.70.0 212.214.172.50 255.255.255.0 UG 0 0 0 eth1 192.168.67.0 * 255.255.255.0 U 0 0 0 eth0 212.214.172.0 * 255.255.255.0 U 0 0 0 eth1 default 212.214.172.1 0.0.0.0 UG 0 0 0 eth1 The addition of -n makes sure the ''route'' command does not try to substitute DNS names for IP addresses it knows. The second most used incarnation of ''route'' lies in the addition of a route, as has happened in the previous example. The route was added to the routing table using something like this: #route add -net 192.168.70.0 netmask 255.255.255.0 gw 212.214.172.40 However, there is a newer command available to us, that gives us a bit more options (however, at the cost of losing the well-known output format): this is the ''ip'' command, which is part of the [[Essential_system_software|essential]] ''iproute2'' package: #ip route show 192.168.70.0/24 via 212.214.172.50 dev eth1 src 192.168.67.10 192.168.67.0/24 dev eth0 proto kernel scope link src 192.168.67.10 212.214.172.0/24 dev eth1 proto kernel scope link src 212.214.172.50 default via 212.214.172.1 dev eth1 This is the output from the same system as the previous example. However, we see something interesting here: "ip" is capable of adding extra information to the route, like the first line shows (it's using "via"). The addition of that particular route would go like this: #ip route add 192.168.70.0/24 via 212.214.172.50 src 192.168.67.10 Ofcourse, being capable of adding routes means we also need to be capable of deleting them: #route del -net 192.168.70.0 netmask 255.255.255.0 #ip route del 192.168.70.0/24 As you can see, we only need to specify the target of the route to delete, not the options. ===Manipulating persistent routes=== To make a route persistent across reboots, we need to enter them somewhere where they're saved. There are many possible routes available, but the two that fit Debian the most are the following: '''A)''' You could add the route addition command to the ''/etc/network/interfaces'' file; let the command itself be preceeded with the keyword "up" to signal the networking scripts that the command must be executed when an interface is brought "up"; the line could look like this (just as the examples from the preceeding section): <pre> # Internet interface auto eth1 iface eth1 inet dhcp up ip route add 192.168.70.0/24 via 212.214.172.50 src 192.168.67.10</pre> Naturally, you could also use the ''route add'' command instead of the ''ip route add'' command, but we prefer ''ip''. Note: it matters --where-- in the ''interfaces'' file you put this line: it should be put in the same stanza as the interface it operates on. In this example, the external interface of the server is 212.214.172.50, which belongs with interface ''eth1''. Therefore, the "up" line appears in the stanza for ''eth1''. '''B)''' You could create a script that sets the route(s), and put it in the directory ''/etc/network/if-up.d''. Since all scripts that reside there get called when any interface goes "up", your route setting script would be called when ''any'' interface comes up, including ''lo''. This in turn means that a script for setting a route that belongs with a particular interface, should check on invocation which is the interface that goes up. At this moment in time, we don't employ any such script, so no example here, but if you look at the existing scripts in ''/etc/network/if-up.d'' you'll see how other programmers have done this. d64fade46ce781b1ef77477633ac34012011dd4f 0 1442 1523 2008-06-22T20:43:31Z Saruman! 2 Iceditch introduction started wikitext text/x-wiki ==Firewalling under Linux== You may not have realised it, but Linux comes with an incredible powerful and flexible [http://searchnetworking.techtarget.com/sDefinition/0,,sid7_gci214173,00.html TCP/IP] [http://www.tech-faq.com/firewall.shtml packet filtering firewall], named [http://www.netfilter.org/ Netfilter]. With a minimum amount of effort, we can create just about any packet filter you can imagine. The Linux solution is so powerful, even commercial firewall vendors like [http://www.watchguard.com/ Watchguard] use it in their products. In fact, Watchguard has paid the main developer early on in the project (see [http://www.netfilter.org/about.html here]). To create a truly magnificent firewall, there are many [[Firewall problems | problems]] to overcome; however, the SaruWiki admin team have created their own "solution" to these problems: the Iceditch firewall script. It handles the many problems firewalls face with the following elements: * Iceditch defines a [[Iceditch IPtables language | "language"]] to more easily read & write IPtables commands; this mainly solves the problems of auditability (partly) and eases maintainability, although it does not by itself solve the problem of documentation. * It offers a standardised way to start the firewall at boot time; * It offers a way to audit the firewall, both while it's running and when you've edited (but not yet implemented) it; * It offers a reasonably failsafe way to change firewall settings from afar. febc6aa14b33f37899b8bc7dea3b44549fd44f8f 1554 1523 2008-07-14T19:25:28Z Saruman! 2 Jump page rewrite wikitext text/x-wiki ==Firewalling under Linux== You may not have realised it, but Linux comes with an incredible powerful and flexible [http://searchnetworking.techtarget.com/sDefinition/0,,sid7_gci214173,00.html TCP/IP] [http://www.tech-faq.com/firewall.shtml packet filtering firewall], named [http://www.netfilter.org/ Netfilter]. With a minimum amount of effort, we can create just about any packet filter you can imagine. The Linux solution is so powerful, even commercial firewall vendors like [http://www.watchguard.com/ Watchguard] use it in their products. In fact, Watchguard has paid the main developer early on in the project (see [http://www.netfilter.org/about.html here]). However, to create a truly magnificent firewall, there are many problems to overcome; we'll discuss them in this section:<br> '''[[Firewall problems | Generic discussion on firewall problems]]'''. Fortunately for YOU, my friend, the SaruWiki admin team have created their own "solution" to these problems: the Iceditch firewall script. By consistent focus on a small set of '''[[Iceditch design targets | sensible design targets]]''', we feel we've succeeded in creating a firewall script that alleviates most of the many problems firewalls face. Our Iceditch solution has the following elements and properties: * Iceditch defines a '''[[Iceditch IPtables language | "language"]]''' to more easily read & write IPtables commands; this mainly solves the problems of auditability (partly) and eases maintainability, although it does not by itself solve the problem of documentation. * It offers '''[[Iceditch functionality | much functionality]]''', like ** a standardised way to start the firewall at boot time, ** ways to audit the firewall, both while it's running and when you've edited (but not yet implemented) it, ** a reasonably failsafe way to change firewall settings from afar. * Iceditch is based on a single Bash script and some configuration files, and thus has a fairly simple '''[[Iceditch file structure | file structure]]'''. * For full reference, we've created this '''[[Iceditch Command Reference]]'''. Now, obviously there are many more firewalls to choose from, ranging from advanced [http://www.shorewall.net/ | configure-it-yourself firewall] to [http://www.smoothwall.org/ pret-a-porter OS-and-firewall-into-one] solutions (and we're not even starting on proprietary solutions, be they hardware and/or software). The main reason for us to create our own firewall script (besides the obvious reasons of fun and learning) is [[Iceditch design targets | flexibility]]. Should you be in any way interested in this project of ours, feel free to [mailto:iceditch@saruman.biz contact us]. 7867e6776292912f502394a24277740f04365bfb 0 1443 1525 2008-06-27T19:25:56Z Saruman! 2 Started explaining Context wikitext text/x-wiki ==The Iceditch control language== If you know and understand [http://iptables-tutorial.frozentux.net/iptables-tutorial.html IPtables commands], then the syntax of the Iceditch control language seems very simple to you. When you realise that it's only goal is to simplify standard IPtables commands __without__ taking away their incredible power or flexibility, you'll also realise that this is actually inevitable. But let's not linger here: dip in! === The ''Context'' header=== Just about every IPtables command that ''creates'' a firewall rule, acts on some firewall table, and some firewall chain. These are found in the IPtables invocation, and are specified by options -A (add to chain) and -t (use table). Thus, the rule iptables -A INPUT -t filter -d 10.0.0.1 -j DROP works in chain ''INPUT'' and table ''filter''. 2cb469bd57f4dd4ac8256125b612120792d5125a 1527 1525 2008-06-27T20:41:14Z Saruman! 2 added target spec wikitext text/x-wiki ==The Iceditch control language== If you know and understand [http://iptables-tutorial.frozentux.net/iptables-tutorial.html IPtables commands], then the syntax of the Iceditch control language seems very simple to you. When you realise that it's only goal is to simplify standard IPtables commands ''without'' taking away their incredible power or flexibility, you'll also realise that this is actually inevitable. But let's not linger here: dip in! === The ''Context'' header=== Just about every IPtables command that ''creates'' a firewall rule, acts on some firewall table, and some firewall chain. These are found in the IPtables invocation, and are specified by options -A (add to chain) and -t (use table). Thus, the rule iptables -A INPUT -t filter -d 10.0.0.1 -j DROP works in chain ''INPUT'' and table ''filter''. There is a number of default chains: * PREROUTING * FORWARD * INPUT * OUTPUT * POSTROUTING Iceditch will (currently) not understand any other chain. There is also a number of default tables: * mangle * nat * filter There is also a "conntrack" table, but it's not user manipulable, so Iceditch won't recognise it Now please have a peek at the following [[nfk-traversal-picture | magnificent picture]]. You can see that tehre are only 11 combinations of default chains and tables that can accept IPtables rules. Fear not: Iceditch will check every rule for valid combination of table and chain, and yield an error message for any invalid combination. The way to tell Iceditch which table and chain to use, is by grouping all commands for a certain combination of table and chain in one stanza of the configuration file: this is called the ''context'' of the rules. A context is specified in the configuration file with the following header context <chain> <table> Every line that follows is assumed to belong to this particular context, so that in these lines the target chain and table do not need to appear. Currently, every context is allowed only once in the configuration file ===The target specification== (Almost) every IPtables rule has a target. Iceditch takes keywords that signify the standard targets, and lets every line begin with this keyword. Thus, the keyword ''accept'' at the beginning of a line signifies that you're talking about an IPtables command that normally would end with ''-j ACCEPT''. The keywords Iceditch currently "understands" are: * accept * drop * reject * redirect * mark * classify * recent * dnat * snat * masquerade * nojump The last one is a bit odd: it signifies an IPtables line that can match a packet, yet won't jump anywhere. This would be the case for a line that you'd insert in order to count certain packets, like iptables -A INPUT -t filter -p icmp -s 10.0.0.1 This line would match any ICMP-packet sent to your machine from IP address 10.0.0.1, but your firewall would not "do" anything with the packet. Thus it would be up to the following lines (or eventually the policy of the table) to actually "do" something with the packet. With the use of CONTEXT, the example line would look like this: context "INPUT" "filter" nojump -p icmp -s 10.0.0.1 1a5de7c907125c3225771e628d0c036f20fe645a 1528 1527 2008-06-27T20:42:01Z Saruman! 2 /* =The target specification */ rectified example box wikitext text/x-wiki ==The Iceditch control language== If you know and understand [http://iptables-tutorial.frozentux.net/iptables-tutorial.html IPtables commands], then the syntax of the Iceditch control language seems very simple to you. When you realise that it's only goal is to simplify standard IPtables commands ''without'' taking away their incredible power or flexibility, you'll also realise that this is actually inevitable. But let's not linger here: dip in! === The ''Context'' header=== Just about every IPtables command that ''creates'' a firewall rule, acts on some firewall table, and some firewall chain. These are found in the IPtables invocation, and are specified by options -A (add to chain) and -t (use table). Thus, the rule iptables -A INPUT -t filter -d 10.0.0.1 -j DROP works in chain ''INPUT'' and table ''filter''. There is a number of default chains: * PREROUTING * FORWARD * INPUT * OUTPUT * POSTROUTING Iceditch will (currently) not understand any other chain. There is also a number of default tables: * mangle * nat * filter There is also a "conntrack" table, but it's not user manipulable, so Iceditch won't recognise it Now please have a peek at the following [[nfk-traversal-picture | magnificent picture]]. You can see that tehre are only 11 combinations of default chains and tables that can accept IPtables rules. Fear not: Iceditch will check every rule for valid combination of table and chain, and yield an error message for any invalid combination. The way to tell Iceditch which table and chain to use, is by grouping all commands for a certain combination of table and chain in one stanza of the configuration file: this is called the ''context'' of the rules. A context is specified in the configuration file with the following header context <chain> <table> Every line that follows is assumed to belong to this particular context, so that in these lines the target chain and table do not need to appear. Currently, every context is allowed only once in the configuration file ===The target specification== (Almost) every IPtables rule has a target. Iceditch takes keywords that signify the standard targets, and lets every line begin with this keyword. Thus, the keyword ''accept'' at the beginning of a line signifies that you're talking about an IPtables command that normally would end with ''-j ACCEPT''. The keywords Iceditch currently "understands" are: * accept * drop * reject * redirect * mark * classify * recent * dnat * snat * masquerade * nojump The last one is a bit odd: it signifies an IPtables line that can match a packet, yet won't jump anywhere. This would be the case for a line that you'd insert in order to count certain packets, like iptables -A INPUT -t filter -p icmp -s 10.0.0.1 This line would match any ICMP-packet sent to your machine from IP address 10.0.0.1, but your firewall would not "do" anything with the packet. Thus it would be up to the following lines (or eventually the policy of the table) to actually "do" something with the packet. With the use of CONTEXT, the example line would look like this: <pre> context "INPUT" "filter" nojump -p icmp -s 10.0.0.1 </pre> 4b28adc5f353cba0e653c84aee35143029e0c535 1529 1528 2008-06-27T20:46:48Z Saruman! 2 cleaning up wikitext text/x-wiki ==The Iceditch control language== If you know and understand [http://iptables-tutorial.frozentux.net/iptables-tutorial.html IPtables commands], then the syntax of the Iceditch control language seems very simple to you. When you realise that it's only goal is to simplify standard IPtables commands ''without'' taking away their incredible power or flexibility, you'll also realise that this is actually inevitable. But let's not linger here: dip in! === The ''Context'' header=== Just about every IPtables command that ''creates'' a firewall rule, acts on some firewall table, and some firewall chain. These are found in the IPtables invocation, and are specified by options -A (add to chain) and -t (use table). Thus, the rule iptables -A INPUT -t filter -d 10.0.0.1 -j DROP works in chain ''INPUT'' and table ''filter''. There is a number of default chains: * PREROUTING * FORWARD * INPUT * OUTPUT * POSTROUTING Iceditch will (currently) not understand any other chain. There is also a number of default tables: * mangle * nat * filter There is also a "conntrack" table, but it's not user manipulable, so Iceditch won't recognise it Now please have a peek at the following [[nfk-traversal-picture | magnificent picture]]. You can see that tehre are only 11 combinations of default chains and tables that can accept IPtables rules. Fear not: '''Iceditch will check every rule for valid combination of table and chain''', and yield an error message for any invalid combination. The way to tell Iceditch which table and chain to use, is by grouping all commands for a certain combination of table and chain in one stanza of the configuration file: this is called the ''context'' of the rules. A context is specified in the configuration file with the following header context <chain> <table> Every line that follows is assumed to belong to this particular context, so that in these lines the target chain and table do not need to appear. Currently, every context is allowed to appear only once in the configuration file. This might seem restrictive (and it actually is), but it forces you to group all actions that take place in a table, so that you actually make sure all actions appear in the right order. Nevertheless, future versions of Iceditch might allow multiple stanzas per unique context. ===The target specification=== (Almost) every IPtables rule has a target. Iceditch takes keywords that signify the standard targets, and lets every line begin with this keyword. Thus, the keyword ''accept'' at the beginning of a line signifies that you're talking about an IPtables command that normally would end with ''-j ACCEPT''. The keywords Iceditch currently "understands" are: * accept * drop * reject * redirect * mark * classify * recent * dnat * snat * masquerade * nojump The last one is a bit odd: it signifies an IPtables line that can match a packet, yet won't jump anywhere; thus, Iceditch actually doesn't "do" anything with the packet. This would be the case for a line that you'd insert in order to count certain packets, like iptables -A INPUT -t filter -p icmp -s 10.0.0.1 This line would match any ICMP-packet sent to your machine from IP address 10.0.0.1, but your firewall would not "do" anything with the packet. Thus it would be up to the following lines (or eventually the policy of the table) to actually "do" something with the packet. With the use of CONTEXT, the example line would look like this: <pre>context "INPUT" "filter" nojump -p icmp -s 10.0.0.1</pre> 6873a6d43b2c56fde0ea4ffb336e3fd1616d5161 1531 1529 2008-06-28T21:39:25Z Saruman! 2 put in the chain/table overview table wikitext text/x-wiki ==The Iceditch control language== If you know and understand [http://iptables-tutorial.frozentux.net/iptables-tutorial.html IPtables commands], then the syntax of the Iceditch control language seems very simple to you. When you realise that it's only goal is to simplify standard IPtables commands ''without'' taking away their incredible power or flexibility, you'll also realise that this is actually inevitable. But let's not linger here: dip in! === The ''Context'' header=== Just about every IPtables command that ''creates'' a firewall rule, acts on some firewall table, and some firewall chain. These are found in the IPtables invocation, and are specified by options -A (add to chain) and -t (use table). Thus, the rule iptables -A INPUT -t filter -d 10.0.0.1 -j DROP works in chain ''INPUT'' and table ''filter''. There is a number of default chains: * PREROUTING * FORWARD * INPUT * OUTPUT * POSTROUTING Iceditch will (currently) not understand any other chain. There is also a number of default tables: * mangle * nat * filter There is also a "conntrack" table, but it's not user manipulable, so Iceditch won't recognise it Now please have a peek at the following [[nfk-traversal-picture | magnificent picture]]. You can see that tehre are only 11 combinations of default chains and tables that can accept IPtables rules. Fear not: '''Iceditch will check every rule for valid combination of table and chain''', and yield an error message for any invalid combination. The valid combinations thus are: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" | !style="background:#ffdead;"|conntrack !style="background:#ffdead;"|mangle !style="background:#ffdead;"|nat !style="background:#ffdead;"|filter |- | style="background:lightgrey" | PREROUTING | X | V | V | X |- | style="background:lightgrey" | FORWARD | X | V | X | V |- | style="background:lightgrey" | INPUT | X | V | V | X |- | style="background:lightgrey" | OUTPUT | X | V | V | V |- | style="background:lightgrey" | POSTROUTING | X | V | V | X |- |} The way to tell Iceditch which table and chain to use, is by grouping all commands for a certain combination of table and chain in one stanza of the configuration file: this is called the ''context'' of the rules. A context is specified in the configuration file with the following header: <pre> context &lt;chain&gt; &lt;table&gt; </pre> Every line that follows is assumed to belong to this particular context, so that in these lines the target chain and table do not need to appear. Currently, every context is allowed to appear only once in the configuration file. This might seem restrictive (and it actually is), but it forces you to group all actions that take place in a table, so that you actually make sure all actions appear in the right order. Nevertheless, future versions of Iceditch might allow multiple stanzas per unique context. ===The target specification=== (Almost) every IPtables rule has a target. Iceditch takes keywords that signify the standard targets, and lets every line begin with this keyword. Thus, the keyword ''accept'' at the beginning of a line signifies that you're talking about an IPtables command that normally would end with ''-j ACCEPT''. The keywords Iceditch currently "understands" are: * accept * drop * reject * redirect * mark * classify * recent * dnat * snat * masquerade * nojump The last one is a bit odd: it signifies an IPtables line that can match a packet, yet won't jump anywhere; thus, Iceditch actually doesn't "do" anything with the packet. This would be the case for a line that you'd insert in order to count certain packets, like iptables -A INPUT -t filter -p icmp -s 10.0.0.1 This line would match any ICMP-packet sent to your machine from IP address 10.0.0.1, but your firewall would not "do" anything with the packet. Thus it would be up to the following lines (or eventually the policy of the table) to actually "do" something with the packet. With the use of CONTEXT, the example line would look like this: <pre>context "INPUT" "filter" nojump -p icmp -s 10.0.0.1</pre> d31b0b6baeb57c32fea4509f2762ed851417b988 1532 1531 2008-06-29T10:25:31Z Saruman! 2 added rule syntax section wikitext text/x-wiki ==The Iceditch control language== If you know and understand [http://iptables-tutorial.frozentux.net/iptables-tutorial.html IPtables commands], then the syntax of the Iceditch control language seems very simple to you. When you realise that it's only goal is to simplify standard IPtables commands ''without'' taking away their incredible power or flexibility, you'll also realise that this is actually inevitable. But let's not linger here: dip in! === The ''Context'' header=== Just about every IPtables command that ''creates'' a firewall rule, acts on some firewall table, and some firewall chain. These are found in the IPtables invocation, and are specified by options -A (add to chain) and -t (use table). Thus, the rule iptables -A INPUT -t filter -d 10.0.0.1 -j DROP works in chain ''INPUT'' and table ''filter''. There is a number of default chains: * PREROUTING * FORWARD * INPUT * OUTPUT * POSTROUTING Iceditch will (currently) not understand any other chain. There is also a number of default tables: * conntrack * mangle * nat * filter The "conntrack" table is not user manipulable, so Iceditch won't (cannot) allow you to it. Now please have a peek at the following [[nfk-traversal-picture | magnificent picture]]. You can see that there are only 11 combinations of default chains and tables that can accept IPtables rules. Fear not: '''Iceditch will check every rule for valid combination of table and chain''', and yield an error message for any invalid combination. The valid combinations thus are: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" | !style="background:#ffdead;"|conntrack !style="background:#ffdead;"|mangle !style="background:#ffdead;"|nat !style="background:#ffdead;"|filter |- | style="background:lightgrey" | '''PREROUTING''' | X | V | V | |- | style="background:lightgrey" | '''FORWARD''' | | V | | V |- | style="background:lightgrey" | '''INPUT''' | | V | | V |- | style="background:lightgrey" | '''OUTPUT''' | X | V | V | V |- | style="background:lightgrey" | '''POSTROUTING''' | | V | V | |- |} The way to tell Iceditch which table and chain to use, is by grouping all commands for a certain combination of table and chain in one stanza of the configuration file: this is called the ''context'' of the rules. A context is specified in the configuration file with the following header: <pre> context &lt;chain&gt; &lt;table&gt; </pre> Every line that follows is assumed to belong to this particular context, so that in these lines the target chain and table do not need to appear. Currently, every context is allowed to appear multiple times in the configuration file. This means Iceditch allows multiple stanzas per unique context. However, they will be processed in the order in which they appear in the configuration file, so one must be careful that the stanzas are ordered correctly; we'd advise to use each context only once, for maintainability over legibility. ===The target specification=== (Almost) every IPtables rule has a target. Iceditch takes keywords that signify the standard targets, and lets every line begin with this keyword. Thus, the keyword ''accept'' at the beginning of a line signifies that you're talking about an IPtables command that normally would end with ''-j ACCEPT''. The keywords Iceditch currently "understands" are: * accept * drop * reject * redirect * mark * classify * recent * dnat * snat * masquerade * nojump The last one is a bit odd: it signifies an IPtables line that can match a packet, yet won't jump anywhere; thus, Iceditch actually doesn't "do" anything with the packet. This would be the case for a line that you'd insert in order to count certain packets, like iptables -A INPUT -t filter -p icmp -s 10.0.0.1 This line would match any ICMP-packet sent to your machine from IP address 10.0.0.1, but your firewall would not "do" anything with the packet. Thus it would be up to the following lines (or eventually the policy of the table) to actually "do" something with the packet. With the use of CONTEXT, the example line would look like this: <pre>context "INPUT" "filter" nojump -p icmp -s 10.0.0.1</pre> ===The rule syntax=== For every IPtables rule you want to specify in Iceditch, the syntax is based on the underlying IPtables rule. However, Iceditch rules are structured differently: the context is specified at the beginning of the stanza, the target forms the opening keyword, and there are several optional addition to the target. Therefor, forming a firewall rule in Iceditch requires you to follow both Iceditch syntax rules and IPtables syntax rules. Don't worry, it's actually quite simple. What we've done is create a page called the [Iceditch Command Reference], where for every target all options are described. However, this reference presupposes intimate knowledge of IPtables. Currently this wiki does not offer a comprehensive course in IPtables; to obtain this knowledge one might start off at sites like [http://iptables-tutorial.frozentux.net/chunkyhtml/index.html this] and [http://security.maruhn.com/ this one]. ad2747d46e089d65a8f627f25dad3988aa3d2466 1533 1532 2008-06-29T10:25:58Z Saruman! 2 /* The rule syntax */ fixed link error wikitext text/x-wiki ==The Iceditch control language== If you know and understand [http://iptables-tutorial.frozentux.net/iptables-tutorial.html IPtables commands], then the syntax of the Iceditch control language seems very simple to you. When you realise that it's only goal is to simplify standard IPtables commands ''without'' taking away their incredible power or flexibility, you'll also realise that this is actually inevitable. But let's not linger here: dip in! === The ''Context'' header=== Just about every IPtables command that ''creates'' a firewall rule, acts on some firewall table, and some firewall chain. These are found in the IPtables invocation, and are specified by options -A (add to chain) and -t (use table). Thus, the rule iptables -A INPUT -t filter -d 10.0.0.1 -j DROP works in chain ''INPUT'' and table ''filter''. There is a number of default chains: * PREROUTING * FORWARD * INPUT * OUTPUT * POSTROUTING Iceditch will (currently) not understand any other chain. There is also a number of default tables: * conntrack * mangle * nat * filter The "conntrack" table is not user manipulable, so Iceditch won't (cannot) allow you to it. Now please have a peek at the following [[nfk-traversal-picture | magnificent picture]]. You can see that there are only 11 combinations of default chains and tables that can accept IPtables rules. Fear not: '''Iceditch will check every rule for valid combination of table and chain''', and yield an error message for any invalid combination. The valid combinations thus are: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" | !style="background:#ffdead;"|conntrack !style="background:#ffdead;"|mangle !style="background:#ffdead;"|nat !style="background:#ffdead;"|filter |- | style="background:lightgrey" | '''PREROUTING''' | X | V | V | |- | style="background:lightgrey" | '''FORWARD''' | | V | | V |- | style="background:lightgrey" | '''INPUT''' | | V | | V |- | style="background:lightgrey" | '''OUTPUT''' | X | V | V | V |- | style="background:lightgrey" | '''POSTROUTING''' | | V | V | |- |} The way to tell Iceditch which table and chain to use, is by grouping all commands for a certain combination of table and chain in one stanza of the configuration file: this is called the ''context'' of the rules. A context is specified in the configuration file with the following header: <pre> context &lt;chain&gt; &lt;table&gt; </pre> Every line that follows is assumed to belong to this particular context, so that in these lines the target chain and table do not need to appear. Currently, every context is allowed to appear multiple times in the configuration file. This means Iceditch allows multiple stanzas per unique context. However, they will be processed in the order in which they appear in the configuration file, so one must be careful that the stanzas are ordered correctly; we'd advise to use each context only once, for maintainability over legibility. ===The target specification=== (Almost) every IPtables rule has a target. Iceditch takes keywords that signify the standard targets, and lets every line begin with this keyword. Thus, the keyword ''accept'' at the beginning of a line signifies that you're talking about an IPtables command that normally would end with ''-j ACCEPT''. The keywords Iceditch currently "understands" are: * accept * drop * reject * redirect * mark * classify * recent * dnat * snat * masquerade * nojump The last one is a bit odd: it signifies an IPtables line that can match a packet, yet won't jump anywhere; thus, Iceditch actually doesn't "do" anything with the packet. This would be the case for a line that you'd insert in order to count certain packets, like iptables -A INPUT -t filter -p icmp -s 10.0.0.1 This line would match any ICMP-packet sent to your machine from IP address 10.0.0.1, but your firewall would not "do" anything with the packet. Thus it would be up to the following lines (or eventually the policy of the table) to actually "do" something with the packet. With the use of CONTEXT, the example line would look like this: <pre>context "INPUT" "filter" nojump -p icmp -s 10.0.0.1</pre> ===The rule syntax=== For every IPtables rule you want to specify in Iceditch, the syntax is based on the underlying IPtables rule. However, Iceditch rules are structured differently: the context is specified at the beginning of the stanza, the target forms the opening keyword, and there are several optional addition to the target. Therefor, forming a firewall rule in Iceditch requires you to follow both Iceditch syntax rules and IPtables syntax rules. Don't worry, it's actually quite simple. What we've done is create a page called the [[Iceditch Command Reference]], where for every target all options are described. However, this reference presupposes intimate knowledge of IPtables. Currently this wiki does not offer a comprehensive course in IPtables; to obtain this knowledge one might start off at sites like [http://iptables-tutorial.frozentux.net/chunkyhtml/index.html this] and [http://security.maruhn.com/ this one]. 0061752b3a5ae6bf479d1dc1d0fec54ef889fec7 1539 1533 2008-06-30T19:33:59Z Saruman! 2 added functionality and structure sections/links wikitext text/x-wiki ==The Iceditch control language== If you know and understand [http://iptables-tutorial.frozentux.net/iptables-tutorial.html IPtables commands], then the syntax of the Iceditch control language seems very simple to you. When you realise that it's only goal is to simplify standard IPtables commands ''without'' taking away their incredible power or flexibility, you'll also realise that this is actually inevitable. But let's not linger here: dip in! === The ''Context'' header=== Just about every IPtables command that ''creates'' a firewall rule, acts on some firewall table, and some firewall chain. These are found in the IPtables invocation, and are specified by options -A (add to chain) and -t (use table). Thus, the rule iptables -A INPUT -t filter -d 10.0.0.1 -j DROP works in chain ''INPUT'' and table ''filter''. There is a number of default chains: * PREROUTING * FORWARD * INPUT * OUTPUT * POSTROUTING Iceditch will (currently) not understand any other chain. There is also a number of default tables: * conntrack * mangle * nat * filter The "conntrack" table is not user manipulable, so Iceditch won't (cannot) allow you to it. Now please have a peek at the following [[nfk-traversal-picture | magnificent picture]]. You can see that there are only 11 combinations of default chains and tables that can accept IPtables rules. Fear not: '''Iceditch will check every rule for valid combination of table and chain''', and yield an error message for any invalid combination. The valid combinations thus are: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" | !style="background:#ffdead;"|conntrack !style="background:#ffdead;"|mangle !style="background:#ffdead;"|nat !style="background:#ffdead;"|filter |- | style="background:lightgrey" | '''PREROUTING''' | X | V | V | |- | style="background:lightgrey" | '''FORWARD''' | | V | | V |- | style="background:lightgrey" | '''INPUT''' | | V | | V |- | style="background:lightgrey" | '''OUTPUT''' | X | V | V | V |- | style="background:lightgrey" | '''POSTROUTING''' | | V | V | |- |} The way to tell Iceditch which table and chain to use, is by grouping all commands for a certain combination of table and chain in one stanza of the configuration file: this is called the ''context'' of the rules. A context is specified in the configuration file with the following header: <pre> context &lt;chain&gt; &lt;table&gt; </pre> Every line that follows is assumed to belong to this particular context, so that in these lines the target chain and table do not need to appear. Currently, every context is allowed to appear multiple times in the configuration file. This means Iceditch allows multiple stanzas per unique context. However, they will be processed in the order in which they appear in the configuration file, so one must be careful that the stanzas are ordered correctly; we'd advise to use each context only once, for maintainability over legibility. ===The target specification=== (Almost) every IPtables rule has a target. Iceditch takes keywords that signify the standard targets, and lets every line begin with this keyword. Thus, the keyword ''accept'' at the beginning of a line signifies that you're talking about an IPtables command that normally would end with ''-j ACCEPT''. The keywords Iceditch currently "understands" are: * accept * drop * reject * redirect * mark * classify * recent * dnat * snat * masquerade * nojump The last one is a bit odd: it signifies an IPtables line that can match a packet, yet won't jump anywhere; thus, Iceditch actually doesn't "do" anything with the packet. This would be the case for a line that you'd insert in order to count certain packets, like iptables -A INPUT -t filter -p icmp -s 10.0.0.1 This line would match any ICMP-packet sent to your machine from IP address 10.0.0.1, but your firewall would not "do" anything with the packet. Thus it would be up to the following lines (or eventually the policy of the table) to actually "do" something with the packet. With the use of CONTEXT, the example line would look like this: <pre>context "INPUT" "filter" nojump -p icmp -s 10.0.0.1</pre> ===The rule syntax=== For every IPtables rule you want to specify in Iceditch, the syntax is based on the underlying IPtables rule. However, Iceditch rules are structured differently: the context is specified at the beginning of the stanza, the target forms the opening keyword, and there are several optional addition to the target. Therefor, forming a firewall rule in Iceditch requires you to follow both Iceditch syntax rules and IPtables syntax rules. Don't worry, it's actually quite simple. What we've done is create a page called the [[Iceditch Command Reference]], where for every target all options are described. However, this reference presupposes intimate knowledge of IPtables. Currently this wiki does not offer a comprehensive course in IPtables; to obtain this knowledge one might start off at sites like [http://iptables-tutorial.frozentux.net/chunkyhtml/index.html this] and [http://security.maruhn.com/ this one]. ===The functionality=== Iceditch helps you create an IPtables based firewall. But ''what'' exactly can it do to help you? You can find out by reading the page on [[Iceditch functionality]], where we list both current functionality, as well as future features. ===The program structure=== Iceditch consists of a number of files, each of which is located in a logical place - at least we think so. For clarity, we've created a comprehensive listing of all the files that comprise the Iceditch package, along with their location and function. It can be found on the [[Iceditch file structure]] page. 03e238ec6a628fce1265353cd7ffef73717d44a9 6 1444 1526 2008-06-27T19:29:09Z Saruman! 2 Netfilter Kernel traversal picture wikitext text/x-wiki Netfilter Kernel traversal picture 29009be412f315ddc66e4ef081cb9a853940d8e2 0 1445 1530 2008-06-28T06:53:21Z 192.168.67.181 0 Creation wikitext text/x-wiki [[Image:Nfk-traversal.png]] This picture has helped me tremendously in understanding Netfilter and IPtables; I have a big colour printout of it hanging on the wall of my study :-) Many, many thanks to [http://linux-ip.net/ Martin Brown]!! e47139e38cfc4c19c12acc81cbc15bd75c75a128 0 1446 1534 2008-06-29T10:29:20Z Saruman! 2 first command defined wikitext text/x-wiki == accept [log [msg <message>]] <qualifiers> == If a network packet matches the qualifiers, then it will be accepted (passed) through the table/chain defined in the context where you put the accept rule. Example: function input_filter { context "INPUT" "filter" accept –p tcp --dport 22 } Iceditch works this out to iptables –t filter –A INPUT –p tcp –-dport 22 –-jump ACCEPT Should you want to log the packet, you’d use accept log msg Secure_Shell –p tcp --dport 22 Iceditch works this out to iptables –t filter –A INPUT –p tcp –-dport 22 \ –-jump LOG --log-prefix Secure_Shell iptables –t filter –A INPUT –p tcp –-dport 22 –-jump ACCEPT You can easily see that “accept log msg Secure_Shell –p tcp --dport 22” is much more readable... Because of how IPtables handles the ACCEPT target, you can only use it in contexts where the table is “filter”. d2a6a8852ae566c090f798194634dc115136cd8a 1535 1534 2008-06-29T13:44:57Z Saruman! 2 added drop/reject and log parameter wikitext text/x-wiki == Parameter: log == ''target '''log [msg <message>]''' <qualifiers>''<br> After most keywords, a "log" parameter can be added (see below). If the "log" parameter is followed by "msg", then the parameter following "msg" is read and used as log-prefix. The parameter is not allowed to have whitespace, and the maximum length of the log-prefix is determined by your version of netfilter/IPtables (usually some 31 characters). Thus a packet matching the rule will be logged with the default setting of the "log" target. If the "log" parameter is ''not'' followed by "msg", then the packet will be logged with the default log message and all the other default setting of the "log" target. Should you want to log a packet with more control over the logging parameters, then you need the ''target keyword'' "log", instead of just following the target keyword with parameter ''log''. For more information, see the target keyword "log" below. == Target keyword: accept == '''''accept [log [msg <message>]] <qualifiers>''''' If a network packet matches the qualifiers, then it will be accepted (passed) through the table/chain defined in the context where you put the accept rule. Example: <pre>context "INPUT" "filter" accept –p tcp --dport 22</pre> Iceditch works this out to iptables –t filter –A INPUT –p tcp –-dport 22 –-jump ACCEPT Should you want to log the packet, you’d use context "INPUT" "filter" accept log msg Secure_Shell –p tcp --dport 22 Iceditch works this out to iptables –t filter –A INPUT –p tcp –-dport 22 \ –-jump LOG --log-prefix Secure_Shell iptables –t filter –A INPUT –p tcp –-dport 22 –-jump ACCEPT You can easily see that “accept log msg Secure_Shell –p tcp --dport 22” is much more readable... Note: because of how IPtables handles the ACCEPT target, you can only use it in contexts where the table is “filter”. == Target keyword: drop == '''''drop [log [msg <message>]] <qualifiers> ''''' In essence, this does the same as the “accept” target keyword, only it jumps to DROP instead of ACCEPT. Thus any packet matching the qualifiers gets discarded; it will not get sent on to its final destination (or next hop), it will not get processed by any other firewall rule, and the sender of the packet is unaware of your treatment of his packet. Because of how iptables handles the DROP target, you can only use it in contexts where the table is “filter”. == Target keyword: reject == '''''reject [with <type>] [log [msg <message>]] <qualifiers>''''' In essence, this does the same as the “drop” target keyword, only it jumps to REJECT instead of DROP. This means the packet is discarded (just as with DROP), but the sender is notified using ICMP (by default, your machine will send an ICMP-packet of type "icmp-port-unreachable"). Because of how iptables handles the REJECT target, you can only use it in contexts where the table is “filter”. Optionally, you can follow “reject” with the keyword “with”, and then use one of the following rejection types: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Type !style="background:#ffdead;"|Description |- | icmp-host-prohibited | will send an ICMP-message "host prohibited" |- |- | icmp-host-prohibited | will send an ICMP-message "host prohibited" |- | icmp-host-unreachable | will send an ICMP-message "host unreachable" |- | icmp-net-prohibited | will send an ICMP-message "net prohibited" |- | icmp-net-unreachable | will send an ICMP-message "net unreachable" |- | icmp-port-prohibited | will send an ICMP-message "port prohibited" |- | icmp-port-unreachable | DEFAULT; will send an ICMP-message "port unreachable" |} If you don’t specify “with <type>”, then netfilter will assume icmp-port-unreachable. Thus, should you want to reject a packet in context filter_INPUT (and log it) with reason net-prohib, you’d use reject with net-prohib log –p tcp –i eth0 --dport 22 The script works this out to iptables –t filter –A INPUT –p tcp –i eth0 –-dport 22 –-jump LOG \ --log-prefix INPUT_REJECT_with_net-prohib: iptables –t filter –A INPUT –p tcp –i eth0 –-dport 22 \ –-jump REJECT –-reject-with net-prohib –p tcp –i eth0 –-dport 22 Surely the rule in the script is more readable… 124cc3599138d9036d7a1c5b8aa9d785c9e21ed4 1536 1535 2008-06-29T14:40:44Z Saruman! 2 added mark target wikitext text/x-wiki == Parameter: log == ''target '''log [msg <message>]''' <qualifiers>''<br> After most keywords, a "log" parameter can be added (see below). If the "log" parameter is followed by "msg", then the parameter following "msg" is read and used as log-prefix. The parameter is not allowed to have whitespace, and the maximum length of the log-prefix is determined by your version of netfilter/IPtables (usually some 31 characters). Thus a packet matching the rule will be logged with the default setting of the "log" target. If the "log" parameter is ''not'' followed by "msg", then the packet will be logged with the default log message for that particular target keyword, and all the other default setting of the "log" target. Thus, should you want to log a packet with more control over the logging parameters, then you need an extra line, beginning with the ''target keyword'' "log", instead of just following the target keyword with parameter ''log''. For more information, see the target keyword "log" below. == Target keyword: accept == '''''accept [log [msg <message>]] <qualifiers>'''''<br> If a network packet matches the qualifiers, then it will be accepted (passed) through the table/chain defined in the context where you put the accept rule. Example: <pre>context "INPUT" "filter" accept –p tcp --dport 22</pre> Iceditch works this out to iptables –t filter –A INPUT –p tcp –-dport 22 –-jump ACCEPT Should you want to log the packet, you’d use context "INPUT" "filter" accept log –p tcp --dport 22 Iceditch works this out to iptables –t filter –A INPUT –p tcp –-dport 22 \ –-jump LOG --log-prefix INPUT_accept iptables –t filter –A INPUT –p tcp –-dport 22 –-jump ACCEPT Note: because of how IPtables handles the ACCEPT target, you can only use it in contexts where the table is “filter”. == Target keyword: classify == '''''classify <classval> [log [msg <message>]] <qualifiers>'''''<br> If a packet travelling through the mangle table in the POSTROUTING chain matches the qualifiers, then it will be classified with the <classval> specified. An example: classify 2:11 –p tcp --dport 22 The script works this out to iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump CLASSIFY --setclass 2:11 Should you want to also log the packet, you’d use classify 2:11 log –p tcp --dport 22 The script works this out to iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump LOG \ --log-prefix classified_2:11: iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump CLASSIFY \ --setclass 2:11 Should you not give a msg, then the log-prefix becomes POSTROUTING_CLASSIFY_set_<classval>. Because of how iptables handles the CLASSIFY target, you can only use it in contexts where the chain is “POSTROUTING” and the table is “mangle”. == Target keyword: drop == '''''drop [log [msg <message>]] <qualifiers> '''''<br> In essence, this does the same as the “accept” target keyword, only it jumps to DROP instead of ACCEPT. Thus any packet matching the qualifiers gets discarded; it will not get sent on to its final destination (or next hop), it will not get processed by any other firewall rule, and the sender of the packet is unaware of your treatment of his packet. Should you want to also log the packet, you’d use context "FORWARD" "filter" drop log –p tcp -s 10.0.0.0/16 The script works this out to iptables –t filter –A FORWARD –p tcp -s 10.0.0.0/16 –-jump LOG \ --log-prefix FORWARD_DROP: iptables –t filter –A FORWARD –p tcp -s 10.0.0.0/16 –-jump DROP Because of how iptables handles the DROP target, you can only use it in contexts where the table is “filter”. == Target keyword: mark == '''''mark <markval> [log [msg <message>]] <qualifiers>'''''<br> If a packet matches the qualifiers, then it will be marked with the <markval> specified. An example from the context “PREROUTING” “mangle”: mark 2 –p tcp --dport 22 Iceditch works this out to iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump MARK --setmark 2 Should you want to also log the packet, you’d use mark 2 log –p tcp --dport 22 Iceditch works this out to iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump LOG \ --log-prefix PREROUTING_MARK_set_2: iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump MARK --setmark 2 Because of how iptables handles the MARK target, you can only use it in contexts where the table is “mangle”. == Target keyword: redirect == '''''redirect [to <to-ports>] [log [msg <message>]] <qualifiers>'''''<br> If a packet matches the qualifiers, then it will be redirected to the local machine, by setting the destination IP to a fitting IP address of the local machine (i.e. 127.0.0.1, or the first-bound IP address of the interface over which it came in. Additionally, by specifying “to <to-ports>” you can have the destination ports redirected to a port or portrange. <to-ports> can either be a port number (e.g. 8080) or a port range (e.g. 6661-6669; the latter is inclusive). Example for a transparent HTTP proxy: context "OUTPUT" "nat" redirect to 8080 –p tcp --dport 80 Iceditch works this out to iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump REDIRECT –to-ports 8080 Should you want to log the packet, you could use redirect to 8080 log –p tcp --dport 80 Iceditch works this out to iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump LOG \ --log-prefix OUTPUT_REDIRECT_to_8080: iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump REDIRECT –-to-ports 8080 Because of how iptables handles the REDIRECT target, you can only use it in contexts where the table is “nat” and the chain is PREROUTING or OUTPUT. == Target keyword: reject == '''''reject [with <type>] [log [msg <message>]] <qualifiers>'''''<br> In essence, this does the same as the “drop” target keyword, only it jumps to REJECT instead of DROP. This means the packet is discarded (just as with DROP), but the sender is notified using ICMP (by default, your machine will send an ICMP-packet of type "icmp-port-unreachable"). Because of how iptables handles the REJECT target, you can only use it in contexts where the table is “filter”. Optionally, you can follow “reject” with the keyword “with”, and then use one of the following rejection types: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Type !style="background:#ffdead;"|Description |- | icmp-host-prohibited | will send an ICMP-message "host prohibited" |- | icmp-host-unreachable | will send an ICMP-message "host unreachable" |- | icmp-net-prohibited | will send an ICMP-message "net prohibited" |- | icmp-net-unreachable | will send an ICMP-message "net unreachable" |- | icmp-port-unreachable | DEFAULT; will send an ICMP-message "port unreachable" |- | icmp-proto-unreachable | DEFAULT; will send an ICMP-message "protocol unreachable" |- | tcp-reset | will send a TCP reset, a packet with the RST flag set (as a response to a TCP packet only) |- | host-prohib | synonymous to icmp-host-prohibited |- | host-unreach | synonymous to icmp-host-unreachable |- | net-prohib | synonymous to icmp-net-prohibited |- | net-unreach | synonymous to icmp-net-unreachable |- | port-unreach | synonymous to icmp-port-unreachable |- | proto-unreach | synonymous to icmp-proto-unreachable |- |} If you don’t specify “with <type>”, then netfilter will assume icmp-port-unreachable. Thus, should you want to reject a packet in context filter_INPUT (and log it) with reason net-prohib, you’d use reject with net-prohib log –p tcp –i eth0 --dport 22 Iceditch works this out to iptables –t filter –A INPUT –p tcp –i eth0 –-dport 22 –-jump LOG \ --log-prefix INPUT_REJECT_with_net-prohib: iptables –t filter –A INPUT –p tcp –i eth0 –-dport 22 \ –-jump REJECT –-reject-with net-prohib –p tcp –i eth0 –-dport 22 96c5252fd2336d53bf491731863dc50ea771ac70 1550 1536 2008-07-05T10:39:31Z Saruman! 2 "log" target added wikitext text/x-wiki == Parameter: log == ''target '''log [msg <message>]''' <qualifiers>''<br> After most keywords, a "log" parameter can be added (see below). If the "log" parameter is followed by "msg", then the parameter following "msg" is read and used as log-prefix. The parameter is not allowed to have whitespace, and the maximum length of the log-prefix is determined by your version of netfilter/IPtables (usually some 31 characters). Thus a packet matching the rule will be logged with the default setting of the "log" target. If the "log" parameter is ''not'' followed by "msg", then the packet will be logged with the default log message for that particular target keyword, and all the other default setting of the "log" target. Thus, should you want to log a packet with more control over the logging parameters, then you need an extra line, beginning with the ''target keyword'' "log", instead of just following the target keyword with parameter ''log''. For more information, see the target keyword "log" below. == Target keyword: accept == '''''accept [log [msg <message>]] <qualifiers>'''''<br> If a network packet matches the qualifiers, then it will be accepted (passed) through the table/chain defined in the context where you put the accept rule. Example: <pre>context "INPUT" "filter" accept –p tcp --dport 22</pre> Iceditch works this out to iptables –t filter –A INPUT –p tcp –-dport 22 –-jump ACCEPT Should you want to log the packet, you’d use context "INPUT" "filter" accept log –p tcp --dport 22 Iceditch works this out to iptables –t filter –A INPUT –p tcp –-dport 22 \ –-jump LOG --log-prefix INPUT_accept iptables –t filter –A INPUT –p tcp –-dport 22 –-jump ACCEPT Note: because of how IPtables handles the ACCEPT target, you can only use it in contexts where the table is “filter”. == Target keyword: classify == '''''classify <classval> [log [msg <message>]] <qualifiers>'''''<br> If a packet travelling through the mangle table in the POSTROUTING chain matches the qualifiers, then it will be classified with the <classval> specified. An example: classify 2:11 –p tcp --dport 22 The script works this out to iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump CLASSIFY --setclass 2:11 Should you want to also log the packet, you’d use classify 2:11 log –p tcp --dport 22 The script works this out to iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump LOG \ --log-prefix classified_2:11: iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump CLASSIFY \ --setclass 2:11 Should you not give a msg, then the log-prefix becomes POSTROUTING_CLASSIFY_set_<classval>. Because of how iptables handles the CLASSIFY target, you can only use it in contexts where the chain is “POSTROUTING” and the table is “mangle”. == Target keyword: drop == '''''drop [log [msg <message>]] <qualifiers> '''''<br> In essence, this does the same as the “accept” target keyword, only it jumps to DROP instead of ACCEPT. Thus any packet matching the qualifiers gets discarded; it will not get sent on to its final destination (or next hop), it will not get processed by any other firewall rule, and the sender of the packet is unaware of your treatment of his packet. Should you want to also log the packet, you’d use context "FORWARD" "filter" drop log –p tcp -s 10.0.0.0/16 The script works this out to iptables –t filter –A FORWARD –p tcp -s 10.0.0.0/16 –-jump LOG \ --log-prefix FORWARD_DROP: iptables –t filter –A FORWARD –p tcp -s 10.0.0.0/16 –-jump DROP Because of how iptables handles the DROP target, you can only use it in contexts where the table is “filter”. == Target keyword: log == '''''log [msg <message>] [lvl <loglevel>] <qualifiers>'''''<br> Sometimes, the standard ''log'' parameter is just not enough. This is mostly the case when you want to log a packet to a log-level other than the default level, which for most systems is 4 (''warning''). For this reason, AND for flexibility and clarity, Iceditch has its own target keyword ''log''. Just as when you use the ''log'' parameter, Iceditch will call the log target specified in the Iceditch [[Iceditch file structure | config file]]. Standard this is LOG, but optionally you could specify ULOG. Depending on which log target you have specified, there are some options you can use with the Iceditch target keyword ''log'': == Target keyword: mark == '''''mark <markval> [log [msg <message>]] <qualifiers>'''''<br> If a packet matches the qualifiers, then it will be marked with the <markval> specified. An example from the context “PREROUTING” “mangle”: mark 2 –p tcp --dport 22 Iceditch works this out to iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump MARK --setmark 2 Should you want to also log the packet, you’d use mark 2 log –p tcp --dport 22 Iceditch works this out to iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump LOG \ --log-prefix PREROUTING_MARK_set_2: iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump MARK --setmark 2 Because of how iptables handles the MARK target, you can only use it in contexts where the table is “mangle”. == Target keyword: redirect == '''''redirect [to <to-ports>] [log [msg <message>]] <qualifiers>'''''<br> If a packet matches the qualifiers, then it will be redirected to the local machine, by setting the destination IP to a fitting IP address of the local machine (i.e. 127.0.0.1, or the first-bound IP address of the interface over which it came in. Additionally, by specifying “to <to-ports>” you can have the destination ports redirected to a port or portrange. <to-ports> can either be a port number (e.g. 8080) or a port range (e.g. 6661-6669; the latter is inclusive). Example for a transparent HTTP proxy: context "OUTPUT" "nat" redirect to 8080 –p tcp --dport 80 Iceditch works this out to iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump REDIRECT –to-ports 8080 Should you want to log the packet, you could use redirect to 8080 log –p tcp --dport 80 Iceditch works this out to iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump LOG \ --log-prefix OUTPUT_REDIRECT_to_8080: iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump REDIRECT –-to-ports 8080 Because of how iptables handles the REDIRECT target, you can only use it in contexts where the table is “nat” and the chain is PREROUTING or OUTPUT. == Target keyword: reject == '''''reject [with <type>] [log [msg <message>]] <qualifiers>'''''<br> In essence, this does the same as the “drop” target keyword, only it jumps to REJECT instead of DROP. This means the packet is discarded (just as with DROP), but the sender is notified using ICMP (by default, your machine will send an ICMP-packet of type "icmp-port-unreachable"). Because of how iptables handles the REJECT target, you can only use it in contexts where the table is “filter”. Optionally, you can follow “reject” with the keyword “with”, and then use one of the following rejection types: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Type !style="background:#ffdead;"|Description |- | icmp-host-prohibited | will send an ICMP-message "host prohibited" |- | icmp-host-unreachable | will send an ICMP-message "host unreachable" |- | icmp-net-prohibited | will send an ICMP-message "net prohibited" |- | icmp-net-unreachable | will send an ICMP-message "net unreachable" |- | icmp-port-unreachable | DEFAULT; will send an ICMP-message "port unreachable" |- | icmp-proto-unreachable | DEFAULT; will send an ICMP-message "protocol unreachable" |- | tcp-reset | will send a TCP reset, a packet with the RST flag set (as a response to a TCP packet only) |- | host-prohib | synonymous to icmp-host-prohibited |- | host-unreach | synonymous to icmp-host-unreachable |- | net-prohib | synonymous to icmp-net-prohibited |- | net-unreach | synonymous to icmp-net-unreachable |- | port-unreach | synonymous to icmp-port-unreachable |- | proto-unreach | synonymous to icmp-proto-unreachable |- |} If you don’t specify “with <type>”, then netfilter will assume icmp-port-unreachable. Thus, should you want to reject a packet in context filter_INPUT (and log it) with reason net-prohib, you’d use reject with net-prohib log –p tcp –i eth0 --dport 22 Iceditch works this out to iptables –t filter –A INPUT –p tcp –i eth0 –-dport 22 –-jump LOG \ --log-prefix INPUT_REJECT_with_net-prohib: iptables –t filter –A INPUT –p tcp –i eth0 –-dport 22 \ –-jump REJECT –-reject-with net-prohib –p tcp –i eth0 –-dport 22 b6661b6a44b805a0139d8cc938b7ddd3f8cf6638 1551 1550 2008-07-05T11:55:57Z Saruman! 2 /* Target keyword: log */ added option tables wikitext text/x-wiki == Parameter: log == ''target '''log [msg <message>]''' <qualifiers>''<br> After most keywords, a "log" parameter can be added (see below). If the "log" parameter is followed by "msg", then the parameter following "msg" is read and used as log-prefix. The parameter is not allowed to have whitespace, and the maximum length of the log-prefix is determined by your version of netfilter/IPtables (usually some 31 characters). Thus a packet matching the rule will be logged with the default setting of the "log" target. If the "log" parameter is ''not'' followed by "msg", then the packet will be logged with the default log message for that particular target keyword, and all the other default setting of the "log" target. Thus, should you want to log a packet with more control over the logging parameters, then you need an extra line, beginning with the ''target keyword'' "log", instead of just following the target keyword with parameter ''log''. For more information, see the target keyword "log" below. == Target keyword: accept == '''''accept [log [msg <message>]] <qualifiers>'''''<br> If a network packet matches the qualifiers, then it will be accepted (passed) through the table/chain defined in the context where you put the accept rule. Example: <pre>context "INPUT" "filter" accept –p tcp --dport 22</pre> Iceditch works this out to iptables –t filter –A INPUT –p tcp –-dport 22 –-jump ACCEPT Should you want to log the packet, you’d use context "INPUT" "filter" accept log –p tcp --dport 22 Iceditch works this out to iptables –t filter –A INPUT –p tcp –-dport 22 \ –-jump LOG --log-prefix INPUT_accept iptables –t filter –A INPUT –p tcp –-dport 22 –-jump ACCEPT Note: because of how IPtables handles the ACCEPT target, you can only use it in contexts where the table is “filter”. == Target keyword: classify == '''''classify <classval> [log [msg <message>]] <qualifiers>'''''<br> If a packet travelling through the mangle table in the POSTROUTING chain matches the qualifiers, then it will be classified with the <classval> specified. An example: classify 2:11 –p tcp --dport 22 The script works this out to iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump CLASSIFY --setclass 2:11 Should you want to also log the packet, you’d use classify 2:11 log –p tcp --dport 22 The script works this out to iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump LOG \ --log-prefix classified_2:11: iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump CLASSIFY \ --setclass 2:11 Should you not give a msg, then the log-prefix becomes POSTROUTING_CLASSIFY_set_<classval>. Because of how iptables handles the CLASSIFY target, you can only use it in contexts where the chain is “POSTROUTING” and the table is “mangle”. == Target keyword: drop == '''''drop [log [msg <message>]] <qualifiers> '''''<br> In essence, this does the same as the “accept” target keyword, only it jumps to DROP instead of ACCEPT. Thus any packet matching the qualifiers gets discarded; it will not get sent on to its final destination (or next hop), it will not get processed by any other firewall rule, and the sender of the packet is unaware of your treatment of his packet. Should you want to also log the packet, you’d use context "FORWARD" "filter" drop log –p tcp -s 10.0.0.0/16 The script works this out to iptables –t filter –A FORWARD –p tcp -s 10.0.0.0/16 –-jump LOG \ --log-prefix FORWARD_DROP: iptables –t filter –A FORWARD –p tcp -s 10.0.0.0/16 –-jump DROP Because of how iptables handles the DROP target, you can only use it in contexts where the table is “filter”. == Target keyword: log == '''''log [msg <message>] [lvl <loglevel>] <qualifiers>'''''<br> Sometimes, the standard ''log'' parameter is just not enough. This is mostly the case when you want to log a packet to a log-level other than the default level, which for most systems is 4 (''warning''). For this reason, AND for flexibility and clarity, Iceditch has its own target keyword ''log''. Just as when you use the ''log'' parameter, Iceditch will call the log target specified in the Iceditch [[Iceditch file structure | config file]]. Standard this is LOG, but optionally you could specify ULOG. Depending on which log target you have specified, there are some options you can use with the Iceditch target keyword ''log''; it is currently deemed unnecessary to make specific Iceditch parameters for them, but we'll list the official IPtables options here, which you can put in the <qualifiers> list: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" ! colspan="2" style="background:#ffdead;"|LOG options | ! colspan="2" style="background:#ffdead;"|ULOG options |- !style="background:#ffdead;"|Option !style="background:#ffdead;"|Description | !style="background:#ffdead;"|Option !style="background:#ffdead;"|Description |- | --log-ip-options |Makes Netfilter include the IP options in the log entry | | --ulog-cprange <''size''> |log the first ''size'' bytes of each packet |- | --log-tcp-options |Makes Netfilter include the TCP options in the log entry | | --ulog-nlgroup <''nlgroup''> |Log to Netlink group number ''nlgroup'' (must match ''/etc/ulogd.conf'') |- | --log-tcp-sequence |Makes Netfilter include the TCP sequence number in the log entry | | --ulog-qthreshold <''value''> |Queue ''value'' packets before sending them to ''ulogd'' (default = 1, max = 50) |- |} <br> For completeness, we here reproduce the list of logging levels that LOG understands: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Level !style="background:#ffdead;"|Description |- |0 |''emerg'' or ''panic'' |- |1 |''alert'' |- |2 |''crit'' |- |3 |''err'' |- |4 |''warn'' (default) |- |5 |''notice'' |- |6 |''info'' |- |7 |''debug'' |- |} == Target keyword: mark == '''''mark <markval> [log [msg <message>]] <qualifiers>'''''<br> If a packet matches the qualifiers, then it will be marked with the <markval> specified. An example from the context “PREROUTING” “mangle”: mark 2 –p tcp --dport 22 Iceditch works this out to iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump MARK --setmark 2 Should you want to also log the packet, you’d use mark 2 log –p tcp --dport 22 Iceditch works this out to iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump LOG \ --log-prefix PREROUTING_MARK_set_2: iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump MARK --setmark 2 Because of how iptables handles the MARK target, you can only use it in contexts where the table is “mangle”. == Target keyword: redirect == '''''redirect [to <to-ports>] [log [msg <message>]] <qualifiers>'''''<br> If a packet matches the qualifiers, then it will be redirected to the local machine, by setting the destination IP to a fitting IP address of the local machine (i.e. 127.0.0.1, or the first-bound IP address of the interface over which it came in. Additionally, by specifying “to <to-ports>” you can have the destination ports redirected to a port or portrange. <to-ports> can either be a port number (e.g. 8080) or a port range (e.g. 6661-6669; the latter is inclusive). Example for a transparent HTTP proxy: context "OUTPUT" "nat" redirect to 8080 –p tcp --dport 80 Iceditch works this out to iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump REDIRECT –to-ports 8080 Should you want to log the packet, you could use redirect to 8080 log –p tcp --dport 80 Iceditch works this out to iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump LOG \ --log-prefix OUTPUT_REDIRECT_to_8080: iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump REDIRECT –-to-ports 8080 Because of how iptables handles the REDIRECT target, you can only use it in contexts where the table is “nat” and the chain is PREROUTING or OUTPUT. == Target keyword: reject == '''''reject [with <type>] [log [msg <message>]] <qualifiers>'''''<br> In essence, this does the same as the “drop” target keyword, only it jumps to REJECT instead of DROP. This means the packet is discarded (just as with DROP), but the sender is notified using ICMP (by default, your machine will send an ICMP-packet of type "icmp-port-unreachable"). Because of how iptables handles the REJECT target, you can only use it in contexts where the table is “filter”. Optionally, you can follow “reject” with the keyword “with”, and then use one of the following rejection types: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Type !style="background:#ffdead;"|Description |- | icmp-host-prohibited | will send an ICMP-message "host prohibited" |- | icmp-host-unreachable | will send an ICMP-message "host unreachable" |- | icmp-net-prohibited | will send an ICMP-message "net prohibited" |- | icmp-net-unreachable | will send an ICMP-message "net unreachable" |- | icmp-port-unreachable | DEFAULT; will send an ICMP-message "port unreachable" |- | icmp-proto-unreachable | DEFAULT; will send an ICMP-message "protocol unreachable" |- | tcp-reset | will send a TCP reset, a packet with the RST flag set (as a response to a TCP packet only) |- | host-prohib | synonymous to icmp-host-prohibited |- | host-unreach | synonymous to icmp-host-unreachable |- | net-prohib | synonymous to icmp-net-prohibited |- | net-unreach | synonymous to icmp-net-unreachable |- | port-unreach | synonymous to icmp-port-unreachable |- | proto-unreach | synonymous to icmp-proto-unreachable |- |} If you don’t specify “with <type>”, then netfilter will assume icmp-port-unreachable. Thus, should you want to reject a packet in context filter_INPUT (and log it) with reason net-prohib, you’d use reject with net-prohib log –p tcp –i eth0 --dport 22 Iceditch works this out to iptables –t filter –A INPUT –p tcp –i eth0 –-dport 22 –-jump LOG \ --log-prefix INPUT_REJECT_with_net-prohib: iptables –t filter –A INPUT –p tcp –i eth0 –-dport 22 \ –-jump REJECT –-reject-with net-prohib –p tcp –i eth0 –-dport 22 6b82d61af3245aeeb34956081232d09452d59f02 0 1434 1537 1505 2008-06-29T15:56:11Z Saruman! 2 /* Installation of MediaWiki */ footer change added wikitext text/x-wiki ==Installation of MediaWiki== An extra feature we added was support for iFrames by means of a little PHP script that we googled; the extension is called [[The websiteFrame PHP extension| websiteFrame.php]]. Furthermore, we [[wiki footer change |changed the Creative Commons picture]] in the footer from a remote one to a local one. 2791148b714daef79d6fbc3a4e873b5f501c41b6 0 1447 1538 2008-06-29T16:10:02Z Saruman! 2 Page created wikitext text/x-wiki * download the needed picture (e.g. from [http://i.creativecommons.org/l/by-nc-sa/3.0/88x31.png http://i.creativecommons.org/l/by-nc-sa/3.0/88x31.png]). * save it to ''/usr/share/mediawiki1.7/skins/common/images/''; if so desired, rename it (we did: to ''by-nc-sa_88x31.png''); remember to set the owner to ''root:root''. * change ''/var/lib/mediawiki1.7/LocalSettings.php'' to include the following line:<br><pre>$wgRightsIcon = "https://oberon.saruman.biz/wiki/skins/common/images/by-nc-sa_88x31.png";</pre> That's it! 67941322b7f8bc18ba6750b89d597f5134fbf515 0 1448 1540 2008-06-30T20:57:23Z Saruman! 2 First inventory of functionality wikitext text/x-wiki This page describes the functions that the Iceditch script can perform for you. ===Rights and security=== Since Iceditch calls IPtables, you need root rights to call it. We therefor have not implemented any mechanism to use Iceditch as a non-root user. ===Invoking Iceditch=== '''iceditch start'''<br> The most common invocation will be the automatic startup at boot time. To this end, the script understands being called with only the "start" parameter. ''iceditch start'' will setup the firewall quietly and completely.<br> '''iceditch restart''' and '''iceditch reload'''<br> These two invocations start up the firewall just as ''start'' does: the firewall is cleared and set up, quietly and completely.<br> '''iceditch stop'''<br> We don't want anyone to be able to ''stop'' the firewall, so this command is accepted, but does nothing (except log the attempt).<br> '''iceditch clear'''<br> This clears all firewall rules, so essentially you're left with no firewall at all. Thus, you're also left without transparent proxy, NATting etcetera. Since this is inherently very unsafe, Iceditch will ''also'' disable forwarding between network interfaces.<br> '''iceditch safestart'''<br> This will have Iceditch start the firewall, but after five minutes, it will fall back to the backup configuration. This enables you to backup the current configuration, change it, and test it. If it accidentally shuts you out, it will revert to the old configuration after five minutes. Good thinking, eh? Note: requires the presence of the ''at'' command, where Iceditch will schedule the fallback to the old configuration.<br> '''iceditch noclear'''<br> This command will remove the fallback to the old configuration by clearing the ''at'' fallback. '''iceditch halt'''<br> This is an emergency break: it will clear all firewall rules, and then block any network traffic going in or out of your machine over any network interface - with the exception of the ''lo'' internal network adapter. When you have reason to believe your system is in some way compromised, you can throw this emergency brake. For those who don't need or want it: the configuration file can disable this emergency break. ===Special options=== There are a number of options that Iceditch recognises, that are listed below. Note: options cannot be grouped. Iceditch understands ''-d -e'' but not ''-de''.<br> '''-d''' dummy run; prevents Iceditch to actually invoke IPtables at all. Used mainly with -e or -E<br> '''-e''' will make Iceditch echo all generated IPtables commands to the console. This can be useful to test a complex configuration.<br> '''-E''' will make Iceditch echo all rules in Iceditch language. Only useful if your rulefile contains lots of conditional rules, flow control and other programming bling.<br> '''-r <rulefile>''' will make Iceditch use <rulefile> instead of the default rulefile /etc/iceditch/rules.conf. <rulefile> can be specified with an absolute path, with a relative path from the current working directory, or without path at all (in which case Iceditch assumes the file lives in /etc/iceditch).<br> '''-v''' verbosity; will make Iceditch send the -v option to all commands it calls itself<br> '''-V''' print the version number and exit (overrides any other option or parameter)<br> ===Logging=== Iceditch logs any (attempted) start or stop action to the syslog. When the Iceditch-built firewall runs, it can make use of the standard IPtables log facilities. These can be either logging packages to syslog, or using the ''ulogd'' logging daemon. This choice can be specified in the Iceditch configuration file, although you have to ensure yourself that ''ulogd'' actually exists on your system. fd4d06c718464098c9772ae548b309d6938a15be 1541 1540 2008-07-01T05:15:59Z Saruman! 2 /* Special options */ added -t switch wikitext text/x-wiki This page describes the functions that the Iceditch script can perform for you. ===Rights and security=== Since Iceditch calls IPtables, you need root rights to call it. We therefor have not implemented any mechanism to use Iceditch as a non-root user. ===Invoking Iceditch=== '''iceditch start'''<br> The most common invocation will be the automatic startup at boot time. To this end, the script understands being called with only the "start" parameter. ''iceditch start'' will setup the firewall quietly and completely.<br> '''iceditch restart''' and '''iceditch reload'''<br> These two invocations start up the firewall just as ''start'' does: the firewall is cleared and set up, quietly and completely.<br> '''iceditch stop'''<br> We don't want anyone to be able to ''stop'' the firewall, so this command is accepted, but does nothing (except log the attempt).<br> '''iceditch clear'''<br> This clears all firewall rules, so essentially you're left with no firewall at all. Thus, you're also left without transparent proxy, NATting etcetera. Since this is inherently very unsafe, Iceditch will ''also'' disable forwarding between network interfaces.<br> '''iceditch safestart'''<br> This will have Iceditch start the firewall, but after five minutes, it will fall back to the backup configuration. This enables you to backup the current configuration, change it, and test it. If it accidentally shuts you out, it will revert to the old configuration after five minutes. Good thinking, eh? Note: requires the presence of the ''at'' command, where Iceditch will schedule the fallback to the old configuration.<br> '''iceditch noclear'''<br> This command will remove the fallback to the old configuration by clearing the ''at'' fallback. '''iceditch halt'''<br> This is an emergency break: it will clear all firewall rules, and then block any network traffic going in or out of your machine over any network interface - with the exception of the ''lo'' internal network adapter. When you have reason to believe your system is in some way compromised, you can throw this emergency brake. For those who don't need or want it: the configuration file can disable this emergency break. ===Special options=== There are a number of options that Iceditch recognises, that are listed below. Note: options cannot be grouped. Iceditch understands ''-d -e'' but not ''-de''.<br> '''-d''' dummy run; prevents Iceditch to actually invoke IPtables at all. Used mainly with -e or -E<br> '''-e''' will make Iceditch echo all generated IPtables commands to the console. This can be useful to test a complex configuration.<br> '''-E''' will make Iceditch echo all rules in Iceditch language. Only useful if your rulefile contains lots of conditional rules, flow control and other programming bling.<br> '''-r <rulefile>''' will make Iceditch use <rulefile> instead of the default rulefile /etc/iceditch/rules.conf. <rulefile> can be specified with an absolute path, with a relative path from the current working directory, or without path at all (in which case Iceditch assumes the file lives in /etc/iceditch).<br> '''-t <number>''' can be used only with ''safestart''; it signifies the number of minutes (1-60) that ''safestart'' must wait before it reverts the configuration.<br> '''-v''' verbosity; will make Iceditch send the -v option to all commands it calls itself<br> '''-V''' print the version number and exit (overrides any other option or parameter)<br> ===Logging=== Iceditch logs any (attempted) start or stop action to the syslog. When the Iceditch-built firewall runs, it can make use of the standard IPtables log facilities. These can be either logging packages to syslog, or using the ''ulogd'' logging daemon. This choice can be specified in the Iceditch configuration file, although you have to ensure yourself that ''ulogd'' actually exists on your system. 24fcb7af0ebc07e3c8bb6daa1ca919934662a64e 1542 1541 2008-07-01T05:22:52Z Saruman! 2 /* Invoking Iceditch */ added backup/restore wikitext text/x-wiki This page describes the functions that the Iceditch script can perform for you. ===Rights and security=== Since Iceditch calls IPtables, you need root rights to call it. We therefor have not implemented any mechanism to use Iceditch as a non-root user. ===Invoking Iceditch=== '''iceditch start | restart | reload'''<br> The most common invocation will be the automatic startup at boot time. To this end, the script understands being called with only the "start" parameter. ''iceditch start'' will setup the firewall quietly and completely.<br> '''iceditch stop | halt'''<br> We don't want anyone person or process to be able to ''stop'' the firewall, so this command is accepted, but does nothing except log the attempt.<br> '''iceditch clear'''<br> This clears all firewall rules, so essentially you're left with no firewall at all. Thus, you're also left without transparent proxy, NATting etcetera. Since this is inherently very unsafe, Iceditch will ''also'' disable forwarding between network interfaces.<br> '''iceditch backup'''<br> This will make Iceditch write a copy of the current configuration files. Used mainly with ''safestart''. '''iceditch safestart'''<br> This will have Iceditch start the firewall, but after five minutes, it will revert to the backup configuration. This enables you to backup the current configuration, change it, and test it. If it accidentally shuts you out, it will revert to the old configuration after five minutes. Good thinking, eh? Note: requires the presence of the ''at'' command, where Iceditch will schedule the fallback to the old configuration.<br> '''iceditch restore'''<br> This will make Iceditch revert to the configuration it previously backed up. Note: this command can only be run interactively, since Iceditch will tell you at which time and date the backup configuration was made, and ask you if you really want to overwrite the current configuration with the old one. '''iceditch noclear'''<br> This command will remove the fallback to the old configuration by clearing the ''at'' fallback. '''iceditch halt'''<br> This is an emergency break: it will clear all firewall rules, and then block any network traffic going in or out of your machine over any network interface - with the exception of the ''lo'' internal network adapter. When you have reason to believe your system is in some way compromised, you can throw this emergency brake. For those who don't need or want it: the configuration file can disable this emergency break. ===Special options=== There are a number of options that Iceditch recognises, that are listed below. Note: options cannot be grouped. Iceditch understands ''-d -e'' but not ''-de''.<br> '''-d''' dummy run; prevents Iceditch to actually invoke IPtables at all. Used mainly with -e or -E<br> '''-e''' will make Iceditch echo all generated IPtables commands to the console. This can be useful to test a complex configuration.<br> '''-E''' will make Iceditch echo all rules in Iceditch language. Only useful if your rulefile contains lots of conditional rules, flow control and other programming bling.<br> '''-r <rulefile>''' will make Iceditch use <rulefile> instead of the default rulefile /etc/iceditch/rules.conf. <rulefile> can be specified with an absolute path, with a relative path from the current working directory, or without path at all (in which case Iceditch assumes the file lives in /etc/iceditch).<br> '''-t <number>''' can be used only with ''safestart''; it signifies the number of minutes (1-60) that ''safestart'' must wait before it reverts the configuration.<br> '''-v''' verbosity; will make Iceditch send the -v option to all commands it calls itself<br> '''-V''' print the version number and exit (overrides any other option or parameter)<br> ===Logging=== Iceditch logs any (attempted) start or stop action to the syslog. When the Iceditch-built firewall runs, it can make use of the standard IPtables log facilities. These can be either logging packages to syslog, or using the ''ulogd'' logging daemon. This choice can be specified in the Iceditch configuration file, although you have to ensure yourself that ''ulogd'' actually exists on your system. 1cb19075582098eae22e5ef31b64ab4c835a1cad 1543 1542 2008-07-01T05:29:15Z Saruman! 2 /* Special options */ changed layout wikitext text/x-wiki This page describes the functions that the Iceditch script can perform for you. ===Rights and security=== Since Iceditch calls IPtables, you need root rights to call it. We therefor have not implemented any mechanism to use Iceditch as a non-root user. ===Invoking Iceditch=== '''iceditch start | restart | reload'''<br> The most common invocation will be the automatic startup at boot time. To this end, the script understands being called with only the "start" parameter. ''iceditch start'' will setup the firewall quietly and completely.<br> '''iceditch stop | halt'''<br> We don't want anyone person or process to be able to ''stop'' the firewall, so this command is accepted, but does nothing except log the attempt.<br> '''iceditch clear'''<br> This clears all firewall rules, so essentially you're left with no firewall at all. Thus, you're also left without transparent proxy, NATting etcetera. Since this is inherently very unsafe, Iceditch will ''also'' disable forwarding between network interfaces.<br> '''iceditch backup'''<br> This will make Iceditch write a copy of the current configuration files. Used mainly with ''safestart''. '''iceditch safestart'''<br> This will have Iceditch start the firewall, but after five minutes, it will revert to the backup configuration. This enables you to backup the current configuration, change it, and test it. If it accidentally shuts you out, it will revert to the old configuration after five minutes. Good thinking, eh? Note: requires the presence of the ''at'' command, where Iceditch will schedule the fallback to the old configuration.<br> '''iceditch restore'''<br> This will make Iceditch revert to the configuration it previously backed up. Note: this command can only be run interactively, since Iceditch will tell you at which time and date the backup configuration was made, and ask you if you really want to overwrite the current configuration with the old one. '''iceditch noclear'''<br> This command will remove the fallback to the old configuration by clearing the ''at'' fallback. '''iceditch halt'''<br> This is an emergency break: it will clear all firewall rules, and then block any network traffic going in or out of your machine over any network interface - with the exception of the ''lo'' internal network adapter. When you have reason to believe your system is in some way compromised, you can throw this emergency brake. For those who don't need or want it: the configuration file can disable this emergency break. ===Special options=== There are a number of options that Iceditch recognises, that are listed below. Note: options cannot be grouped. For example, Iceditch understands ''-d -e'' but not ''-de''.<br> '''-d''' dummy run; prevents Iceditch to actually invoke IPtables at all. Used mainly with ''-e'' or ''-E'', to check a configuration.<br> '''-e''' will make Iceditch echo all generated IPtables commands to the console. This can be useful to test a complex configuration. ''-e'' cannot be combined with ''-E''<br> '''-E''' will make Iceditch echo all rules in Iceditch language. Only useful if your rulefile contains lots of conditional rules, flow control and other programming bling. ''-E'' cannot be combined with ''-e''<br> '''-r <rulefile>''' will make Iceditch use ''<rulefile>'' instead of the default rulefile ''/etc/iceditch/rules.conf''. ''<rulefile>'' can be specified with an absolute path, with a relative path from the current working directory, or without path at all (in which case Iceditch assumes the file lives in ''/etc/iceditch'').<br> '''-t <number>''' can be used only with ''safestart''; it signifies the number of minutes (1-60) that ''safestart'' must wait before it reverts the configuration.<br> '''-v''' verbosity; will make Iceditch send the -v option to all commands it calls itself<br> '''-V''' print the version number and exit (overrides any other option or parameter)<br> ===Logging=== Iceditch logs any (attempted) start or stop action to the syslog. When the Iceditch-built firewall runs, it can make use of the standard IPtables log facilities. These can be either logging packages to syslog, or using the ''ulogd'' logging daemon. This choice can be specified in the Iceditch configuration file, although you have to ensure yourself that ''ulogd'' actually exists on your system. af4c6366b00c40e914dc0085d184a156e34fd173 1544 1543 2008-07-01T05:31:00Z Saruman! 2 /* Invoking Iceditch */ layout wikitext text/x-wiki This page describes the functions that the Iceditch script can perform for you. ===Rights and security=== Since Iceditch calls IPtables, you need root rights to call it. We therefor have not implemented any mechanism to use Iceditch as a non-root user. ===Invoking Iceditch=== '''iceditch start | restart | reload'''<br> The most common invocation will be the automatic startup at boot time. To this end, the script understands being called with only the "start" parameter. ''iceditch start'' will setup the firewall quietly and completely.<br> '''iceditch stop | halt'''<br> We don't want anyone person or process to be able to ''stop'' the firewall, so this command is accepted, but does nothing except log the attempt.<br> '''iceditch clear'''<br> This clears all firewall rules, so essentially you're left with no firewall at all. Thus, you're also left without transparent proxy, NATting etcetera. Since this is inherently very unsafe, Iceditch will ''also'' disable forwarding between network interfaces.<br> '''iceditch backup'''<br> This will make Iceditch write a copy of the current configuration files. Used mainly to accommodate ''safestart''.<br> '''iceditch safestart'''<br> This will have Iceditch start the firewall, but after five minutes, it will revert to the backup configuration. This enables you to backup the current configuration, change it, and test it. If it accidentally shuts you out, it will revert to the old configuration after five minutes. Good thinking, eh? Note: requires the presence of the ''at'' command, where Iceditch will schedule the fallback to the old configuration.<br> '''iceditch restore'''<br> This will make Iceditch revert to the configuration it previously backed up. Note: this command can only be run interactively, since Iceditch will tell you at which time and date the backup configuration was made, and ask you if you really want to overwrite the current configuration with the old one. '''iceditch noclear'''<br> This command will remove the fallback to the old configuration by clearing the ''at'' fallback. '''iceditch halt'''<br> This is an emergency break: it will clear all firewall rules, and then block any network traffic going in or out of your machine over any network interface - with the exception of the ''lo'' internal network adapter. When you have reason to believe your system is in some way compromised, you can throw this emergency brake. For those who don't need or want it: the configuration file can disable this emergency break. ===Special options=== There are a number of options that Iceditch recognises, that are listed below. Note: options cannot be grouped. For example, Iceditch understands ''-d -e'' but not ''-de''.<br> '''-d''' dummy run; prevents Iceditch to actually invoke IPtables at all. Used mainly with ''-e'' or ''-E'', to check a configuration.<br> '''-e''' will make Iceditch echo all generated IPtables commands to the console. This can be useful to test a complex configuration. ''-e'' cannot be combined with ''-E''<br> '''-E''' will make Iceditch echo all rules in Iceditch language. Only useful if your rulefile contains lots of conditional rules, flow control and other programming bling. ''-E'' cannot be combined with ''-e''<br> '''-r <rulefile>''' will make Iceditch use ''<rulefile>'' instead of the default rulefile ''/etc/iceditch/rules.conf''. ''<rulefile>'' can be specified with an absolute path, with a relative path from the current working directory, or without path at all (in which case Iceditch assumes the file lives in ''/etc/iceditch'').<br> '''-t <number>''' can be used only with ''safestart''; it signifies the number of minutes (1-60) that ''safestart'' must wait before it reverts the configuration.<br> '''-v''' verbosity; will make Iceditch send the -v option to all commands it calls itself<br> '''-V''' print the version number and exit (overrides any other option or parameter)<br> ===Logging=== Iceditch logs any (attempted) start or stop action to the syslog. When the Iceditch-built firewall runs, it can make use of the standard IPtables log facilities. These can be either logging packages to syslog, or using the ''ulogd'' logging daemon. This choice can be specified in the Iceditch configuration file, although you have to ensure yourself that ''ulogd'' actually exists on your system. 99f5e3bb463cd5cf22671e4e0fef451610253520 1545 1544 2008-07-01T05:33:19Z Saruman! 2 /* Invoking Iceditch */ expanded safestart wikitext text/x-wiki This page describes the functions that the Iceditch script can perform for you. ===Rights and security=== Since Iceditch calls IPtables, you need root rights to call it. We therefor have not implemented any mechanism to use Iceditch as a non-root user. ===Invoking Iceditch=== '''iceditch start | restart | reload'''<br> The most common invocation will be the automatic startup at boot time. To this end, the script understands being called with only the "start" parameter. ''iceditch start'' will setup the firewall quietly and completely.<br> '''iceditch stop | halt'''<br> We don't want anyone person or process to be able to ''stop'' the firewall, so this command is accepted, but does nothing except log the attempt.<br> '''iceditch clear'''<br> This clears all firewall rules, so essentially you're left with no firewall at all. Thus, you're also left without transparent proxy, NATting etcetera. Since this is inherently very unsafe, Iceditch will ''also'' disable forwarding between network interfaces.<br> '''iceditch backup'''<br> This will make Iceditch write a copy of the current configuration files. Used mainly to accommodate ''safestart''.<br> '''iceditch safestart'''<br> This will have Iceditch start the firewall, but after five minutes, it will revert to the backup configuration. This enables you to backup the current configuration, change it, and test it. If it accidentally shuts you out, it will revert to the old configuration after five minutes. Good thinking, eh? Note: requires that you've made a backup confiuration; if none is present, safestart will ''clear'' the firewall upon the reversion time. Furthermore this option requires availability of the ''at'' command, where Iceditch will schedule the fallback to the old configuration.<br> '''iceditch restore'''<br> This will make Iceditch revert to the configuration it previously backed up. Note: this command can only be run interactively, since Iceditch will tell you at which time and date the backup configuration was made, and ask you if you really want to overwrite the current configuration with the old one.<br> '''iceditch noclear'''<br> This command will remove the fallback to the old configuration by clearing the ''at'' fallback.<br> '''iceditch halt'''<br> This is an emergency break: it will clear all firewall rules, and then block any network traffic going in or out of your machine over any network interface - with the exception of the ''lo'' internal network adapter. When you have reason to believe your system is in some way compromised, you can throw this emergency brake. For those who don't need or want it: the configuration file can disable this emergency break. ===Special options=== There are a number of options that Iceditch recognises, that are listed below. Note: options cannot be grouped. For example, Iceditch understands ''-d -e'' but not ''-de''.<br> '''-d''' dummy run; prevents Iceditch to actually invoke IPtables at all. Used mainly with ''-e'' or ''-E'', to check a configuration.<br> '''-e''' will make Iceditch echo all generated IPtables commands to the console. This can be useful to test a complex configuration. ''-e'' cannot be combined with ''-E''<br> '''-E''' will make Iceditch echo all rules in Iceditch language. Only useful if your rulefile contains lots of conditional rules, flow control and other programming bling. ''-E'' cannot be combined with ''-e''<br> '''-r <rulefile>''' will make Iceditch use ''<rulefile>'' instead of the default rulefile ''/etc/iceditch/rules.conf''. ''<rulefile>'' can be specified with an absolute path, with a relative path from the current working directory, or without path at all (in which case Iceditch assumes the file lives in ''/etc/iceditch'').<br> '''-t <number>''' can be used only with ''safestart''; it signifies the number of minutes (1-60) that ''safestart'' must wait before it reverts the configuration.<br> '''-v''' verbosity; will make Iceditch send the -v option to all commands it calls itself<br> '''-V''' print the version number and exit (overrides any other option or parameter)<br> ===Logging=== Iceditch logs any (attempted) start or stop action to the syslog. When the Iceditch-built firewall runs, it can make use of the standard IPtables log facilities. These can be either logging packages to syslog, or using the ''ulogd'' logging daemon. This choice can be specified in the Iceditch configuration file, although you have to ensure yourself that ''ulogd'' actually exists on your system. 034429e923c5aab10647ab42add1299f3772a882 0 1449 1546 2008-07-03T20:15:04Z Saruman! 2 Page created wikitext text/x-wiki ==Problems creating a firewall== Creating a firewall is pretty hard work. You'll have to think up all functionality your firewall will have to accomodate, you'll have to translate that functionality into rules that operate on network packets, then translate those rules into IPtables commands, and then you'll have to group all those commands in a script. The script will have to be made executable, must be invoked automatically at boot time, and stored in some logical place. That's not trivial. It requires intimate knowledge and understanding of networking, of IPtables/Netfilter, and some basic knowledge of scripting and linux. And then you need to review, adapt, expound the firewall you're creating, and the complexities you're encountering multiply. ==Problems checking a firewall== After you've created your firewall, you'll have to test it. This might reveal that some packet is getting through that you'd rather not let through, or that some packet is dropped that you'd actually want to receive. Or logging is incomplete, or -just as bad- overcomplete. When this happens, you'll have to find the cause and fix it. But can you easily read the configuration of your firewall? Can your collegue? Can you still read and understand your firewall if the problem occurs five months after you've created it? And what if you suddenly need to log packets that get dropped or accepted - can you easily find the rules that you need to put logging on? ==Problems maintaining a firewall== To maintain a firewall requires you to be able to check it, add new functionality, and remove functionality that's no longer needed. However, since the order in which rules are executed is important, it is entirely possible that adding a set of rules in one place of the firewall, breaks the working of it in another. And the same holds for the removal of rules: * adding a rule that allows certain packets might interfere with rules that log or mark (some of) those packets further down the firewall; * removing a rule that used to block certain packets does not always mean that the packets now arrive successfully - maybe another rule further down the firewall ''also'' blocks (a part of) the packets, or maybe you've not set an "allow" rule for (all of) the packets; * conversely, removing a rule that used to allow certain packets does not always mean that the packets will now get blocked - maybe another rule further down the firewall ''still'' allows (a part of) the packets. In essence, this proves that any single change to the functionality of the firewall requires a re-evaluation of the whole firewall, checking it's programmed working as-of-now to the intended functionality. Furthermore, if you've actually written ''code'' to perform some of your firewalling for you, with conditional statements, with variables and checks, with loops and arrays and whatnot, then you're in even deeper water. What if functionality is required that you haven't coded for: can you easily adapt your code to this new functionality? Have you documented and commented your code? Is it even ''your'' code, or is it from a sloppy collegue? ==Problems when using Netfilter/IPtables== The forementioned problems can quite easily arise when you or your organization create your own firewall scripts using Linux Netfilter/IPtables. These scripts are usually simple shellscripts with many long lines of IPtables invocations, along the lines of <pre> iptables -A FORWARD -i ipsec+ -o $LAN -s 172.30.50.0/24 -d 172.24.9.15 -j LNX iptables -A FORWARD -i $LAN -o ipsec+ -s 172.24.9.15 -d 172.30.50.0/24 -m state --state ESTABLISHED,RELATED -j ACCEPT iptables -A FORWARD -i ipsec+ -o $LAN -s 172.30.50.0/24 -d 172.24.8.0/21 -j SMB_MGMT iptables -A FORWARD -i $LAN -o ipsec+ -s 172.24.8.0/21 -d 172.30.50.0/24 -m state --state ESTABLISHED,RELATED -j ACCEPT iptables -A FORWARD -p tcp -i ipsec+ -o $LAN -s 172.30.50.0/24 -d 172.24.9.1 -m multiport --dport 135,1228,5001,5002,5003,5004 -j ACCEPT iptables -A FORWARD -p tcp -i $LAN -o ipsec+ -s 172.24.9.1 -d 172.30.50.0/24 -m state --state ESTABLISHED,RELATED -j ACCEPT iptables -A FORWARD -i ipsec+ -o $DMZ1 -s 172.30.50.0/24 -d 172.24.16.0/24 -j SMB_MGMT iptables -A FORWARD -i ipsec+ -o $DMZ1 -s 172.30.50.0/24 -d 172.24.16.0/24 -j LNX iptables -A FORWARD -p tcp -i ipsec+ -o $DMZ1 -s 172.30.50.0/24 -d 172.24.16.0/24 --dport 1433 -j ACCEPT iptables -A FORWARD -i ipsec+ -o $DMZ1 -s 172.30.50.0/24 -d 172.24.16.0/24 -m state --state ESTABLISHED,RELATED -j ACCEPT iptables -A FORWARD -i $DMZ1 -o ipsec+ -s 172.24.16.0/24 -d 172.30.50.0/24 -m state --state ESTABLISHED,RELATED -j ACCEPT </pre> It will be clear that reading, editing, maintaining this type of firewall is pretty hard on the brains. * hard to read * hard to code without syntax errors * much much typing (or cutting & pasting) ==Solutions to these problems== Some of the problems mentioned above cannot be fixed for you, just by us providing you with a firewall script. For instance, no matter how good our firewall script is, it'll never give you intimate knowledge and understanding of networking, on which to base your firewall rules. However, a good firewall script can tackle several issues for you: * a good firewall script shows your firewall rules in a very readable form; * a good firewall script offers structure and order; * a good firewall script does not impose undue restrains on your ability to code the firewall, i.e. it should not be hard to code ''anything'' in the script that you could also code with your own homegrown IPtables scripts * a good firewall script saves you coding, i.e. must need less effort to create the firewall you need than it would to create your own IPtables script. a673ca988cc422387f0ec047cc97a4fe917207d1 0 1450 1547 2008-07-05T09:03:13Z Saruman! 2 First filestructure setup wikitext text/x-wiki Iceditch is quite a simple script, so it has only a few files. In a standard Debian environment, you'll find these files: '''/etc/iceditch/rules.conf''' This is the "rulefile", that contains your actual firewall rules (in [[Iceditch IPtables language]]). '''/etc/iceditch/.rules.bak''' This file may or may not exist; it's a backup of the rulefile, made by Iceditch itself when you told it to. '''/etc/iceditch/params.conf''' This is the "parameter file", a file that contains all parameters that Iceditch needs for your firewall. This is also the place where you would stuff your custom functions, so that you could call them from the rulefile when necessary. '''/bin/iceditch''' This is the firewall script itself. It's an executable shellscript. '''/etc/init.d/iceditch''' This is only a symlink to the iceditch script itself. e7d35a88904004fd70e3a3a12d16ade37d1872ec 1548 1547 2008-07-05T09:07:01Z Saruman! 2 edited backup file description wikitext text/x-wiki Iceditch is quite a simple script, so it has only a few files. In a standard Debian environment, you'll find these files: '''/etc/iceditch/rules.conf'''<br> This is the "rulefile", that contains your actual firewall rules (in [[Iceditch IPtables language]]). '''/etc/iceditch/params.conf'''<br> This is the "parameter file", a file that contains all parameters that Iceditch needs for your firewall. This is also the place where you would stuff your custom functions, so that you could call them from the rulefile when necessary. '''/etc/iceditch/.rules.bak'''<br> '''/etc/iceditch/.params.conf'''<br> These files may or may not exist; they're backups of the rulefile and parameter file, made by Iceditch itself when you told it to. These will be the source of the "new" rules and parameters, when Iceditch performs a fallback after a [[Iceditch functionality | safestart]], or when you call [[Iceditch functionality | ''iceditch restore'']]. '''/bin/iceditch'''<br> This is the firewall script itself. It's an executable shellscript. '''/etc/init.d/iceditch'''<br> This is only a symlink to the iceditch script itself. 3d13ac6f14dc04d02f708f350db77753f58a45a0 1549 1548 2008-07-05T09:15:31Z Saruman! 2 added params.conf wikitext text/x-wiki Iceditch is quite a simple script, so it has only a few files. In a standard Debian environment, you'll find these files: '''/etc/iceditch/rules.conf'''<br> This is the "rulefile", that contains your actual firewall rules (in [[Iceditch IPtables language]]). '''/etc/iceditch/config.conf'''<br> This is the "config file", a file that contains all default parameters that Iceditch needs for your firewall, like aliases for your NICs (like ''Inet=eth0''). This is also the place where you would stuff your custom functions, so that you could call them from the rulefile when necessary. '''/etc/iceditch/params.conf'''<br> This is the optional "parameter file", a file that may contain lists of parameters that you would want to read into your firewall. An example would be a list like IPblocked=192.168.1.14 # don't want any traffic to the switch from here IPblocked=216.73.93.8 IPblocked=127.0.0.2 # Blocked on 2008-07-05 for hacking attempts '''/etc/iceditch/.rules.bak''',<br> '''/etc/iceditch/.config.bak''',<br> '''/etc/iceditch/.params.conf'''<br> These three files may or may not exist; they're backups of the rulefile and parameter file, made by Iceditch itself when you told it to. These will be the source of the "new" rules and parameters, when Iceditch performs a fallback after a [[Iceditch functionality | safestart]], or when you call [[Iceditch functionality | ''iceditch restore'']]. '''/bin/iceditch'''<br> This is the firewall script itself. It's an executable shellscript. '''/etc/init.d/iceditch'''<br> This is only a symlink to the iceditch script itself. 9529715022d5a0fcdc45219441a39251fca4af2e 0 1451 1552 2008-07-13T09:26:39Z Insomnia 3 wikitext text/x-wiki == VMware ESX 3.5 == 7cdf8abb0fb5efcdfc984f0708897eec3a376d44 1553 1552 2008-07-13T10:37:23Z Insomnia 3 Project started wikitext text/x-wiki Our goal is to setup a test environment with VMware esx 3.5. * Situation as is * Problems with the current setup * Proposed solutions ** VI3 ** Hardware ** Standarized storage solution * 6297728544fadb9526d11f8f7922bff10aab67f6 1557 1553 2008-07-18T07:28:15Z Insomnia 3 wikitext text/x-wiki Our goal is to setup a test environment with VMware esx 3.5. * '''[[Situation]]''' as is * Problems with the current setup * Proposed solutions ** VI3 ** Hardware ** Standarized storage solution * 2fb2231ef080431e3ebd3adf86eca4a158a16630 1558 1557 2008-07-18T07:28:33Z Insomnia 3 wikitext text/x-wiki Our goal is to setup a test environment with VMware esx 3.5. * '''[[Current Situation|Situation]]''' as is * Problems with the current setup * Proposed solutions ** VI3 ** Hardware ** Standarized storage solution * b7c15ef9287883cddb44bb2429c44e208b7f9096 1562 1558 2008-07-18T14:11:16Z 193.67.158.163 0 wikitext text/x-wiki Our goal is to setup a test environment with VMware esx 3.5. * '''[[Current Situation|Situation]]''' as is * Problems with the current setup * Proposed solutions ** VI3 ** Hardware ** Standarized storage solution * At this moment we have Vmware infrastructure 3.0. we have 2 ESX hosts HP Dl 385 G1 with 16Gb ram. Due to the latest expension we have to many vmware hosts to guerantee High availability. We run out of memory to support all hosts on 1 ESX host. There are a few sollutions: * turn of some vmware hosts when 1 ESX host goes down * Increase the memory * scale out with 1 or 2 hosts Turn off some hosts is a short term sollution Increase the memory is not possible. The Dl 385 can handle no more then 16Gb of memory. Scale out is the prefered solution. dcde75cb0abf0e90ee105c64f029cbebf69d239d 1563 1562 2008-07-19T07:52:46Z Insomnia 3 wikitext text/x-wiki Our goal is to setup a test environment with VMware esx 3.5. * Situation as is * Problems with the current setup * Proposed solutions ** VI3 ** Hardware ** Standarized storage solution * == Current Situation At this moment we have Vmware infrastructure 3.0.1 We have 2 ESX hosts HP Dl 385 G1 with 16Gb ram. Virtual Center 2.0 == Problems == Due to the latest expension we have to many vmware hosts to guarantee High availability. We run out of memory to support all hosts on 1 ESX host. When 1 host goes down due to failure. == Solution == There are a few sollutions: * turn of some vmware hosts when 1 ESX host goes down * Increase the memory * scale out with 1 or 2 hosts Turn off some hosts is a short term sollution Increase the memory is not possible. The Dl 385 can handle no more then 16Gb of memory. Scale out is the prefered solution. b33ba6402817394f1e753c58ce6d12e19c36f629 0 1452 1555 2008-07-14T19:49:23Z Saruman! 2 Documentation project started wikitext text/x-wiki == The Documentation Project== Documentation in ICT projects is a tough cookie (maybe outside of ICT as well, but that's no concern of ours at this moment). What the ICT profession seems to lack is * a thorough understanding of the fundamental problems that surround ICT documentation * taxonomies of the different documentation purposes, target audiences (with their experience levels), and document types * a methodology to create, review and maintain ICT documentation of sufficient quality, against reasonable cost * templates, guidelines and best practices to assist such a methodology * some sort of overview of the different documentation management solutions that exist, ranging from the venerable binders with photocopies and printouts, through fileshares full of text documents, through the anarchistic wiki system, all the way to Enterprise Content Management (ECM) systems with integrated document scanners, archivers, ILM-components and what have you not * an appreciation for the specific skills that are needed in the so-called "technical writers" * an embedded process for documentation in the business processes; if not in projects, then most surely in day-to-day system administration. What we'll attempt to do here is to systematically address all issues surrounding ICT documentation, and develop the lacking taxonomies, methodologies etcetera. bedc8612a25f6d367876f014072ce9ecb178ab5c 12 1420 1556 1453 2008-07-15T07:55:51Z Saruman! 2 added picture link wikitext text/x-wiki If you need some help on editing, the main source of info is [http://meta.wikimedia.org/wiki/Help:Contents here, on the Wikimedia page]. Should you want to use pictures, [http://en.wikipedia.org/wiki/Wikipedia:Picture_tutorial go here]. 5ebf9209975507668f6f45c1b1e7c8cb82c0cafe 0 1451 1564 1563 2008-07-19T07:53:54Z Insomnia 3 wikitext text/x-wiki Our goal is to setup a test environment with VMware esx 3.5. * Situation as is * Problems with the current setup * Proposed solutions ** VI3 ** Hardware ** Standarized storage solution * == Current Situation == At this moment we have Vmware infrastructure 3.0.1 We have 2 ESX hosts HP Dl 385 G1 with 16Gb ram. Virtual Center 2.0 == Problems == Due to the latest expension we have to many vmware hosts to guarantee High availability. We run out of memory to support all hosts on 1 ESX host. When 1 host goes down due to failure. == Solution == There are a few sollutions: * turn of some vmware hosts when 1 ESX host goes down * Increase the memory * scale out with 1 or 2 hosts Turn off some hosts is a short term sollution Increase the memory is not possible. The Dl 385 can handle no more then 16Gb of memory. Scale out is the prefered solution. 33b957776d9d16f0dc21b1575cc341711f72d638 0 1442 1565 1554 2008-07-19T15:44:38Z Saruman! 2 added config example wikitext text/x-wiki ==Firewalling under Linux== You may not have realised it, but Linux comes with an incredible powerful and flexible [http://searchnetworking.techtarget.com/sDefinition/0,,sid7_gci214173,00.html TCP/IP] [http://www.tech-faq.com/firewall.shtml packet filtering firewall], named [http://www.netfilter.org/ Netfilter]. With a minimum amount of effort, we can create just about any packet filter you can imagine. The Linux solution is so powerful, even commercial firewall vendors like [http://www.watchguard.com/ Watchguard] use it in their products. In fact, Watchguard has paid the main developer early on in the project (see [http://www.netfilter.org/about.html here]). However, to create a truly magnificent firewall, there are many problems to overcome; we'll discuss them in this section:<br> '''[[Firewall problems | Generic discussion on firewall problems]]'''. Fortunately for YOU, my friend, the SaruWiki admin team have created their own "solution" to these problems: the Iceditch firewall script. By consistent focus on a small set of '''[[Iceditch design targets | sensible design targets]]''', we feel we've succeeded in creating a firewall script that alleviates most of the many problems firewalls face. Our Iceditch solution has the following elements and properties: * Iceditch defines a '''[[Iceditch IPtables language | "language"]]''' to more easily read & write IPtables commands; this mainly solves the problems of auditability (partly) and eases maintainability, although it does not by itself solve the problem of documentation. * It offers '''[[Iceditch functionality | much functionality]]''', like ** a standardised way to start the firewall at boot time, ** ways to audit the firewall, both while it's running and when you've edited (but not yet implemented) it, ** a reasonably failsafe way to change firewall settings from afar. * Iceditch is based on a single Bash script and some configuration files, and thus has a fairly simple '''[[Iceditch file structure | file structure]]'''. * For full reference, we've created this '''[[Iceditch Command Reference]]'''. * Here is an [[Iceditch configuration example]] Now, obviously there are many more firewalls to choose from, ranging from advanced [http://www.shorewall.net/ | configure-it-yourself firewall] to [http://www.smoothwall.org/ pret-a-porter OS-and-firewall-into-one] solutions (and we're not even starting on proprietary solutions, be they hardware and/or software). The main reason for us to create our own firewall script (besides the obvious reasons of fun and learning) is [[Iceditch design targets | flexibility]]. Should you be in any way interested in this project of ours, feel free to [mailto:iceditch@saruman.biz contact us]. d015ad5dfdf9c258d144f005ffa2e40a75d35a4f 0 1454 1566 2008-07-19T16:01:00Z Saruman! 2 Iceditch example config wikitext text/x-wiki ==File ''config.conf''== <pre> ## PUT YOUR OWN ADDRESS HERE! if you want to receive errors by mail MAILTO="linuxwarning@saruman.biz"; CMD="/sbin/iptables"; SYSLOG="/usr/bin/logger"; # if you want to use the Userspace Logging Daemon, change this # from "LOG" to "ULOG" FWLOG="ULOG"; # default "--log-prefix" or "--ulog-prefix" FWLOGPREFIX="--ulog-prefix"; # topology inetIF='eth1'; inetIP='212.238.151.172'; lanIF='eth0'; lanIP='192.168.67.10'; lanNET='192.168.67.0/24'; natIF=$inetIF; natIP=$inetIP; # Define some subnets FRESHFIELDNET='192.168.67.144/28' # Limited hosts: 144 t/m 159 JANNET='192.168.67.160/27' # Limited hosts: 160 t/m 191 SASNET='192.168.67.192/26' # Limited hosts: 192 t/m 254 ################################################################################ ## Here you can declare and/or read every variable you'll need in the rules ## ################################################################################ # Fetch all IP's that are totally blocked lookup_param_list 'blockedIP' "/etc/iceditch/params.conf"; NumOfBlockedIPs=${r[0]}; if [ $NumOfBlockedIPs -gt 0 ]; then i=0; while [ $i -le $NumOfBlockedIPs ] ; do blockedIP[$i]=${r[$i]}; let "i += 1"; done; fi; # Fetch all IPsec tunnel parameters lookup_param_list 'IPsecLocalLAN' "/etc/iceditch/params.conf"; IPsecNumOfTunnels=${r[0]}; if [ $IPsecNumOfTunnels -gt 0 ]; then i=0; while [ $i -lt $IPsecNumOfTunnels ] ; do let "i += 1"; IPsecLocalLAN[$i]=${r[$i]}; IPsecLocalLANIP[$i]=$lanIP; # we don't read these from the config IPsecLocalWANIP[$i]=$inetIP; # file, since they're always the same done; lookup_param_list 'IPsecRemoteWANIP' "$PATHNAME/$PARMFILENAME"; i=0; while [ $i -lt $IPsecNumOfTunnels ] ; do let "i += 1"; IPsecRemoteWANIP[$i]=${r[$i]}; done; lookup_param_list 'IPsecRemoteLAN' "$PATHNAME/$PARMFILENAME"; i=0; while [ $i -lt $IPsecNumOfTunnels ] ; do let "i += 1"; IPsecRemoteLAN[$i]=${r[$i]}; done; fi; </pre> ==File ''params.conf''== <pre> blockedIP = 62.27.41.69 = 20060529 - adware webserver blockedIP = 195.56.146.210 = 20060805 - forum.joomla.hu blockedIP = 82.201.220.60 = 20070918 - messes on udp500 blockedIP = 80.73.129.193 = 20080127 - lots of NewNotSyns IPsecRemoteNET = 'Odeon.lan' = descriptive name of the IPtunnel destination IPsecLocalLanIP = $lanIP = the local IP address of the router IPsecLocalLAN = $lanNET = the LAN segment we're prepared to open IPsecLocalWANIP = $inetIP = Our own external IP for this connection IPsecRemoteLAN = '192.168.70.0/24' = the remote LAN segment we wanna reach IPsecRemoteWANIP = '82.161.20.132' = the public IP of the remote gateway </pre> ==File ''rules.conf''== <pre> ###################################################################### ### ### ### 1.1 PRE_ROUTING mangle ### ### ### ### use case: mark incoming packets for (outgoing) traffic control ### ### ### ###################################################################### context "PREROUTING" "mangle" # Mark incoming ESP packets with mark "1" let "i=0"; while [[ $i -lt $IPsecNumOfTunnels ]]; do let "i += 1"; mark 1 -p esp -s ${IPsecRemoteWANIP[$i]} -d ${IPsecLocalWANIP[$i]}; done; # default policy: accept ###################################################################### ### ### ### 1.2 PRE_ROUTING nat ### ### ### ### use cases: ### ### - DNAT (incoming connects to private ip's, e.g. DMZ or svr) ### ### - REDIRECT (machine port redirects / transparant proxy) ### ### ### ###################################################################### context "PREROUTING" "nat" # let IPsec traffic bypass any SNATting let "i=0" while [[ $i -lt $IPsecNumOfTunnels ]]; do let "i += 1" accept -s ${IPsecRemoteLAN[$i]} -d ${IPsecLocalLAN[$i]} done # also accept all traffic marked "1" which is # incoming ESP traffic from trusted remote IP's # SHOULD already be handled by the default policy accept -m mark --mark 1 # make Squid our transparent proxy dnat to ${lanIP}:3128 -p tcp -i $lanIF --dport 80 # default policy: accept ###################################################################### ### ### ### 2.1 FORWARD mangle ### ### ### ### use case: none ### ### ### ###################################################################### context "FORWARD" "mangle" # default policy: accept ###################################################################### ### ### ### 2.2 FORWARD filter ### ### ### ### use case: filter traffic forwarded between networks ### ### ### ### ATTENTION please: choose an appropriate forwarding policy ### ### o no forwarding: 0 > ip_forward ### ### o untrusted forwarding: filter ports + egress ip ### ### o trusted forwarding: filter only egress ip ### ### ### ###################################################################### context "FORWARD" "filter" # upfront blocking of all banned IP's let "j = 0"; while [[ $j -lt ${blockedIP[0]} ]]; do let "j += 1"; drop -s ${blockedIP[$j]}; drop log msg Banned_IP_$j -d ${blockedIP[$j]}; done # drop some nasty P2P calls reject with host-prohib -p tcp --dport 13830 # Connection tracking for forwarding accept -m state --state ESTABLISHED,RELATED # drop new-not-syn drop log msg FORWARD_NewNotSYN -p tcp ! --syn -m state --state NEW # let IPsec traffic through let "i=0" while [[ $i -lt $IPsecNumOfTunnels ]]; do let "i += 1" drop -s $FRESHFIELDNET -d ${IPsecRemoteLAN[$i]} # Freshfieldnet has no business in the tunnels accept -s ${IPsecLocalLAN[$i]} -d ${IPsecRemoteLAN[$i]} accept -s ${IPsecRemoteLAN[$i]} -d ${IPsecLocalLAN[$i]} done # Allow Yodi's mail (pop3.zonnet.nl + mail.descartes.nl + wissit.com/mail.wissit.nl) accept -p tcp -d 62.58.50.236 --dport 110 accept -p tcp -d 213.196.12.29 --dport 110 accept -p tcp -d 194.121.181.250 --dport 25 # Allow MPPE-traffic from inside to outside accept -p 47 # Specifically block certain ports out to the Internet # Mainly mail, DNS and NTP drop -p tcp -m multiport --dport 25,53,110,123 drop -p udp -m multiport --dport 53,123 # Generic TCP traffic allowed out to the Internet: everything else # note: return traffic is handled by connection tracking accept -p tcp -s $lanNET accept -p udp -s $lanNET # Allowing full ICMP between inside and outside accept -p icmp -s $lanNET # default policy: drop ###################################################################### ### ### ### 3.2 INPUT filter ### ### ### ### use case: filter incoming traffic directed at machine host ### ### ### ###################################################################### context "INPUT" "filter" # upfront blocking of all banned IP's let "j = 0"; while [[ $j -lt ${blockedIP[0]} ]]; do let "j += 1"; drop -s ${blockedIP[$j]} done # Spoofed IP protect # a bit superfluous, since rp_filter (Source Address Verification) can # be turned on in /proc/sys... # drop log msg Local_IP_from_Inet_192 -i $inetIF -s 192.168.0.0/16 # drop log msg Local_IP_from_Inet_10 -i $inetIF -s 10.0.0.0/8 # drop log msg Local_IP_from_Inet_172 -i $inetIF -s 172.16.0.0/12 # drop some nasty P2P calls reject with host-prohib -p tcp --dport 13830 # drop new-not-syn drop log msg INPUT_NewNotSYN -p tcp ! --syn -m state --state NEW # Connection tracking for incoming traffic accept -m state --state ESTABLISHED,RELATED # Drop different attacks: # Xmas scan drop log msg Xmas_scan -i $inetIF -p tcp --tcp-flags ALL FIN,URG,PSH drop log msg Xmas_scan -i $inetIF -p tcp --tcp-flags ALL ALL # Stealth scan drop log msg Stealth_scan -i $inetIF -p tcp --tcp-flags SYN,ACK,FIN,RST RST drop log msg Stealth_scan -i $inetIF -p tcp --tcp-flags ALL SYN,RST,ACK,FIN,URG drop log msg Stealth_scan -i $inetIF -p tcp --tcp-flags ALL NONE # SYN,RST scan drop log msg SYN/RST_scan -i $inetIF -p tcp --tcp-flags SYN,RST SYN,RST # SYN,FIN scan drop log msg SYN/FIN_scan -i $inetIF -p tcp --tcp-flags SYN,FIN SYN,FIN # drop SSH connections if they're spurious (more than 2 attempts per minute) nojump -p tcp --dport 22 -i $inetIF -m state --state NEW -m recent --name SSHERS --set drop -p tcp --dport 22 -i $inetIF -m state --state NEW -m recent --name SSHERS --update --seconds 60 --hitcount 3 # accept SSH from all sides accept -p tcp --dport 22 # accept IKE traffic from everyone including NAT-T accept -p udp --sport 500 --dport 500 accept -p udp --sport 4500 --dport 4500 # accept ESP traffic from everyone # accept -p esp # accept all traffic marked "1", which is # incoming ESP traffic from trusted remote IP's accept -m mark --mark 1 # accept MPPTP to this machine from the Internet accept -p tcp --dport 1723 # accept -i $inetIF -p 47 accept -p 47 # This might be needed for 2 simultaneous connections to a local PPTP server?? #accept -i ppp0 #accept -o ppp0 #accept -i ppp1 #accept -o ppp1 # accepting ICMP traffic from the inside accept -i $lanIF -p icmp; # accepting ICMP traffic from the Internet side accept -i $inetIF -p icmp #accept -i $inetIF -p icmp --icmp-type echo-request; #accept -i $inetIF -p icmp --icmp-type ttl-exceeded; #accept -i $inetIF -p icmp --icmp-type destination-unreachable; # Generic TCP traffic from the LAN to this machine # 20 = FTP 135 = DCE Endpoint Resolution # 21 = FTP 137 = NetBIOS Name Service # 22 = SSH 138 = NetBIOS Datagram Service # 25 = SMTP 139 = NetBIOS Session Service # 53 = DNS # 80 = HTTP # 110 = POP3 accept -p tcp -i $lanIF -m multiport --dport 20,21,22,25,53,80,110,135,137,138,139 # 143 = IMAP 993 = IMAP4 over TLS # 443 = HTTPS 995 = POP3 over TLS # 445 = CIFS 3128 = Squid access # 631 = CUPSadmin 3306 = MySQL port # 901 = SWAT accept -p tcp -i $lanIF -m multiport --dport 143,443,445,631,901,993,995,3128,3306 # Generic TCP traffic from the Internet to this machine # 25 = SMTP 443 = HTTPS # 53 = DNS 993 = IMAP4 over TLS # 80 = HTTP 995 = POP3 over TLS # 110 = POP3 # 143 = IMAP accept -p tcp -i $inetIF -m multiport --dport 25,53,80,110,143,443,993,995 # Generic UDP traffic from the LAN to this machine # 53 = DNS 137 = NetBIOS Name Service # 123 = NTP 138 = NetBIOS Datagram Service # 139 = NetBIOS Session Service accept -p udp -i $lanIF -m multiport --dport 53,123,137,138,139 # Generic UDP traffic from the Internet to this machine # 53 = DNS 123 = NTP accept -p udp -i $inetIF -m multiport --dport 53,123 accept -p udp -i $inetIF -m multiport --sport 53,123 # default policy: drop ###################################################################### ### ### ### 4.1 OUTPUT mangle ### ### ### ### use case: mark locally generated traffic for traffic control ### ### ### ###################################################################### context "OUTPUT" "mangle" # Mark all outgoing ESP packets to trusted IP's with mark "2" let "i=0" while [[ $i -lt $IPsecNumOfTunnels ]]; do let "i += 1" mark 2 -p esp -d ${IPsecRemoteWANIP[$i]} done # default policy: accept ###################################################################### ### ### ### 4.2 OUTPUT nat ### ### ### ### use cases: ### ### - DNAT locally generated traffic (e.g. tunnel encapsulation) ### ### - REDIRECT port redirects (???) ### ### ### ###################################################################### context "OUTPUT" "nat" # accept trusted outgoing ESP packages, which are marked "2" # only needed if we need to bypass some NAT rules # accept -m mark --mark 2 # default policy: accept ###################################################################### ### ### ### 4.3 OUTPUT filter ### ### ### ### use case: filter locally generated traffic ### ### ### ###################################################################### context "OUTPUT" "filter" # upfront blocking of all banned IP's let "j = 0"; while [[ $j -lt ${blockedIP[0]} ]]; do let "j += 1" drop log msg Banned_IP_$j -d ${blockedIP[$j]} done # accept trusted outgoing ESP packages, which are marked "2" accept -m mark --mark 2 # assume ALL traffic from the server to the LAN is safe accept -p tcp -o $lanIF accept -p udp -o $lanIF # for convenience, let's for now assume all traffic from # the server to the Internet is safe as well.... accept -p tcp -o $inetIF accept -p udp -o $inetIF accept -p 47 accept -p icmp accept log msg odeon_output -p tcp -d 192.168.70.0/24 accept log msg odeon_output -p udp -d 192.168.70.0/24 # default policy: drop ###################################################################### ### ### ### 5.1 POSTROUTING mangle ### ### ### ### use case: set TOS on outgoing packets to guide other routers ### ### ### ###################################################################### context "POSTROUTING" "mangle" classify 1:11 -s $JANNET -d ! $lanNET classify 2:11 -d $JANNET -s ! $lanNET classify 1:12 -s $FRESHFIELDNET -d ! $lanNET classify 2:12 -d $FRESHFIELDNET -s ! $lanNET classify 2:99 -s $lanNET -d $lanNET # default policy: accept ###################################################################### ### ### ### 5.2 POSTROUTING nat ### ### ### ### use cases ### ### - SNAT hide LAN ip range behind public ip façade ### ### - MASQUERADE on dynamic ip dialup interface only ### ### ### ###################################################################### context "POSTROUTING" "nat" # let trusted IPsec traffic bypass the NATting let "i=0" while [[ $i -lt $IPsecNumOfTunnels ]]; do let "i += 1" accept -s ${IPsecLocalLAN[$i]} -d ${IPsecRemoteLAN[$i]} done # and accept trusted outgoing ESP packages, which are marked "2", # which also need to bypass the NATting accept -m mark --mark 2 # This machine is a NAT router, so sourcenat over the designated # NAT interface using the designated NAT IP address, EXCEPT for # traffic that originates from the machine itself snat to $natIP -o $natIF ! --src $natIP # default policy: accept </pre> 7604f8e1a7275435d3943e00feac10cc61b5c9db 0 1 1567 1520 2008-07-19T19:08:24Z Saruman! 2 added X11 wikitext text/x-wiki <big>'''Welcome to SaruWiki.'''</big> This Wiki is intended to document bits and bobs about [http://www.kernel.org/ Linux] (and some Unix) in general, and [http://www.debian.org Debian] in particular. In it, [[SaruTeam|we]] wish to collect the tips and tricks of both [[SaruTeam|our own team of Linux admins]] and those of other interested users. Consult the [http://meta.wikimedia.org/wiki/Help:Contents User's Guide] for information on using this wiki's software. ---- <big>'''Main Content'''</big> * Setting up a [[Debian Etch base server]] is a howto on the installation of a very basic Linux box under Etch (it's actually not even a server yet). * The use of [[APT and aptitude]] is crucial to the concept of a Debian machine. * [[Roll your own kernel]] discusses the pros and cons of compiling your own kernel, and how to do it. * [[Essential system software]] lists all (sets of) packages that we deem, well, essential. * [[Add an X11 server]] to your server, if you need one * The [[system boot procedure]] section explains what we can customise in the standard ways Debian boots. * The [[networking section]] treats subjects like setting persistent routes. * The [[firewall section]] is where we discuss "IPtables" (netfilter) and how we use it for firewalling. * The [[native IPsec tunnel]] section describes how to configure an IPsec tunnel. * Using ''md'' for [[software RAID]] contains our ideas and observations on redundancy. * [[Hardware monitoring]] is important for your server's health and reliability. * [[Database 101]] introduces you to MySQL. * [[Vmware_server|VMware Server basics]] gives some pointers on how to install VMware Server on a Debian server box. * Make your server a [[Microsoft PPTP server | Microsoft client compatible VPN Server ]]. * How to install [[Mediawiki Installation | Mediawiki]] on your Debian server - like what you're looking at now. ---- '''Note''': the Wiki admins reserve the right to edit or remove any content they feel is not suitable for this site, not relevant, (too) inaccurate or otherwise not in line with the intentions and spirit of the admin team. ---- <websiteFrame> website=http://www.google.com/talk/service/badge/Show?tk&#61;z01q6amlqld8jocej2ca891jl9dunqqra83nhehaoqpednb5skkur0fv70jsuavce4ii9ms5e9afdr8qmpsc1d9upni4jom8g1em3p1cvq1p5eo1ugv162fosgprdv867iuememlcogfle8n3dmcf97durjld85avnh8k5lm1&amp;w=200&amp;h=60 border=0 height=60 width=200 name=GoogleChatwithSaruman! allowtransparency=true </websiteFrame> 3bab4a9163f5593da3a03a4776025acaad42fc93 0 1455 1568 2008-07-19T19:20:58Z Saruman! 2 Page started wikitext text/x-wiki First update your apt using apt-get update Now run tasksel Under Choose software to install, remove all asterisks except for "desktop environment". When you select ''OK'' the system gets going. That's it! aebf193f6e253e8a6c8f0640cd92f5103cf6109a 1569 1568 2008-07-19T19:37:14Z Saruman! 2 added userspace sw suspend wikitext text/x-wiki First make sure that your kernel supports "userspace software suspend". If it doesn't (as might be with a homegrown kernel), then reconfigure your kernel to include CONFIG_SOFTWARE_SUSPEND=Y, recompile, reboot. Now, you can update your apt using apt-get update Now run tasksel Under Choose software to install, remove all asterisks except for "desktop environment". When you select ''OK'' the system gets going. That's it! 0c6b6e56e376b86234dc520c75f7b6dc6ae38285 1570 1569 2008-07-19T20:06:10Z Saruman! 2 ... continuing wikitext text/x-wiki First make sure that your kernel supports "userspace software suspend". If it doesn't (as might be with a homegrown kernel), then reconfigure your kernel to include CONFIG_SOFTWARE_SUSPEND=Y, recompile, reboot. Now, you can update your apt using apt-get update Now run tasksel Under Choose software to install, remove all asterisks except for "desktop environment". When you select ''OK'' the system gets going. After installing a LOT of software, Tasksel will ask you what you want your default resolutions to be. Select at least those that you want to be able to use. Then Tasksel installs and configures some more. That's it! 39797ec0dfbb8d0d1bf3ac7a1b7c7f1106c84d8a 1571 1570 2008-07-19T22:01:45Z Saruman! 2 added removal of automatic X starting wikitext text/x-wiki First make sure that your kernel supports "userspace software suspend". If it doesn't (as might be with a homegrown kernel), then reconfigure your kernel to include CONFIG_SOFTWARE_SUSPEND=Y, recompile, reboot. Now, log into the real console of your server. If you use a terminal, the setup of X will "hang" at the end. You can update your apt using apt-get update Now run tasksel Under Choose software to install, remove all asterisks except for "desktop environment". When you select ''OK'' the system gets going. After installing a LOT of software, Tasksel will ask you what you want your default resolutions to be. Select at least those that you want to be able to use. Then Tasksel installs and configures some more. However, since this will make your server start up with a GUI, we now take out the graphic desktop manager with update-rc.d -f gdm remove This means that you still boot into the text mode console. So how do we then get that graphic desktop (should we ever need it)? Simply by issuing startx at the root prompt on the real console. That's it! 9def3ac5e02cbfbb63540c16b71a15649888fac8 1587 1571 2008-07-29T21:30:06Z 192.168.67.181 0 added X to Windows wikitext text/x-wiki First make sure that your kernel supports "userspace software suspend". If it doesn't (as might be with a homegrown kernel), then reconfigure your kernel to include CONFIG_SOFTWARE_SUSPEND=Y, recompile, reboot. Now, log into the real console of your server. If you use a terminal, the setup of X will "hang" at the end. You can update your apt using apt-get update Now run tasksel Under Choose software to install, remove all asterisks except for "desktop environment". When you select ''OK'' the system gets going. After installing a LOT of software, Tasksel will ask you what you want your default resolutions to be. Select at least those that you want to be able to use. Then Tasksel installs and configures some more. However, since this will make your server start up with a GUI, we now take out the graphic desktop manager with update-rc.d -f gdm remove This means that you still boot into the text mode console. So how do we then get that graphic desktop (should we ever need it)? Simply by issuing startx at the root prompt on the real console. That's it! ==Use X programs on a Windows client== [http://www.linux-tip.net/cms/content/view/302/26/ Here] is a very instructive explanation. In short:<br> * Install Xming. Create a local Xming server that runs on display 10. Start it; your tooltip should say "Xming server:10.0" * Install PuTTy, if you don't have already. * For the PuTTy session to your Debian machine where you want to run X programs: enable X11 forwarding, with an X display location of "localhost:10" or something alike, and MIT-Magic-Cookie-1 as X11 authentication protocol * On your [[OpenSSH server]], enable the option "AllowX11Forwarding yes"; restart your SSH daemon * in your user's profile, put the setting "export DISPLAY=localhost:10.0" * log out, log on again * start xclock or xeyes, and see the program appear on your windows host. Better yet, start the program in the background (''xclock &'') to get it on your windows machine AND be able to continue to work at the commandline 6fb309a65ec18425ffd6990dc47b3acd66ece5a3 1589 1587 2008-07-30T20:06:42Z Saruman! 2 added dpkg-reconfigure wikitext text/x-wiki First make sure that your kernel supports "userspace software suspend". If it doesn't (as might be with a homegrown kernel), then reconfigure your kernel to include CONFIG_SOFTWARE_SUSPEND=Y, recompile, reboot. Now, log into the real console of your server. If you use a terminal, the setup of X will "hang" at the end. You can update your apt using apt-get update Now run tasksel Under Choose software to install, remove all asterisks except for "desktop environment". When you select ''OK'' the system gets going. After installing a LOT of software, Tasksel will ask you what you want your default resolutions to be. Select at least those that you want to be able to use. Then Tasksel installs and configures some more. However, since this will make your server start up with a GUI, we now take out the graphic desktop manager with update-rc.d -f gdm remove This means that you still boot into the text mode console. So how do we then get that graphic desktop (should we ever need it)? Simply by issuing startx at the root prompt on the real console. That's it! ==Use X programs on a Windows client== [http://www.linux-tip.net/cms/content/view/302/26/ Here] is a very instructive explanation. In short:<br> * Install Xming. Create a local Xming server that runs on display 10. Start it; your tooltip should say "Xming server:10.0" * Install PuTTy, if you don't have already. * For the PuTTy session to your Debian machine where you want to run X programs: enable X11 forwarding, with an X display location of "localhost:10" or something alike, and MIT-Magic-Cookie-1 as X11 authentication protocol * On your [[OpenSSH server]], enable the option "AllowX11Forwarding yes"; restart your SSH daemon * On your server, enable use of X11 for all users by running <pre>dpkg-reconfigure x11-common</pre>; this presents you with the question which users are allowed to start the X server. The Debian (safe!) default is "Console Users Only"; change this to "Anybody". * in your user's profile, put the setting "export DISPLAY=localhost:10.0" * log out, log on again * start xclock or xeyes, and see the program appear on your windows host. Better yet, start the program in the background (''xclock &'') to get it on your windows machine AND be able to continue to work at the commandline 01ad2d33afa8f6c1a84863b156dfd609ba0d7a89 1590 1589 2008-07-30T20:08:16Z Saruman! 2 and added x11-common priority wikitext text/x-wiki First make sure that your kernel supports "userspace software suspend". If it doesn't (as might be with a homegrown kernel), then reconfigure your kernel to include CONFIG_SOFTWARE_SUSPEND=Y, recompile, reboot. Now, log into the real console of your server. If you use a terminal, the setup of X will "hang" at the end. You can update your apt using apt-get update Now run tasksel Under Choose software to install, remove all asterisks except for "desktop environment". When you select ''OK'' the system gets going. After installing a LOT of software, Tasksel will ask you what you want your default resolutions to be. Select at least those that you want to be able to use. Then Tasksel installs and configures some more. However, since this will make your server start up with a GUI, we now take out the graphic desktop manager with update-rc.d -f gdm remove This means that you still boot into the text mode console. So how do we then get that graphic desktop (should we ever need it)? Simply by issuing startx at the root prompt on the real console. That's it! ==Use X programs on a Windows client== [http://www.linux-tip.net/cms/content/view/302/26/ Here] is a very instructive explanation. In short:<br> * Install Xming. Create a local Xming server that runs on display 10. Start it; your tooltip should say "Xming server:10.0" * Install PuTTy, if you don't have already. * For the PuTTy session to your Debian machine where you want to run X programs: enable X11 forwarding, with an X display location of "localhost:10" or something alike, and MIT-Magic-Cookie-1 as X11 authentication protocol * On your [[OpenSSH server]], enable the option "AllowX11Forwarding yes"; restart your SSH daemon * On your server, enable use of X11 for all users by running <pre>dpkg-reconfigure x11-common</pre>This presents you with the question which users are allowed to start the X server. The Debian (safe!) default is "Console Users Only"; change this to "Anybody". For the next question about "priority", you can keep the default value of zero. * in your user's profile, put the setting "export DISPLAY=localhost:10.0" * log out, log on again * start xclock or xeyes, and see the program appear on your windows host. Better yet, start the program in the background (''xclock &'') to get it on your windows machine AND be able to continue to work at the commandline 7c7ddcd248116b5f63b1659980317f9d05118f32 0 1433 1573 1561 2008-07-23T20:51:37Z Insomnia 3 added modem page wikitext text/x-wiki ==Asterisk Project page== This describes the project plan for our Asterisk implementation # obtain [http://www.oreilly.com/catalog/9780596510480/ Asterisk book (2nd edition)] => Jan # research [[modem/ISDN hardware]] support => Henri # research [http://www.asteriskguru.com/tools/bandwidth_calculator.php/ bandwidth requirements] => Henri # research QoS necessity/possibility => Jan Links: [http://www.voip-wiki.nl/doku.php?id=xs4all] and [http://www.xs4all.nl/helpdesk/bellen/anders.php] # research Digium support/value-for-money => Jan # research difference Debian Etch vs. stable Asterisk source files => Jan # research features between Asterisk and SIP phone (SNOM320) # Plan Asterisk configurations for Darktower & Oberon ## hardware inclusion (Digium? ISDN/modem? SIP phone?) ## VoIP numbers to order with [http://www.xs4all.nl/allediensten/bellen/faq.php XS4all] <big>GO/NO-GO POINT</big> # Order Digium card, SIP phones => Jan # Install basic Asterisk software # Configure firewall fb659c7dfce5ac6fde785baa9c9907324c327626 1574 1573 2008-07-23T20:52:46Z Insomnia 3 wikitext text/x-wiki ==Asterisk Project page== This describes the project plan for our Asterisk implementation # obtain [http://www.oreilly.com/catalog/9780596510480/ Asterisk book (2nd edition)] => Jan # research [[Hardware | modem/ISDN hardware]] support => Henri # research [http://www.asteriskguru.com/tools/bandwidth_calculator.php/ bandwidth requirements] => Henri # research QoS necessity/possibility => Jan Links: [http://www.voip-wiki.nl/doku.php?id=xs4all] and [http://www.xs4all.nl/helpdesk/bellen/anders.php] # research Digium support/value-for-money => Jan # research difference Debian Etch vs. stable Asterisk source files => Jan # research features between Asterisk and SIP phone (SNOM320) # Plan Asterisk configurations for Darktower & Oberon ## hardware inclusion (Digium? ISDN/modem? SIP phone?) ## VoIP numbers to order with [http://www.xs4all.nl/allediensten/bellen/faq.php XS4all] <big>GO/NO-GO POINT</big> # Order Digium card, SIP phones => Jan # Install basic Asterisk software # Configure firewall 2971f26fb83f5b99e4e8ba6ddfdb4a8967f21cc9 1584 1574 2008-07-27T15:39:03Z Saruman! 2 link added wikitext text/x-wiki ==Asterisk Project page== This describes the project plan for our Asterisk implementation # obtain [http://www.oreilly.com/catalog/9780596510480/ Asterisk book (2nd edition)] => Jan # research [[Hardware | modem/ISDN hardware]] support => Henri # research [http://www.asteriskguru.com/tools/bandwidth_calculator.php/ bandwidth requirements] => Henri # research QoS necessity/possibility => Jan Links: * [http://www.voip-wiki.nl/doku.php?id=xs4all XS4all Asterisk info] * [http://www.xs4all.nl/helpdesk/bellen/anders.php XS4all Bellen Anders] * [http://www.asteriskguru.com/ Asterisk Guru] # research Digium support/value-for-money => Jan # research difference Debian Etch vs. stable Asterisk source files => Jan # research features between Asterisk and SIP phone (SNOM320) # Plan Asterisk configurations for Darktower & Oberon ## hardware inclusion (Digium? ISDN/modem? SIP phone?) ## VoIP numbers to order with [http://www.xs4all.nl/allediensten/bellen/faq.php XS4all] <big>GO/NO-GO POINT</big> # Order Digium card, SIP phones => Jan # Install basic Asterisk software # Configure firewall 46aa0426864ca243246ce0dab2a67e9ede083168 1585 1584 2008-07-27T16:35:56Z Saruman! 2 added instllations page wikitext text/x-wiki ==Asterisk Project page== This describes the project plan for our Asterisk implementation # obtain [http://www.oreilly.com/catalog/9780596510480/ Asterisk book (2nd edition)] => Jan # research [[Hardware | modem/ISDN hardware]] support => Henri # research [http://www.asteriskguru.com/tools/bandwidth_calculator.php/ bandwidth requirements] => Henri # research QoS necessity/possibility => Jan Links: * [http://www.voip-wiki.nl/doku.php?id=xs4all XS4all Asterisk info] * [http://www.xs4all.nl/helpdesk/bellen/anders.php XS4all Bellen Anders] * [http://www.asteriskguru.com/ Asterisk Guru] # research Digium support/value-for-money => Jan # research difference Debian Etch vs. stable Asterisk source files => Jan # research features between Asterisk and SIP phone (SNOM320) # Plan Asterisk configurations for Darktower & Oberon, a.o. via test [[Asterisk Installation on Lenny | installations]] ## hardware inclusion (Digium? ISDN/modem? SIP phone?) ## VoIP numbers to order with [http://www.xs4all.nl/allediensten/bellen/faq.php XS4all] <big>GO/NO-GO POINT</big> # Order Digium card, SIP phones => Jan # Install basic Asterisk software # Configure firewall c5ec79fa3b925d7ed0e31e5aaedf6faffd021040 0 1456 1575 2008-07-23T20:53:54Z Insomnia 3 Page started wikitext text/x-wiki The following modem chipsets would work with Asterisk Intel 537PG and 537PU Ambient MD3200 Motorola 62802 03478aaa256735b446e95c4a6a7361029712f4fb 1576 1575 2008-07-24T09:19:55Z Saruman! 2 layout wikitext text/x-wiki The following modem chipsets would work with Asterisk: * ''Intel'' 537PG and 537PU * ''Ambient'' MD3200 * ''Motorola'' 62802 32ddc3d93422251f12e24e2bbe055bd5c32d105a 1577 1576 2008-07-25T06:32:44Z 193.67.158.163 0 PoE wikitext text/x-wiki The following modem chipsets would work with Asterisk: * ''Intel'' 537PG and 537PU * ''Ambient'' MD3200 * ''Motorola'' 62802 To give power over ethernet use the following schema 1 TX+ 2 TX- 3 RX+ 4 DC- 5 DC- 6 RX- 7 DC+ 8 DC+ 3a15b2a20a3c579a67a706bac0f0af9e168b586c 1578 1577 2008-07-25T06:52:04Z Insomnia 3 wikitext text/x-wiki The following modem chipsets would work with Asterisk: * ''Intel'' 537PG and 537PU * ''Ambient'' MD3200 * ''Motorola'' 62802 To give power over ethernet use the following schema 1 TX+ 2 TX- 3 RX+ 4 DC- 5 DC- 6 RX- 7 DC+ 8 DC+ Give pair 4 and 5 a gound current and give pair 7,8 a plus current b592ac96df62ea633938813ed2d966d2774a70f2 1579 1578 2008-07-25T06:58:53Z Insomnia 3 wikitext text/x-wiki The following modem chipsets would work with Asterisk: * ''Intel'' 537PG and 537PU * ''Ambient'' MD3200 * ''Motorola'' 62802 To give power over ethernet use the following schema 1 TX+ 2 TX- 3 RX+ 4 DC- 5 DC- 6 RX- 7 DC+ 8 DC+ Give pair 4 and 5 a negative current and give pair 7,8 a positive current. Usually the current is 48V 2d746a11b19dbce5c962a22439e1da7e80a752db 0 1448 1580 1545 2008-07-25T18:28:16Z Saruman! 2 halt command cleared up wikitext text/x-wiki This page describes the functions that the Iceditch script can perform for you. ===Rights and security=== Since Iceditch calls IPtables, you need root rights to call it. We therefor have not implemented any mechanism to use Iceditch as a non-root user. ===Invoking Iceditch=== '''iceditch start | restart | reload'''<br> The most common invocation will be the automatic startup at boot time. To this end, the script understands being called with only the "start" parameter. ''iceditch start'' will setup the firewall quietly and completely.<br> '''iceditch stop | unload'''<br> We don't want anyone person or process to be able to ''stop'' the firewall, so this command is accepted, but does nothing except log the attempt.<br> '''iceditch clear'''<br> This clears all firewall rules, so essentially you're left with no firewall at all. Thus, you're also left without transparent proxy, NATting etcetera. Since this is inherently very unsafe, Iceditch will ''also'' disable forwarding between network interfaces.<br> '''iceditch backup'''<br> This will make Iceditch write a copy of the current configuration files. Used mainly to accommodate ''safestart''.<br> '''iceditch safestart'''<br> This will have Iceditch start the firewall, but after five minutes, it will revert to the backup configuration. This enables you to backup the current configuration, change it, and test it. If it accidentally shuts you out, it will revert to the old configuration after five minutes. Good thinking, eh? Note: requires that you've made a backup confiuration; if none is present, safestart will ''clear'' the firewall upon the reversion time. Furthermore this option requires availability of the ''at'' command, where Iceditch will schedule the fallback to the old configuration.<br> '''iceditch restore'''<br> This will make Iceditch revert to the configuration it previously backed up. Note: this command can only be run interactively, since Iceditch will tell you at which time and date the backup configuration was made, and ask you if you really want to overwrite the current configuration with the old one.<br> '''iceditch noclear'''<br> This command will remove the fallback to the old configuration by clearing the ''at'' fallback.<br> '''iceditch halt'''<br> This is an emergency break: it will clear all firewall rules, and then block any network traffic going in or out of your machine over any network interface - with the exception of the ''lo'' internal network adapter. When you have reason to believe your system is in some way compromised, you can throw this emergency brake. For those who don't need or want it: the configuration file can disable this emergency break. ===Special options=== There are a number of options that Iceditch recognises, that are listed below. Note: options cannot be grouped. For example, Iceditch understands ''-d -e'' but not ''-de''.<br> '''-d''' dummy run; prevents Iceditch to actually invoke IPtables at all. Used mainly with ''-e'' or ''-E'', to check a configuration.<br> '''-e''' will make Iceditch echo all generated IPtables commands to the console. This can be useful to test a complex configuration. ''-e'' cannot be combined with ''-E''<br> '''-E''' will make Iceditch echo all rules in Iceditch language. Only useful if your rulefile contains lots of conditional rules, flow control and other programming bling. ''-E'' cannot be combined with ''-e''<br> '''-r <rulefile>''' will make Iceditch use ''<rulefile>'' instead of the default rulefile ''/etc/iceditch/rules.conf''. ''<rulefile>'' can be specified with an absolute path, with a relative path from the current working directory, or without path at all (in which case Iceditch assumes the file lives in ''/etc/iceditch'').<br> '''-t <number>''' can be used only with ''safestart''; it signifies the number of minutes (1-60) that ''safestart'' must wait before it reverts the configuration.<br> '''-v''' verbosity; will make Iceditch send the -v option to all commands it calls itself<br> '''-V''' print the version number and exit (overrides any other option or parameter)<br> ===Logging=== Iceditch logs any (attempted) start or stop action to the syslog. When the Iceditch-built firewall runs, it can make use of the standard IPtables log facilities. These can be either logging packages to syslog, or using the ''ulogd'' logging daemon. This choice can be specified in the Iceditch configuration file, although you have to ensure yourself that ''ulogd'' actually exists on your system. da1ceea4ac8d6dc12c57ce48042515b78d3f3d58 1581 1580 2008-07-26T08:14:27Z Saruman! 2 changed rulesfile location to always be /etc/iceditch wikitext text/x-wiki This page describes the functions that the Iceditch script can perform for you. ===Rights and security=== Since Iceditch calls IPtables, you need root rights to call it. We therefor have not implemented any mechanism to use Iceditch as a non-root user. ===Invoking Iceditch=== '''iceditch start | restart | reload'''<br> The most common invocation will be the automatic startup at boot time. To this end, the script understands being called with only the "start" parameter. ''iceditch start'' will setup the firewall quietly and completely.<br> '''iceditch stop | unload'''<br> We don't want anyone person or process to be able to ''stop'' the firewall, so this command is accepted, but does nothing except log the attempt.<br> '''iceditch clear'''<br> This clears all firewall rules, so essentially you're left with no firewall at all. Thus, you're also left without transparent proxy, NATting etcetera. Since this is inherently very unsafe, Iceditch will ''also'' disable forwarding between network interfaces.<br> '''iceditch backup'''<br> This will make Iceditch write a copy of the current configuration files. Used mainly to accommodate ''safestart''.<br> '''iceditch safestart'''<br> This will have Iceditch start the firewall, but after five minutes, it will revert to the backup configuration. This enables you to backup the current configuration, change it, and test it. If it accidentally shuts you out, it will revert to the old configuration after five minutes. Good thinking, eh? Note: requires that you've made a backup confiuration; if none is present, safestart will ''clear'' the firewall upon the reversion time. Furthermore this option requires availability of the ''at'' command, where Iceditch will schedule the fallback to the old configuration.<br> '''iceditch restore'''<br> This will make Iceditch revert to the configuration it previously backed up. Note: this command can only be run interactively, since Iceditch will tell you at which time and date the backup configuration was made, and ask you if you really want to overwrite the current configuration with the old one.<br> '''iceditch noclear'''<br> This command will remove the fallback to the old configuration by clearing the ''at'' fallback.<br> '''iceditch halt'''<br> This is an emergency break: it will clear all firewall rules, and then block any network traffic going in or out of your machine over any network interface - with the exception of the ''lo'' internal network adapter. When you have reason to believe your system is in some way compromised, you can throw this emergency brake. For those who don't need or want it: the configuration file can disable this emergency break. ===Special options=== There are a number of options that Iceditch recognises, that are listed below. Note: options cannot be grouped. For example, Iceditch understands ''-d -e'' but not ''-de''.<br> '''-d''' dummy run; prevents Iceditch to actually invoke IPtables at all. Used mainly with ''-e'' or ''-E'', to check a configuration.<br> '''-e''' will make Iceditch echo all generated IPtables commands to the console. This can be useful to test a complex configuration. ''-e'' cannot be combined with ''-E''<br> '''-E''' will make Iceditch echo all rules in Iceditch language. Only useful if your rulefile contains lots of conditional rules, flow control and other programming bling. ''-E'' cannot be combined with ''-e''<br> '''-r <rulefile>''' will make Iceditch use ''<rulefile>'' instead of the default rulefile ''rules.conf''. ''<rulefile>'' must be specified as a simple filename only (Iceditch expects the rulefile to live in /etc/iceditch)<br> '''-t <number>''' can be used only with ''safestart''; it signifies the number of minutes (1-60) that ''safestart'' must wait before it reverts the configuration.<br> '''-v''' verbosity; will make Iceditch send the -v option to all commands it calls itself<br> '''-V''' print the version number and exit (overrides any other option or parameter)<br> ===Logging=== Iceditch logs any (attempted) start or stop action to the syslog. When the Iceditch-built firewall runs, it can make use of the standard IPtables log facilities. These can be either logging packages to syslog, or using the ''ulogd'' logging daemon. This choice can be specified in the Iceditch configuration file, although you have to ensure yourself that ''ulogd'' actually exists on your system. 253c8a3d8188140abc326772b5bf0fac36d96b5f 0 1450 1583 1549 2008-07-27T07:29:17Z Saruman! 2 changed config filename wikitext text/x-wiki Iceditch is quite a simple script, so it has only a few files. In a standard Debian environment, you'll find these files: '''/etc/iceditch/rules.conf'''<br> This is the "rulefile", that contains your actual firewall rules (in [[Iceditch IPtables language]]). '''/etc/iceditch/iceditch.conf'''<br> This is the "config file", a file that contains all default parameters that Iceditch needs for your firewall, like aliases for your NICs (like ''Inet=eth0''). This is also the place where you would stuff your custom functions, so that you could call them from the rulefile when necessary. '''/etc/iceditch/params.conf'''<br> This is the optional "parameter file", a file that may contain lists of parameters that you would want to read into your firewall. An example would be a list like IPblocked=192.168.1.14 # don't want any traffic to the switch from here IPblocked=216.73.93.8 IPblocked=127.0.0.2 # Blocked on 2008-07-05 for hacking attempts '''/etc/iceditch/backup/.rules.bak''',<br> '''/etc/iceditch/backup/.config.bak''',<br> '''/etc/iceditch/backup/.params.bak'''<br> These three files may or may not exist; they're backups of the rulefile and parameter file, made by Iceditch itself when you told it to. These will be the source of the "new" rules and parameters, when Iceditch performs a fallback after a [[Iceditch functionality | safestart]], or when you call [[Iceditch functionality | ''iceditch restore'']]. '''/bin/iceditch'''<br> This is the firewall script itself. It's an executable shellscript. '''/etc/init.d/iceditch'''<br> This is only a symlink to the iceditch script itself. faf024203b59d19c0182507ec69428062f6b0eb4 0 1458 1586 2008-07-27T17:11:38Z Saruman! 2 page started wikitext text/x-wiki Asterisk installation on Lenny can be performed with ease using Aptitude. This brings you Asterisk version 1.4.20. Since this has a graphical GUI manager, it might be wise to add X to your server. f86bfabd3a2b44452449e1aeb5809672d1a8e680 0 1446 1591 1551 2008-08-02T19:03:21Z Saruman! 2 changed ACCEPT range wikitext text/x-wiki == Parameter: log == ''target '''log [msg <message>]''' <qualifiers>''<br> After most keywords, a "log" parameter can be added (see below). If the "log" parameter is followed by "msg", then the parameter following "msg" is read and used as log-prefix. The parameter is not allowed to have whitespace, and the maximum length of the log-prefix is determined by your version of netfilter/IPtables (usually some 31 characters). Thus a packet matching the rule will be logged with the default setting of the "log" target. If the "log" parameter is ''not'' followed by "msg", then the packet will be logged with the default log message for that particular target keyword, and all the other default setting of the "log" target. Thus, should you want to log a packet with more control over the logging parameters, then you need an extra line, beginning with the ''target keyword'' "log", instead of just following the target keyword with parameter ''log''. For more information, see the target keyword "log" below. == Target keyword: accept == '''''accept [log [msg <message>]] <qualifiers>'''''<br> If a network packet matches the qualifiers, then it will be accepted (passed) through the table/chain defined in the context where you put the accept rule. Example: <pre>context "INPUT" "filter" accept –p tcp --dport 22</pre> Iceditch works this out to iptables –t filter –A INPUT –p tcp –-dport 22 –-jump ACCEPT Should you want to log the packet, you’d use context "INPUT" "filter" accept log –p tcp --dport 22 Iceditch works this out to iptables –t filter –A INPUT –p tcp –-dport 22 \ –-jump LOG --log-prefix INPUT_accept iptables –t filter –A INPUT –p tcp –-dport 22 –-jump ACCEPT Note: the ACCEPT target is valid in any user-manipulable table/chain combination == Target keyword: classify == '''''classify <classval> [log [msg <message>]] <qualifiers>'''''<br> If a packet travelling through the mangle table in the POSTROUTING chain matches the qualifiers, then it will be classified with the <classval> specified. An example: classify 2:11 –p tcp --dport 22 The script works this out to iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump CLASSIFY --setclass 2:11 Should you want to also log the packet, you’d use classify 2:11 log –p tcp --dport 22 The script works this out to iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump LOG \ --log-prefix classified_2:11: iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump CLASSIFY \ --setclass 2:11 Should you not give a msg, then the log-prefix becomes POSTROUTING_CLASSIFY_set_<classval>. Because of how iptables handles the CLASSIFY target, you can only use it in contexts where the chain is “POSTROUTING” and the table is “mangle”. == Target keyword: drop == '''''drop [log [msg <message>]] <qualifiers> '''''<br> In essence, this does the same as the “accept” target keyword, only it jumps to DROP instead of ACCEPT. Thus any packet matching the qualifiers gets discarded; it will not get sent on to its final destination (or next hop), it will not get processed by any other firewall rule, and the sender of the packet is unaware of your treatment of his packet. Should you want to also log the packet, you’d use context "FORWARD" "filter" drop log –p tcp -s 10.0.0.0/16 The script works this out to iptables –t filter –A FORWARD –p tcp -s 10.0.0.0/16 –-jump LOG \ --log-prefix FORWARD_DROP: iptables –t filter –A FORWARD –p tcp -s 10.0.0.0/16 –-jump DROP Because of how iptables handles the DROP target, you can only use it in contexts where the table is “filter”. == Target keyword: log == '''''log [msg <message>] [lvl <loglevel>] <qualifiers>'''''<br> Sometimes, the standard ''log'' parameter is just not enough. This is mostly the case when you want to log a packet to a log-level other than the default level, which for most systems is 4 (''warning''). For this reason, AND for flexibility and clarity, Iceditch has its own target keyword ''log''. Just as when you use the ''log'' parameter, Iceditch will call the log target specified in the Iceditch [[Iceditch file structure | config file]]. Standard this is LOG, but optionally you could specify ULOG. Depending on which log target you have specified, there are some options you can use with the Iceditch target keyword ''log''; it is currently deemed unnecessary to make specific Iceditch parameters for them, but we'll list the official IPtables options here, which you can put in the <qualifiers> list: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" ! colspan="2" style="background:#ffdead;"|LOG options | ! colspan="2" style="background:#ffdead;"|ULOG options |- !style="background:#ffdead;"|Option !style="background:#ffdead;"|Description | !style="background:#ffdead;"|Option !style="background:#ffdead;"|Description |- | --log-ip-options |Makes Netfilter include the IP options in the log entry | | --ulog-cprange <''size''> |log the first ''size'' bytes of each packet |- | --log-tcp-options |Makes Netfilter include the TCP options in the log entry | | --ulog-nlgroup <''nlgroup''> |Log to Netlink group number ''nlgroup'' (must match ''/etc/ulogd.conf'') |- | --log-tcp-sequence |Makes Netfilter include the TCP sequence number in the log entry | | --ulog-qthreshold <''value''> |Queue ''value'' packets before sending them to ''ulogd'' (default = 1, max = 50) |- |} <br> For completeness, we here reproduce the list of logging levels that LOG understands: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Level !style="background:#ffdead;"|Description |- |0 |''emerg'' or ''panic'' |- |1 |''alert'' |- |2 |''crit'' |- |3 |''err'' |- |4 |''warn'' (default) |- |5 |''notice'' |- |6 |''info'' |- |7 |''debug'' |- |} == Target keyword: mark == '''''mark <markval> [log [msg <message>]] <qualifiers>'''''<br> If a packet matches the qualifiers, then it will be marked with the <markval> specified. An example from the context “PREROUTING” “mangle”: mark 2 –p tcp --dport 22 Iceditch works this out to iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump MARK --setmark 2 Should you want to also log the packet, you’d use mark 2 log –p tcp --dport 22 Iceditch works this out to iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump LOG \ --log-prefix PREROUTING_MARK_set_2: iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump MARK --setmark 2 Because of how iptables handles the MARK target, you can only use it in contexts where the table is “mangle”. == Target keyword: redirect == '''''redirect [to <to-ports>] [log [msg <message>]] <qualifiers>'''''<br> If a packet matches the qualifiers, then it will be redirected to the local machine, by setting the destination IP to a fitting IP address of the local machine (i.e. 127.0.0.1, or the first-bound IP address of the interface over which it came in. Additionally, by specifying “to <to-ports>” you can have the destination ports redirected to a port or portrange. <to-ports> can either be a port number (e.g. 8080) or a port range (e.g. 6661-6669; the latter is inclusive). Example for a transparent HTTP proxy: context "OUTPUT" "nat" redirect to 8080 –p tcp --dport 80 Iceditch works this out to iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump REDIRECT –to-ports 8080 Should you want to log the packet, you could use redirect to 8080 log –p tcp --dport 80 Iceditch works this out to iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump LOG \ --log-prefix OUTPUT_REDIRECT_to_8080: iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump REDIRECT –-to-ports 8080 Because of how iptables handles the REDIRECT target, you can only use it in contexts where the table is “nat” and the chain is PREROUTING or OUTPUT. == Target keyword: reject == '''''reject [with <type>] [log [msg <message>]] <qualifiers>'''''<br> In essence, this does the same as the “drop” target keyword, only it jumps to REJECT instead of DROP. This means the packet is discarded (just as with DROP), but the sender is notified using ICMP (by default, your machine will send an ICMP-packet of type "icmp-port-unreachable"). Because of how iptables handles the REJECT target, you can only use it in contexts where the table is “filter”. Optionally, you can follow “reject” with the keyword “with”, and then use one of the following rejection types: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Type !style="background:#ffdead;"|Description |- | icmp-host-prohibited | will send an ICMP-message "host prohibited" |- | icmp-host-unreachable | will send an ICMP-message "host unreachable" |- | icmp-net-prohibited | will send an ICMP-message "net prohibited" |- | icmp-net-unreachable | will send an ICMP-message "net unreachable" |- | icmp-port-unreachable | DEFAULT; will send an ICMP-message "port unreachable" |- | icmp-proto-unreachable | DEFAULT; will send an ICMP-message "protocol unreachable" |- | tcp-reset | will send a TCP reset, a packet with the RST flag set (as a response to a TCP packet only) |- | host-prohib | synonymous to icmp-host-prohibited |- | host-unreach | synonymous to icmp-host-unreachable |- | net-prohib | synonymous to icmp-net-prohibited |- | net-unreach | synonymous to icmp-net-unreachable |- | port-unreach | synonymous to icmp-port-unreachable |- | proto-unreach | synonymous to icmp-proto-unreachable |- |} If you don’t specify “with <type>”, then netfilter will assume icmp-port-unreachable. Thus, should you want to reject a packet in context filter_INPUT (and log it) with reason net-prohib, you’d use reject with net-prohib log –p tcp –i eth0 --dport 22 Iceditch works this out to iptables –t filter –A INPUT –p tcp –i eth0 –-dport 22 –-jump LOG \ --log-prefix INPUT_REJECT_with_net-prohib: iptables –t filter –A INPUT –p tcp –i eth0 –-dport 22 \ –-jump REJECT –-reject-with net-prohib –p tcp –i eth0 –-dport 22 490944e5709c580f40517c09fb2fa6e420909c94 1592 1591 2008-08-04T19:58:15Z Saruman! 2 added SNAT target wikitext text/x-wiki == Parameter: log == ''target '''log [msg <message>]''' <qualifiers>''<br> After most keywords, a "log" parameter can be added (see below). If the "log" parameter is followed by "msg", then the parameter following "msg" is read and used as log-prefix. The parameter is not allowed to have whitespace, and the maximum length of the log-prefix is determined by your version of netfilter/IPtables (usually some 31 characters). Thus a packet matching the rule will be logged with the default setting of the "log" target. If the "log" parameter is ''not'' followed by "msg", then the packet will be logged with the default log message for that particular target keyword, and all the other default setting of the "log" target. Thus, should you want to log a packet with more control over the logging parameters, then you need an extra line, beginning with the ''target keyword'' "log", instead of just following the target keyword with parameter ''log''. For more information, see the target keyword "log" below. == Target keyword: accept == '''''accept [log [msg <message>]] <qualifiers>'''''<br> If a network packet matches the qualifiers, then it will be accepted (passed) through the table/chain defined in the context where you put the accept rule. Example: <pre>context "INPUT" "filter" accept –p tcp --dport 22</pre> Iceditch works this out to iptables –t filter –A INPUT –p tcp –-dport 22 –-jump ACCEPT Should you want to log the packet, you’d use context "INPUT" "filter" accept log –p tcp --dport 22 Iceditch works this out to iptables –t filter –A INPUT –p tcp –-dport 22 \ –-jump LOG --log-prefix INPUT_accept iptables –t filter –A INPUT –p tcp –-dport 22 –-jump ACCEPT Note: the ACCEPT target is valid in any user-manipulable table/chain combination == Target keyword: classify == '''''classify <classval> [log [msg <message>]] <qualifiers>'''''<br> If a packet travelling through the mangle table in the POSTROUTING chain matches the qualifiers, then it will be classified with the <classval> specified. An example: classify 2:11 –p tcp --dport 22 The script works this out to iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump CLASSIFY --setclass 2:11 Should you want to also log the packet, you’d use classify 2:11 log –p tcp --dport 22 The script works this out to iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump LOG \ --log-prefix classified_2:11: iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump CLASSIFY \ --setclass 2:11 Should you not give a msg, then the log-prefix becomes POSTROUTING_CLASSIFY_set_<classval>. Because of how iptables handles the CLASSIFY target, you can only use it in contexts where the chain is “POSTROUTING” and the table is “mangle”. == Target keyword: drop == '''''drop [log [msg <message>]] <qualifiers> '''''<br> In essence, this does the same as the “accept” target keyword, only it jumps to DROP instead of ACCEPT. Thus any packet matching the qualifiers gets discarded; it will not get sent on to its final destination (or next hop), it will not get processed by any other firewall rule, and the sender of the packet is unaware of your treatment of his packet. Should you want to also log the packet, you’d use context "FORWARD" "filter" drop log –p tcp -s 10.0.0.0/16 The script works this out to iptables –t filter –A FORWARD –p tcp -s 10.0.0.0/16 –-jump LOG \ --log-prefix FORWARD_DROP: iptables –t filter –A FORWARD –p tcp -s 10.0.0.0/16 –-jump DROP Because of how iptables handles the DROP target, you can only use it in contexts where the table is “filter”. == Target keyword: log == '''''log [msg <message>] [lvl <loglevel>] <qualifiers>'''''<br> Sometimes, the standard ''log'' parameter is just not enough. This is mostly the case when you want to log a packet to a log-level other than the default level, which for most systems is 4 (''warning''). For this reason, AND for flexibility and clarity, Iceditch has its own target keyword ''log''. Just as when you use the ''log'' parameter, Iceditch will call the log target specified in the Iceditch [[Iceditch file structure | config file]]. Standard this is LOG, but optionally you could specify ULOG. Depending on which log target you have specified, there are some options you can use with the Iceditch target keyword ''log''; it is currently deemed unnecessary to make specific Iceditch parameters for them, but we'll list the official IPtables options here, which you can put in the <qualifiers> list: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" ! colspan="2" style="background:#ffdead;"|LOG options | ! colspan="2" style="background:#ffdead;"|ULOG options |- !style="background:#ffdead;"|Option !style="background:#ffdead;"|Description | !style="background:#ffdead;"|Option !style="background:#ffdead;"|Description |- | --log-ip-options |Makes Netfilter include the IP options in the log entry | | --ulog-cprange <''size''> |log the first ''size'' bytes of each packet |- | --log-tcp-options |Makes Netfilter include the TCP options in the log entry | | --ulog-nlgroup <''nlgroup''> |Log to Netlink group number ''nlgroup'' (must match ''/etc/ulogd.conf'') |- | --log-tcp-sequence |Makes Netfilter include the TCP sequence number in the log entry | | --ulog-qthreshold <''value''> |Queue ''value'' packets before sending them to ''ulogd'' (default = 1, max = 50) |- |} <br> For completeness, we here reproduce the list of logging levels that LOG understands: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Level !style="background:#ffdead;"|Description |- |0 |''emerg'' or ''panic'' |- |1 |''alert'' |- |2 |''crit'' |- |3 |''err'' |- |4 |''warn'' (default) |- |5 |''notice'' |- |6 |''info'' |- |7 |''debug'' |- |} == Target keyword: mark == '''''mark <markval> [log [msg <message>]] <qualifiers>'''''<br> If a packet matches the qualifiers, then it will be marked with the <markval> specified. An example from the context “PREROUTING” “mangle”: mark 2 –p tcp --dport 22 Iceditch works this out to iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump MARK --setmark 2 Should you want to also log the packet, you’d use mark 2 log –p tcp --dport 22 Iceditch works this out to iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump LOG \ --log-prefix PREROUTING_MARK_set_2: iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump MARK --setmark 2 Because of how iptables handles the MARK target, you can only use it in contexts where the table is “mangle”. == Target keyword: redirect == '''''redirect [to <to-ports>] [log [msg <message>]] <qualifiers>'''''<br> If a packet matches the qualifiers, then it will be redirected to the local machine, by setting the destination IP to a fitting IP address of the local machine (i.e. 127.0.0.1, or the first-bound IP address of the interface over which it came in. Additionally, by specifying “to <to-ports>” you can have the destination ports redirected to a port or portrange. <to-ports> can either be a port number (e.g. 8080) or a port range (e.g. 6661-6669; the latter is inclusive). Example for a transparent HTTP proxy: context "OUTPUT" "nat" redirect to 8080 –p tcp --dport 80 Iceditch works this out to iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump REDIRECT –to-ports 8080 Should you want to log the packet, you could use redirect to 8080 log –p tcp --dport 80 Iceditch works this out to iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump LOG \ --log-prefix OUTPUT_REDIRECT_to_8080: iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump REDIRECT –-to-ports 8080 Because of how iptables handles the REDIRECT target, you can only use it in contexts where the table is “nat” and the chain is PREROUTING or OUTPUT. == Target keyword: reject == '''''reject [with <type>] [log [msg <message>]] <qualifiers>'''''<br> In essence, this does the same as the “drop” target keyword, only it jumps to REJECT instead of DROP. This means the packet is discarded (just as with DROP), but the sender is notified using ICMP (by default, your machine will send an ICMP-packet of type "icmp-port-unreachable"). Because of how iptables handles the REJECT target, you can only use it in contexts where the table is “filter”. Optionally, you can follow “reject” with the keyword “with”, and then use one of the following rejection types: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Type !style="background:#ffdead;"|Description |- | icmp-host-prohibited | will send an ICMP-message "host prohibited" |- | icmp-host-unreachable | will send an ICMP-message "host unreachable" |- | icmp-net-prohibited | will send an ICMP-message "net prohibited" |- | icmp-net-unreachable | will send an ICMP-message "net unreachable" |- | icmp-port-unreachable | DEFAULT; will send an ICMP-message "port unreachable" |- | icmp-proto-unreachable | DEFAULT; will send an ICMP-message "protocol unreachable" |- | tcp-reset | will send a TCP reset, a packet with the RST flag set (as a response to a TCP packet only) |- | host-prohib | synonymous to icmp-host-prohibited |- | host-unreach | synonymous to icmp-host-unreachable |- | net-prohib | synonymous to icmp-net-prohibited |- | net-unreach | synonymous to icmp-net-unreachable |- | port-unreach | synonymous to icmp-port-unreachable |- | proto-unreach | synonymous to icmp-proto-unreachable |- |} If you don’t specify “with <type>”, then netfilter will assume icmp-port-unreachable. Thus, should you want to reject a packet in context filter_INPUT (and log it) with reason net-prohib, you’d use reject with net-prohib log –p tcp –i eth0 --dport 22 Iceditch works this out to iptables –t filter –A INPUT –p tcp –i eth0 –-dport 22 –-jump LOG \ --log-prefix INPUT_REJECT_with_net-prohib: iptables –t filter –A INPUT –p tcp –i eth0 –-dport 22 \ –-jump REJECT –-reject-with net-prohib –p tcp –i eth0 –-dport 22 == Taret keyword: snat== '''''snat [to <a1[-a2][:p1-p2]> [to <a3[-a4][:p3-p4]> [...]]] [log [msg <message>]] <qualifiers>'''''<br> This keyword is only valid in the chain POSTROUTING, table nat. This will create a Source NATting rule for you, whereby a packet matching the qualifiers will be source NATted using the source IP address ''a1'' (or the range ''a1-a2''). Ofcourse, ''a1[-a2]'' should be valid IP address(es) of the firewalling machine.<br> Furthermore, if a port range ''p1-p2'' is specified, then you'll limit the range of ports that ''snat'' will use outbound (only valid for TCP or UDP packets).<br> Finally, it is possible to specify multiple IP address ranges and port ranges, using multiple ''to <a1[-a2][:p1-p2]'' in succession.<br> An example would be: context "POSTROUTING" "nat" snat to $inetIP -o $inetIF ! --src $inetIP If the variable ''$inetIP'' contains your public IP (e.g. 212.238.151.72), and ''$inetIF'' your interface connected to the Internet (e.g. ''eth0''), then this rule would expand to iptables -A POSTROUTING -t nat -o eth0 ! --src 212.238.151.72 -j SNAT This would cause Iceditch to sourcenat any outbound packet that is NOT sent by your firewall itself. 36424209f084880c1a9a8114ec13e37aea113634 1593 1592 2008-08-04T20:05:22Z Saruman! 2 /* Target keyword: snat */ fixed typo's, expounded a bit wikitext text/x-wiki == Parameter: log == ''target '''log [msg <message>]''' <qualifiers>''<br> After most keywords, a "log" parameter can be added (see below). If the "log" parameter is followed by "msg", then the parameter following "msg" is read and used as log-prefix. The parameter is not allowed to have whitespace, and the maximum length of the log-prefix is determined by your version of netfilter/IPtables (usually some 31 characters). Thus a packet matching the rule will be logged with the default setting of the "log" target. If the "log" parameter is ''not'' followed by "msg", then the packet will be logged with the default log message for that particular target keyword, and all the other default setting of the "log" target. Thus, should you want to log a packet with more control over the logging parameters, then you need an extra line, beginning with the ''target keyword'' "log", instead of just following the target keyword with parameter ''log''. For more information, see the target keyword "log" below. == Target keyword: accept == '''''accept [log [msg <message>]] <qualifiers>'''''<br> If a network packet matches the qualifiers, then it will be accepted (passed) through the table/chain defined in the context where you put the accept rule. Example: <pre>context "INPUT" "filter" accept –p tcp --dport 22</pre> Iceditch works this out to iptables –t filter –A INPUT –p tcp –-dport 22 –-jump ACCEPT Should you want to log the packet, you’d use context "INPUT" "filter" accept log –p tcp --dport 22 Iceditch works this out to iptables –t filter –A INPUT –p tcp –-dport 22 \ –-jump LOG --log-prefix INPUT_accept iptables –t filter –A INPUT –p tcp –-dport 22 –-jump ACCEPT Note: the ACCEPT target is valid in any user-manipulable table/chain combination == Target keyword: classify == '''''classify <classval> [log [msg <message>]] <qualifiers>'''''<br> If a packet travelling through the mangle table in the POSTROUTING chain matches the qualifiers, then it will be classified with the <classval> specified. An example: classify 2:11 –p tcp --dport 22 The script works this out to iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump CLASSIFY --setclass 2:11 Should you want to also log the packet, you’d use classify 2:11 log –p tcp --dport 22 The script works this out to iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump LOG \ --log-prefix classified_2:11: iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump CLASSIFY \ --setclass 2:11 Should you not give a msg, then the log-prefix becomes POSTROUTING_CLASSIFY_set_<classval>. Because of how iptables handles the CLASSIFY target, you can only use it in contexts where the chain is “POSTROUTING” and the table is “mangle”. == Target keyword: drop == '''''drop [log [msg <message>]] <qualifiers> '''''<br> In essence, this does the same as the “accept” target keyword, only it jumps to DROP instead of ACCEPT. Thus any packet matching the qualifiers gets discarded; it will not get sent on to its final destination (or next hop), it will not get processed by any other firewall rule, and the sender of the packet is unaware of your treatment of his packet. Should you want to also log the packet, you’d use context "FORWARD" "filter" drop log –p tcp -s 10.0.0.0/16 The script works this out to iptables –t filter –A FORWARD –p tcp -s 10.0.0.0/16 –-jump LOG \ --log-prefix FORWARD_DROP: iptables –t filter –A FORWARD –p tcp -s 10.0.0.0/16 –-jump DROP Because of how iptables handles the DROP target, you can only use it in contexts where the table is “filter”. == Target keyword: log == '''''log [msg <message>] [lvl <loglevel>] <qualifiers>'''''<br> Sometimes, the standard ''log'' parameter is just not enough. This is mostly the case when you want to log a packet to a log-level other than the default level, which for most systems is 4 (''warning''). For this reason, AND for flexibility and clarity, Iceditch has its own target keyword ''log''. Just as when you use the ''log'' parameter, Iceditch will call the log target specified in the Iceditch [[Iceditch file structure | config file]]. Standard this is LOG, but optionally you could specify ULOG. Depending on which log target you have specified, there are some options you can use with the Iceditch target keyword ''log''; it is currently deemed unnecessary to make specific Iceditch parameters for them, but we'll list the official IPtables options here, which you can put in the <qualifiers> list: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" ! colspan="2" style="background:#ffdead;"|LOG options | ! colspan="2" style="background:#ffdead;"|ULOG options |- !style="background:#ffdead;"|Option !style="background:#ffdead;"|Description | !style="background:#ffdead;"|Option !style="background:#ffdead;"|Description |- | --log-ip-options |Makes Netfilter include the IP options in the log entry | | --ulog-cprange <''size''> |log the first ''size'' bytes of each packet |- | --log-tcp-options |Makes Netfilter include the TCP options in the log entry | | --ulog-nlgroup <''nlgroup''> |Log to Netlink group number ''nlgroup'' (must match ''/etc/ulogd.conf'') |- | --log-tcp-sequence |Makes Netfilter include the TCP sequence number in the log entry | | --ulog-qthreshold <''value''> |Queue ''value'' packets before sending them to ''ulogd'' (default = 1, max = 50) |- |} <br> For completeness, we here reproduce the list of logging levels that LOG understands: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Level !style="background:#ffdead;"|Description |- |0 |''emerg'' or ''panic'' |- |1 |''alert'' |- |2 |''crit'' |- |3 |''err'' |- |4 |''warn'' (default) |- |5 |''notice'' |- |6 |''info'' |- |7 |''debug'' |- |} == Target keyword: mark == '''''mark <markval> [log [msg <message>]] <qualifiers>'''''<br> If a packet matches the qualifiers, then it will be marked with the <markval> specified. An example from the context “PREROUTING” “mangle”: mark 2 –p tcp --dport 22 Iceditch works this out to iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump MARK --setmark 2 Should you want to also log the packet, you’d use mark 2 log –p tcp --dport 22 Iceditch works this out to iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump LOG \ --log-prefix PREROUTING_MARK_set_2: iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump MARK --setmark 2 Because of how iptables handles the MARK target, you can only use it in contexts where the table is “mangle”. == Target keyword: redirect == '''''redirect [to <to-ports>] [log [msg <message>]] <qualifiers>'''''<br> If a packet matches the qualifiers, then it will be redirected to the local machine, by setting the destination IP to a fitting IP address of the local machine (i.e. 127.0.0.1, or the first-bound IP address of the interface over which it came in. Additionally, by specifying “to <to-ports>” you can have the destination ports redirected to a port or portrange. <to-ports> can either be a port number (e.g. 8080) or a port range (e.g. 6661-6669; the latter is inclusive). Example for a transparent HTTP proxy: context "OUTPUT" "nat" redirect to 8080 –p tcp --dport 80 Iceditch works this out to iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump REDIRECT –to-ports 8080 Should you want to log the packet, you could use redirect to 8080 log –p tcp --dport 80 Iceditch works this out to iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump LOG \ --log-prefix OUTPUT_REDIRECT_to_8080: iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump REDIRECT –-to-ports 8080 Because of how iptables handles the REDIRECT target, you can only use it in contexts where the table is “nat” and the chain is PREROUTING or OUTPUT. == Target keyword: reject == '''''reject [with <type>] [log [msg <message>]] <qualifiers>'''''<br> In essence, this does the same as the “drop” target keyword, only it jumps to REJECT instead of DROP. This means the packet is discarded (just as with DROP), but the sender is notified using ICMP (by default, your machine will send an ICMP-packet of type "icmp-port-unreachable"). Because of how iptables handles the REJECT target, you can only use it in contexts where the table is “filter”. Optionally, you can follow “reject” with the keyword “with”, and then use one of the following rejection types: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Type !style="background:#ffdead;"|Description |- | icmp-host-prohibited | will send an ICMP-message "host prohibited" |- | icmp-host-unreachable | will send an ICMP-message "host unreachable" |- | icmp-net-prohibited | will send an ICMP-message "net prohibited" |- | icmp-net-unreachable | will send an ICMP-message "net unreachable" |- | icmp-port-unreachable | DEFAULT; will send an ICMP-message "port unreachable" |- | icmp-proto-unreachable | DEFAULT; will send an ICMP-message "protocol unreachable" |- | tcp-reset | will send a TCP reset, a packet with the RST flag set (as a response to a TCP packet only) |- | host-prohib | synonymous to icmp-host-prohibited |- | host-unreach | synonymous to icmp-host-unreachable |- | net-prohib | synonymous to icmp-net-prohibited |- | net-unreach | synonymous to icmp-net-unreachable |- | port-unreach | synonymous to icmp-port-unreachable |- | proto-unreach | synonymous to icmp-proto-unreachable |- |} If you don’t specify “with <type>”, then netfilter will assume icmp-port-unreachable. Thus, should you want to reject a packet in context filter_INPUT (and log it) with reason net-prohib, you’d use reject with net-prohib log –p tcp –i eth0 --dport 22 Iceditch works this out to iptables –t filter –A INPUT –p tcp –i eth0 –-dport 22 –-jump LOG \ --log-prefix INPUT_REJECT_with_net-prohib: iptables –t filter –A INPUT –p tcp –i eth0 –-dport 22 \ –-jump REJECT –-reject-with net-prohib –p tcp –i eth0 –-dport 22 == Target keyword: snat== '''''snat [to <a1[-a2][:p1-p2]]> [to <a3[-a4][:p3-p4]]>] ] [log [msg <message>] ] <qualifiers>'''''<br> This keyword is only valid in the chain POSTROUTING, table nat. And ofcourse, source NATting does you little good if you haven't enabled forwarding (e.g. use this machine as a router for other machines on your network).<br> Calling snat with the right parameters will create a Source NATting rule for you, whereby a packet matching the qualifiers will be source NATted using the source IP address ''a1'' (or the range ''a1-a2''). Ofcourse, ''a1[-a2]'' should be valid IP address(es) of the firewalling machine.<br> Furthermore, if a port range ''p1-p2'' is specified, then you'll limit the range of ports that ''snat'' will use outbound (only valid for TCP or UDP packets).<br> Finally, it is possible to specify ''multiple'' IP address ranges and port ranges, using multiple ''to <a1[-a2][:p1-p2]]'' declarations in succession.<br> An example would be: context "POSTROUTING" "nat" snat to $inetIP -o $inetIF ! --src $inetIP If the variable ''$inetIP'' contains your public IP (e.g. 212.238.151.72), and ''$inetIF'' your interface connected to the Internet (e.g. ''eth0''), then this rule would expand to iptables -A POSTROUTING -t nat -o eth0 ! --src 212.238.151.72 -j SNAT --to-source 212.238.151.72 This would cause Iceditch to source NAT any outbound packet that is NOT sent by your firewall itself; in effect your server is now a nice fullblown NAT router for all machines on your private network. ca1d72f3934775a909a37fb1ac80b7f7de0205e9 1594 1593 2008-08-04T20:21:26Z Saruman! 2 /* Target keyword: log */ expanded wikitext text/x-wiki == Parameter: log == ''target '''log [msg <message>]''' <qualifiers>''<br> After most keywords, a "log" parameter can be added (see below). If the "log" parameter is followed by "msg", then the parameter following "msg" is read and used as log-prefix. The parameter is not allowed to have whitespace, and the maximum length of the log-prefix is determined by your version of netfilter/IPtables (usually some 31 characters). Thus a packet matching the rule will be logged with the default setting of the "log" target. If the "log" parameter is ''not'' followed by "msg", then the packet will be logged with the default log message for that particular target keyword, and all the other default setting of the "log" target. Thus, should you want to log a packet with more control over the logging parameters, then you need an extra line, beginning with the ''target keyword'' "log", instead of just following the target keyword with parameter ''log''. For more information, see the target keyword "log" below. == Target keyword: accept == '''''accept [log [msg <message>]] <qualifiers>'''''<br> If a network packet matches the qualifiers, then it will be accepted (passed) through the table/chain defined in the context where you put the accept rule. Example: <pre>context "INPUT" "filter" accept –p tcp --dport 22</pre> Iceditch works this out to iptables –t filter –A INPUT –p tcp –-dport 22 –-jump ACCEPT Should you want to log the packet, you’d use context "INPUT" "filter" accept log –p tcp --dport 22 Iceditch works this out to iptables –t filter –A INPUT –p tcp –-dport 22 \ –-jump LOG --log-prefix INPUT_accept iptables –t filter –A INPUT –p tcp –-dport 22 –-jump ACCEPT Note: the ACCEPT target is valid in any user-manipulable table/chain combination == Target keyword: classify == '''''classify <classval> [log [msg <message>]] <qualifiers>'''''<br> If a packet travelling through the mangle table in the POSTROUTING chain matches the qualifiers, then it will be classified with the <classval> specified. An example: classify 2:11 –p tcp --dport 22 The script works this out to iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump CLASSIFY --setclass 2:11 Should you want to also log the packet, you’d use classify 2:11 log –p tcp --dport 22 The script works this out to iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump LOG \ --log-prefix classified_2:11: iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump CLASSIFY \ --setclass 2:11 Should you not give a msg, then the log-prefix becomes POSTROUTING_CLASSIFY_set_<classval>. Because of how iptables handles the CLASSIFY target, you can only use it in contexts where the chain is “POSTROUTING” and the table is “mangle”. == Target keyword: drop == '''''drop [log [msg <message>]] <qualifiers> '''''<br> In essence, this does the same as the “accept” target keyword, only it jumps to DROP instead of ACCEPT. Thus any packet matching the qualifiers gets discarded; it will not get sent on to its final destination (or next hop), it will not get processed by any other firewall rule, and the sender of the packet is unaware of your treatment of his packet. Should you want to also log the packet, you’d use context "FORWARD" "filter" drop log –p tcp -s 10.0.0.0/16 The script works this out to iptables –t filter –A FORWARD –p tcp -s 10.0.0.0/16 –-jump LOG \ --log-prefix FORWARD_DROP: iptables –t filter –A FORWARD –p tcp -s 10.0.0.0/16 –-jump DROP Because of how iptables handles the DROP target, you can only use it in contexts where the table is “filter”. == Target keyword: log == '''''log [msg <message>] [lvl <loglevel>] <qualifiers>'''''<br> Sometimes, the standard ''log'' parameter is just not enough. This is mostly the case when you want to log a packet to a log-level other than the default level, which for most systems is ''4'' (''warning''). Furthermore, maybe you want to log a certain type or class of packets, without performing an action on those packets just yet. For this reason, AND for flexibility and clarity, Iceditch has the dedicated target keyword ''log''.<br> Just as when you use the ''log'' parameter, Iceditch will call the log target specified in the Iceditch [[Iceditch file structure | config file]]. Standard this is LOG, but optionally you could specify ULOG in the config file. ''<message>'' can be any string of 32 characters max (letters, numbers and underscores; no spaces); the ''<loglevel>'' can either be numeric or the corresponding keyword (e.g. ''crit''); Iceditch translates it to its numeric value anyway. Furthermore, the order in which <msg> and <lvl> appear is not important.<br> Depending on which log target you have specified, there are some options you can use with the Iceditch target keyword ''log''; it is currently deemed unnecessary to make specific Iceditch parameters for them, but as a reference we'll list the official IPtables options here, which you can put in the <qualifiers> list: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" ! colspan="2" style="background:#ffdead;"|LOG options | ! colspan="2" style="background:#ffdead;"|ULOG options |- !style="background:#ffdead;"|Option !style="background:#ffdead;"|Description | !style="background:#ffdead;"|Option !style="background:#ffdead;"|Description |- | --log-ip-options |Makes Netfilter include the IP options in the log entry | | --ulog-cprange <''size''> |log the first ''size'' bytes of each packet |- | --log-tcp-options |Makes Netfilter include the TCP options in the log entry | | --ulog-nlgroup <''nlgroup''> |Log to Netlink group number ''nlgroup'' (must match ''/etc/ulogd.conf'') |- | --log-tcp-sequence |Makes Netfilter include the TCP sequence number in the log entry | | --ulog-qthreshold <''value''> |Queue ''value'' packets before sending them to ''ulogd'' (default = 1, max = 50) |- |} <br> For completeness, we here reproduce the list of logging levels that ''log'' understands: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Level !style="background:#ffdead;"|Description |- |0 |''emerg'' or ''panic'' |- |1 |''alert'' |- |2 |''crit'' |- |3 |''err'' |- |4 |''warn'' (default) |- |5 |''notice'' |- |6 |''info'' |- |7 |''debug'' |- |} Now an example: context "INPUT" "filter" log lvl info msg SSH_incoming -p tcp --dport 22 -i $inetIF Iceditch works this out into iptables -A INPUT -t filter -p tcp --dport 22 -i $inetIF --jump ULOG --ulog-prefix "SSH_incoming" --log-level 6 == Target keyword: mark == '''''mark <markval> [log [msg <message>]] <qualifiers>'''''<br> If a packet matches the qualifiers, then it will be marked with the <markval> specified. An example from the context “PREROUTING” “mangle”: mark 2 –p tcp --dport 22 Iceditch works this out to iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump MARK --setmark 2 Should you want to also log the packet, you’d use mark 2 log –p tcp --dport 22 Iceditch works this out to iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump LOG \ --log-prefix PREROUTING_MARK_set_2: iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump MARK --setmark 2 Because of how iptables handles the MARK target, you can only use it in contexts where the table is “mangle”. == Target keyword: redirect == '''''redirect [to <to-ports>] [log [msg <message>]] <qualifiers>'''''<br> If a packet matches the qualifiers, then it will be redirected to the local machine, by setting the destination IP to a fitting IP address of the local machine (i.e. 127.0.0.1, or the first-bound IP address of the interface over which it came in. Additionally, by specifying “to <to-ports>” you can have the destination ports redirected to a port or portrange. <to-ports> can either be a port number (e.g. 8080) or a port range (e.g. 6661-6669; the latter is inclusive). Example for a transparent HTTP proxy: context "OUTPUT" "nat" redirect to 8080 –p tcp --dport 80 Iceditch works this out to iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump REDIRECT –to-ports 8080 Should you want to log the packet, you could use redirect to 8080 log –p tcp --dport 80 Iceditch works this out to iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump LOG \ --log-prefix OUTPUT_REDIRECT_to_8080: iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump REDIRECT –-to-ports 8080 Because of how iptables handles the REDIRECT target, you can only use it in contexts where the table is “nat” and the chain is PREROUTING or OUTPUT. == Target keyword: reject == '''''reject [with <type>] [log [msg <message>]] <qualifiers>'''''<br> In essence, this does the same as the “drop” target keyword, only it jumps to REJECT instead of DROP. This means the packet is discarded (just as with DROP), but the sender is notified using ICMP (by default, your machine will send an ICMP-packet of type "icmp-port-unreachable"). Because of how iptables handles the REJECT target, you can only use it in contexts where the table is “filter”. Optionally, you can follow “reject” with the keyword “with”, and then use one of the following rejection types: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Type !style="background:#ffdead;"|Description |- | icmp-host-prohibited | will send an ICMP-message "host prohibited" |- | icmp-host-unreachable | will send an ICMP-message "host unreachable" |- | icmp-net-prohibited | will send an ICMP-message "net prohibited" |- | icmp-net-unreachable | will send an ICMP-message "net unreachable" |- | icmp-port-unreachable | DEFAULT; will send an ICMP-message "port unreachable" |- | icmp-proto-unreachable | DEFAULT; will send an ICMP-message "protocol unreachable" |- | tcp-reset | will send a TCP reset, a packet with the RST flag set (as a response to a TCP packet only) |- | host-prohib | synonymous to icmp-host-prohibited |- | host-unreach | synonymous to icmp-host-unreachable |- | net-prohib | synonymous to icmp-net-prohibited |- | net-unreach | synonymous to icmp-net-unreachable |- | port-unreach | synonymous to icmp-port-unreachable |- | proto-unreach | synonymous to icmp-proto-unreachable |- |} If you don’t specify “with <type>”, then netfilter will assume icmp-port-unreachable. Thus, should you want to reject a packet in context filter_INPUT (and log it) with reason net-prohib, you’d use reject with net-prohib log –p tcp –i eth0 --dport 22 Iceditch works this out to iptables –t filter –A INPUT –p tcp –i eth0 –-dport 22 –-jump LOG \ --log-prefix INPUT_REJECT_with_net-prohib: iptables –t filter –A INPUT –p tcp –i eth0 –-dport 22 \ –-jump REJECT –-reject-with net-prohib –p tcp –i eth0 –-dport 22 == Target keyword: snat== '''''snat [to <a1[-a2][:p1-p2]]> [to <a3[-a4][:p3-p4]]>] ] [log [msg <message>] ] <qualifiers>'''''<br> This keyword is only valid in the chain POSTROUTING, table nat. And ofcourse, source NATting does you little good if you haven't enabled forwarding (e.g. use this machine as a router for other machines on your network).<br> Calling snat with the right parameters will create a Source NATting rule for you, whereby a packet matching the qualifiers will be source NATted using the source IP address ''a1'' (or the range ''a1-a2''). Ofcourse, ''a1[-a2]'' should be valid IP address(es) of the firewalling machine.<br> Furthermore, if a port range ''p1-p2'' is specified, then you'll limit the range of ports that ''snat'' will use outbound (only valid for TCP or UDP packets).<br> Finally, it is possible to specify ''multiple'' IP address ranges and port ranges, using multiple ''to <a1[-a2][:p1-p2]]'' declarations in succession.<br> An example would be: context "POSTROUTING" "nat" snat to $inetIP -o $inetIF ! --src $inetIP If the variable ''$inetIP'' contains your public IP (e.g. 212.238.151.72), and ''$inetIF'' your interface connected to the Internet (e.g. ''eth0''), then this rule would expand to iptables -A POSTROUTING -t nat -o eth0 ! --src 212.238.151.72 -j SNAT --to-source 212.238.151.72 This would cause Iceditch to source NAT any outbound packet that is NOT sent by your firewall itself; in effect your server is now a nice fullblown NAT router for all machines on your private network. b020ed2cff1eecd8f3816e8095709a57c2b521e5 1595 1594 2008-08-04T20:33:42Z Saruman! 2 added "context" wikitext text/x-wiki == Parameter: log == ''target '''log [msg <message>]''' <qualifiers>''<br> After most keywords, a "log" parameter can be added (see below). If the "log" parameter is followed by "msg", then the parameter following "msg" is read and used as log-prefix. The parameter is not allowed to have whitespace, and the maximum length of the log-prefix is determined by your version of netfilter/IPtables (usually some 31 characters). Thus a packet matching the rule will be logged with the default setting of the "log" target. If the "log" parameter is ''not'' followed by "msg", then the packet will be logged with the default log message for that particular target keyword, and all the other default setting of the "log" target. Thus, should you want to log a packet with more control over the logging parameters, then you need an extra line, beginning with the ''target keyword'' "log", instead of just following the target keyword with parameter ''log''. For more information, see the target keyword "log" below. == Context keyword: context == '''''context <chain> <table>'''''<br> Every IPtables rule is written to a chain in a table; with Iceditch, you don't have to specify the chain and table in every line. Just precede the lines with the ''context'' statement. Example: context POSTROUTING nat Notes: the order of chain and table does not matter; ''context nat POSTROUTING'' works just as well. Furthermore, <chain> and <table> have been made case-insensitive; whatever you specify as chain will be translated to uppercase, whatever you specify as table will be translated to lowercase. This gives you the possibility to write the context as you like to read it, e.g. ''context Postrouting Nat''; after processing this, Iceditch will have two variables $CHAIN="POSTROUTING" and $TABLE="nat" that it will use in every following command. For example: context "Input" "fIlTeR" accept -p tcp --dport 22 will result in the following IPtables call: iptables -A INPUT -t filter -p tcp --dport 22 --jump ACCEPT If you do NOT specify a [[Iceditch IPtables language | valid combination]] of chain and table, the execution of Iceditch will halt with a fatal error. It is allowed (but not recommended) to call ''context'' multiple times for the same combination of chain and table; the order in which the rules are added to that chain in that table, is the same in which they appear in your rulefile, top to bottom. == Target keyword: accept == '''''accept [log [msg <message>]] <qualifiers>'''''<br> If a network packet matches the qualifiers, then it will be accepted (passed) through the table/chain defined in the context where you put the accept rule. Example: <pre>context "INPUT" "filter" accept –p tcp --dport 22</pre> Iceditch works this out to iptables –t filter –A INPUT –p tcp –-dport 22 –-jump ACCEPT Should you want to log the packet, you’d use context "INPUT" "filter" accept log –p tcp --dport 22 Iceditch works this out to iptables –t filter –A INPUT –p tcp –-dport 22 \ –-jump LOG --log-prefix INPUT_accept iptables –t filter –A INPUT –p tcp –-dport 22 –-jump ACCEPT Note: the ACCEPT target is valid in any user-manipulable table/chain combination == Target keyword: classify == '''''classify <classval> [log [msg <message>]] <qualifiers>'''''<br> If a packet travelling through the mangle table in the POSTROUTING chain matches the qualifiers, then it will be classified with the <classval> specified. An example: classify 2:11 –p tcp --dport 22 The script works this out to iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump CLASSIFY --setclass 2:11 Should you want to also log the packet, you’d use classify 2:11 log –p tcp --dport 22 The script works this out to iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump LOG \ --log-prefix classified_2:11: iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump CLASSIFY \ --setclass 2:11 Should you not give a msg, then the log-prefix becomes POSTROUTING_CLASSIFY_set_<classval>. Because of how iptables handles the CLASSIFY target, you can only use it in contexts where the chain is “POSTROUTING” and the table is “mangle”. == Target keyword: drop == '''''drop [log [msg <message>]] <qualifiers> '''''<br> In essence, this does the same as the “accept” target keyword, only it jumps to DROP instead of ACCEPT. Thus any packet matching the qualifiers gets discarded; it will not get sent on to its final destination (or next hop), it will not get processed by any other firewall rule, and the sender of the packet is unaware of your treatment of his packet. Should you want to also log the packet, you’d use context "FORWARD" "filter" drop log –p tcp -s 10.0.0.0/16 The script works this out to iptables –t filter –A FORWARD –p tcp -s 10.0.0.0/16 –-jump LOG \ --log-prefix FORWARD_DROP: iptables –t filter –A FORWARD –p tcp -s 10.0.0.0/16 –-jump DROP Because of how iptables handles the DROP target, you can only use it in contexts where the table is “filter”. == Target keyword: log == '''''log [msg <message>] [lvl <loglevel>] <qualifiers>'''''<br> Sometimes, the standard ''log'' parameter is just not enough. This is mostly the case when you want to log a packet to a log-level other than the default level, which for most systems is ''4'' (''warning''). Furthermore, maybe you want to log a certain type or class of packets, without performing an action on those packets just yet. For this reason, AND for flexibility and clarity, Iceditch has the dedicated target keyword ''log''.<br> Just as when you use the ''log'' parameter, Iceditch will call the log target specified in the Iceditch [[Iceditch file structure | config file]]. Standard this is LOG, but optionally you could specify ULOG in the config file. ''<message>'' can be any string of 32 characters max (letters, numbers and underscores; no spaces); the ''<loglevel>'' can either be numeric or the corresponding keyword (e.g. ''crit''); Iceditch translates it to its numeric value anyway. Furthermore, the order in which <msg> and <lvl> appear is not important.<br> Depending on which log target you have specified, there are some options you can use with the Iceditch target keyword ''log''; it is currently deemed unnecessary to make specific Iceditch parameters for them, but as a reference we'll list the official IPtables options here, which you can put in the <qualifiers> list: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" ! colspan="2" style="background:#ffdead;"|LOG options | ! colspan="2" style="background:#ffdead;"|ULOG options |- !style="background:#ffdead;"|Option !style="background:#ffdead;"|Description | !style="background:#ffdead;"|Option !style="background:#ffdead;"|Description |- | --log-ip-options |Makes Netfilter include the IP options in the log entry | | --ulog-cprange <''size''> |log the first ''size'' bytes of each packet |- | --log-tcp-options |Makes Netfilter include the TCP options in the log entry | | --ulog-nlgroup <''nlgroup''> |Log to Netlink group number ''nlgroup'' (must match ''/etc/ulogd.conf'') |- | --log-tcp-sequence |Makes Netfilter include the TCP sequence number in the log entry | | --ulog-qthreshold <''value''> |Queue ''value'' packets before sending them to ''ulogd'' (default = 1, max = 50) |- |} <br> For completeness, we here reproduce the list of logging levels that ''log'' understands: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Level !style="background:#ffdead;"|Description |- |0 |''emerg'' or ''panic'' |- |1 |''alert'' |- |2 |''crit'' |- |3 |''err'' |- |4 |''warn'' (default) |- |5 |''notice'' |- |6 |''info'' |- |7 |''debug'' |- |} Now an example: context "INPUT" "filter" log lvl info msg SSH_incoming -p tcp --dport 22 -i $inetIF Iceditch works this out into iptables -A INPUT -t filter -p tcp --dport 22 -i $inetIF --jump ULOG --ulog-prefix "SSH_incoming" --log-level 6 == Target keyword: mark == '''''mark <markval> [log [msg <message>]] <qualifiers>'''''<br> If a packet matches the qualifiers, then it will be marked with the <markval> specified. An example from the context “PREROUTING” “mangle”: mark 2 –p tcp --dport 22 Iceditch works this out to iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump MARK --setmark 2 Should you want to also log the packet, you’d use mark 2 log –p tcp --dport 22 Iceditch works this out to iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump LOG \ --log-prefix PREROUTING_MARK_set_2: iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump MARK --setmark 2 Because of how iptables handles the MARK target, you can only use it in contexts where the table is “mangle”. == Target keyword: redirect == '''''redirect [to <to-ports>] [log [msg <message>]] <qualifiers>'''''<br> If a packet matches the qualifiers, then it will be redirected to the local machine, by setting the destination IP to a fitting IP address of the local machine (i.e. 127.0.0.1, or the first-bound IP address of the interface over which it came in. Additionally, by specifying “to <to-ports>” you can have the destination ports redirected to a port or portrange. <to-ports> can either be a port number (e.g. 8080) or a port range (e.g. 6661-6669; the latter is inclusive). Example for a transparent HTTP proxy: context "OUTPUT" "nat" redirect to 8080 –p tcp --dport 80 Iceditch works this out to iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump REDIRECT –to-ports 8080 Should you want to log the packet, you could use redirect to 8080 log –p tcp --dport 80 Iceditch works this out to iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump LOG \ --log-prefix OUTPUT_REDIRECT_to_8080: iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump REDIRECT –-to-ports 8080 Because of how iptables handles the REDIRECT target, you can only use it in contexts where the table is “nat” and the chain is PREROUTING or OUTPUT. == Target keyword: reject == '''''reject [with <type>] [log [msg <message>]] <qualifiers>'''''<br> In essence, this does the same as the “drop” target keyword, only it jumps to REJECT instead of DROP. This means the packet is discarded (just as with DROP), but the sender is notified using ICMP (by default, your machine will send an ICMP-packet of type "icmp-port-unreachable"). Because of how iptables handles the REJECT target, you can only use it in contexts where the table is “filter”. Optionally, you can follow “reject” with the keyword “with”, and then use one of the following rejection types: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Type !style="background:#ffdead;"|Description |- | icmp-host-prohibited | will send an ICMP-message "host prohibited" |- | icmp-host-unreachable | will send an ICMP-message "host unreachable" |- | icmp-net-prohibited | will send an ICMP-message "net prohibited" |- | icmp-net-unreachable | will send an ICMP-message "net unreachable" |- | icmp-port-unreachable | DEFAULT; will send an ICMP-message "port unreachable" |- | icmp-proto-unreachable | DEFAULT; will send an ICMP-message "protocol unreachable" |- | tcp-reset | will send a TCP reset, a packet with the RST flag set (as a response to a TCP packet only) |- | host-prohib | synonymous to icmp-host-prohibited |- | host-unreach | synonymous to icmp-host-unreachable |- | net-prohib | synonymous to icmp-net-prohibited |- | net-unreach | synonymous to icmp-net-unreachable |- | port-unreach | synonymous to icmp-port-unreachable |- | proto-unreach | synonymous to icmp-proto-unreachable |- |} If you don’t specify “with <type>”, then netfilter will assume icmp-port-unreachable. Thus, should you want to reject a packet in context filter_INPUT (and log it) with reason net-prohib, you’d use reject with net-prohib log –p tcp –i eth0 --dport 22 Iceditch works this out to iptables –t filter –A INPUT –p tcp –i eth0 –-dport 22 –-jump LOG \ --log-prefix INPUT_REJECT_with_net-prohib: iptables –t filter –A INPUT –p tcp –i eth0 –-dport 22 \ –-jump REJECT –-reject-with net-prohib –p tcp –i eth0 –-dport 22 == Target keyword: snat== '''''snat [to <a1[-a2][:p1-p2]]> [to <a3[-a4][:p3-p4]]>] ] [log [msg <message>] ] <qualifiers>'''''<br> This keyword is only valid in the chain POSTROUTING, table nat. And ofcourse, source NATting does you little good if you haven't enabled forwarding (e.g. use this machine as a router for other machines on your network).<br> Calling snat with the right parameters will create a Source NATting rule for you, whereby a packet matching the qualifiers will be source NATted using the source IP address ''a1'' (or the range ''a1-a2''). Ofcourse, ''a1[-a2]'' should be valid IP address(es) of the firewalling machine.<br> Furthermore, if a port range ''p1-p2'' is specified, then you'll limit the range of ports that ''snat'' will use outbound (only valid for TCP or UDP packets).<br> Finally, it is possible to specify ''multiple'' IP address ranges and port ranges, using multiple ''to <a1[-a2][:p1-p2]]'' declarations in succession.<br> An example would be: context "POSTROUTING" "nat" snat to $inetIP -o $inetIF ! --src $inetIP If the variable ''$inetIP'' contains your public IP (e.g. 212.238.151.72), and ''$inetIF'' your interface connected to the Internet (e.g. ''eth0''), then this rule would expand to iptables -A POSTROUTING -t nat -o eth0 ! --src 212.238.151.72 -j SNAT --to-source 212.238.151.72 This would cause Iceditch to source NAT any outbound packet that is NOT sent by your firewall itself; in effect your server is now a nice fullblown NAT router for all machines on your private network. ac31c74f25109c60bb0be96bb1e072f0d176c778 1596 1595 2008-08-04T20:36:53Z Saruman! 2 /* Context keyword: context */ typo's wikitext text/x-wiki == Parameter: log == ''target '''log [msg <message>]''' <qualifiers>''<br> After most keywords, a "log" parameter can be added (see below). If the "log" parameter is followed by "msg", then the parameter following "msg" is read and used as log-prefix. The parameter is not allowed to have whitespace, and the maximum length of the log-prefix is determined by your version of netfilter/IPtables (usually some 31 characters). Thus a packet matching the rule will be logged with the default setting of the "log" target. If the "log" parameter is ''not'' followed by "msg", then the packet will be logged with the default log message for that particular target keyword, and all the other default setting of the "log" target. Thus, should you want to log a packet with more control over the logging parameters, then you need an extra line, beginning with the ''target keyword'' "log", instead of just following the target keyword with parameter ''log''. For more information, see the target keyword "log" below. == Context keyword: context == '''''context <chain> &lt;table&gt;'''''<br> Every IPtables rule is written to a chain in a table; with Iceditch, you don't have to specify the chain and table in every line. Just precede the lines with the ''context'' statement. Example: context POSTROUTING nat Notes: the order of chain and table does not matter; ''context nat POSTROUTING'' works just as well. Furthermore, <chain> and &lt;table&gt; have been made case-insensitive; whatever you specify as chain will be translated to uppercase, whatever you specify as table will be translated to lowercase. This gives you the possibility to write the context as you like to read it, e.g. ''context Postrouting Nat''; after processing this, Iceditch will have two variables $CHAIN="POSTROUTING" and $TABLE="nat" that it will use in every following command. For example: context "Input" "fIlTeR" accept -p tcp --dport 22 will result in the following IPtables call: iptables -A INPUT -t filter -p tcp --dport 22 --jump ACCEPT If you do NOT specify a [[Iceditch IPtables language | valid combination]] of chain and table, the execution of Iceditch will halt with a fatal error. It is allowed (but not recommended) to call ''context'' multiple times for the same combination of chain and table; the order in which the rules are added to that chain in that table, is the same in which they appear in your rulefile, top to bottom. This is not recommended, because we feel it decreases readability, and thus maintainability, of the rules file. But hey, it's going to be ''your'' rulefile anyway... == Target keyword: accept == '''''accept [log [msg <message>]] <qualifiers>'''''<br> If a network packet matches the qualifiers, then it will be accepted (passed) through the table/chain defined in the context where you put the accept rule. Example: <pre>context "INPUT" "filter" accept –p tcp --dport 22</pre> Iceditch works this out to iptables –t filter –A INPUT –p tcp –-dport 22 –-jump ACCEPT Should you want to log the packet, you’d use context "INPUT" "filter" accept log –p tcp --dport 22 Iceditch works this out to iptables –t filter –A INPUT –p tcp –-dport 22 \ –-jump LOG --log-prefix INPUT_accept iptables –t filter –A INPUT –p tcp –-dport 22 –-jump ACCEPT Note: the ACCEPT target is valid in any user-manipulable table/chain combination == Target keyword: classify == '''''classify <classval> [log [msg <message>]] <qualifiers>'''''<br> If a packet travelling through the mangle table in the POSTROUTING chain matches the qualifiers, then it will be classified with the <classval> specified. An example: classify 2:11 –p tcp --dport 22 The script works this out to iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump CLASSIFY --setclass 2:11 Should you want to also log the packet, you’d use classify 2:11 log –p tcp --dport 22 The script works this out to iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump LOG \ --log-prefix classified_2:11: iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump CLASSIFY \ --setclass 2:11 Should you not give a msg, then the log-prefix becomes POSTROUTING_CLASSIFY_set_<classval>. Because of how iptables handles the CLASSIFY target, you can only use it in contexts where the chain is “POSTROUTING” and the table is “mangle”. == Target keyword: drop == '''''drop [log [msg <message>]] <qualifiers> '''''<br> In essence, this does the same as the “accept” target keyword, only it jumps to DROP instead of ACCEPT. Thus any packet matching the qualifiers gets discarded; it will not get sent on to its final destination (or next hop), it will not get processed by any other firewall rule, and the sender of the packet is unaware of your treatment of his packet. Should you want to also log the packet, you’d use context "FORWARD" "filter" drop log –p tcp -s 10.0.0.0/16 The script works this out to iptables –t filter –A FORWARD –p tcp -s 10.0.0.0/16 –-jump LOG \ --log-prefix FORWARD_DROP: iptables –t filter –A FORWARD –p tcp -s 10.0.0.0/16 –-jump DROP Because of how iptables handles the DROP target, you can only use it in contexts where the table is “filter”. == Target keyword: log == '''''log [msg <message>] [lvl <loglevel>] <qualifiers>'''''<br> Sometimes, the standard ''log'' parameter is just not enough. This is mostly the case when you want to log a packet to a log-level other than the default level, which for most systems is ''4'' (''warning''). Furthermore, maybe you want to log a certain type or class of packets, without performing an action on those packets just yet. For this reason, AND for flexibility and clarity, Iceditch has the dedicated target keyword ''log''.<br> Just as when you use the ''log'' parameter, Iceditch will call the log target specified in the Iceditch [[Iceditch file structure | config file]]. Standard this is LOG, but optionally you could specify ULOG in the config file. ''<message>'' can be any string of 32 characters max (letters, numbers and underscores; no spaces); the ''<loglevel>'' can either be numeric or the corresponding keyword (e.g. ''crit''); Iceditch translates it to its numeric value anyway. Furthermore, the order in which <msg> and <lvl> appear is not important.<br> Depending on which log target you have specified, there are some options you can use with the Iceditch target keyword ''log''; it is currently deemed unnecessary to make specific Iceditch parameters for them, but as a reference we'll list the official IPtables options here, which you can put in the <qualifiers> list: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" ! colspan="2" style="background:#ffdead;"|LOG options | ! colspan="2" style="background:#ffdead;"|ULOG options |- !style="background:#ffdead;"|Option !style="background:#ffdead;"|Description | !style="background:#ffdead;"|Option !style="background:#ffdead;"|Description |- | --log-ip-options |Makes Netfilter include the IP options in the log entry | | --ulog-cprange <''size''> |log the first ''size'' bytes of each packet |- | --log-tcp-options |Makes Netfilter include the TCP options in the log entry | | --ulog-nlgroup <''nlgroup''> |Log to Netlink group number ''nlgroup'' (must match ''/etc/ulogd.conf'') |- | --log-tcp-sequence |Makes Netfilter include the TCP sequence number in the log entry | | --ulog-qthreshold <''value''> |Queue ''value'' packets before sending them to ''ulogd'' (default = 1, max = 50) |- |} <br> For completeness, we here reproduce the list of logging levels that ''log'' understands: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Level !style="background:#ffdead;"|Description |- |0 |''emerg'' or ''panic'' |- |1 |''alert'' |- |2 |''crit'' |- |3 |''err'' |- |4 |''warn'' (default) |- |5 |''notice'' |- |6 |''info'' |- |7 |''debug'' |- |} Now an example: context "INPUT" "filter" log lvl info msg SSH_incoming -p tcp --dport 22 -i $inetIF Iceditch works this out into iptables -A INPUT -t filter -p tcp --dport 22 -i $inetIF --jump ULOG --ulog-prefix "SSH_incoming" --log-level 6 == Target keyword: mark == '''''mark <markval> [log [msg <message>]] <qualifiers>'''''<br> If a packet matches the qualifiers, then it will be marked with the <markval> specified. An example from the context “PREROUTING” “mangle”: mark 2 –p tcp --dport 22 Iceditch works this out to iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump MARK --setmark 2 Should you want to also log the packet, you’d use mark 2 log –p tcp --dport 22 Iceditch works this out to iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump LOG \ --log-prefix PREROUTING_MARK_set_2: iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump MARK --setmark 2 Because of how iptables handles the MARK target, you can only use it in contexts where the table is “mangle”. == Target keyword: redirect == '''''redirect [to <to-ports>] [log [msg <message>]] <qualifiers>'''''<br> If a packet matches the qualifiers, then it will be redirected to the local machine, by setting the destination IP to a fitting IP address of the local machine (i.e. 127.0.0.1, or the first-bound IP address of the interface over which it came in. Additionally, by specifying “to <to-ports>” you can have the destination ports redirected to a port or portrange. <to-ports> can either be a port number (e.g. 8080) or a port range (e.g. 6661-6669; the latter is inclusive). Example for a transparent HTTP proxy: context "OUTPUT" "nat" redirect to 8080 –p tcp --dport 80 Iceditch works this out to iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump REDIRECT –to-ports 8080 Should you want to log the packet, you could use redirect to 8080 log –p tcp --dport 80 Iceditch works this out to iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump LOG \ --log-prefix OUTPUT_REDIRECT_to_8080: iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump REDIRECT –-to-ports 8080 Because of how iptables handles the REDIRECT target, you can only use it in contexts where the table is “nat” and the chain is PREROUTING or OUTPUT. == Target keyword: reject == '''''reject [with <type>] [log [msg <message>]] <qualifiers>'''''<br> In essence, this does the same as the “drop” target keyword, only it jumps to REJECT instead of DROP. This means the packet is discarded (just as with DROP), but the sender is notified using ICMP (by default, your machine will send an ICMP-packet of type "icmp-port-unreachable"). Because of how iptables handles the REJECT target, you can only use it in contexts where the table is “filter”. Optionally, you can follow “reject” with the keyword “with”, and then use one of the following rejection types: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Type !style="background:#ffdead;"|Description |- | icmp-host-prohibited | will send an ICMP-message "host prohibited" |- | icmp-host-unreachable | will send an ICMP-message "host unreachable" |- | icmp-net-prohibited | will send an ICMP-message "net prohibited" |- | icmp-net-unreachable | will send an ICMP-message "net unreachable" |- | icmp-port-unreachable | DEFAULT; will send an ICMP-message "port unreachable" |- | icmp-proto-unreachable | DEFAULT; will send an ICMP-message "protocol unreachable" |- | tcp-reset | will send a TCP reset, a packet with the RST flag set (as a response to a TCP packet only) |- | host-prohib | synonymous to icmp-host-prohibited |- | host-unreach | synonymous to icmp-host-unreachable |- | net-prohib | synonymous to icmp-net-prohibited |- | net-unreach | synonymous to icmp-net-unreachable |- | port-unreach | synonymous to icmp-port-unreachable |- | proto-unreach | synonymous to icmp-proto-unreachable |- |} If you don’t specify “with <type>”, then netfilter will assume icmp-port-unreachable. Thus, should you want to reject a packet in context filter_INPUT (and log it) with reason net-prohib, you’d use reject with net-prohib log –p tcp –i eth0 --dport 22 Iceditch works this out to iptables –t filter –A INPUT –p tcp –i eth0 –-dport 22 –-jump LOG \ --log-prefix INPUT_REJECT_with_net-prohib: iptables –t filter –A INPUT –p tcp –i eth0 –-dport 22 \ –-jump REJECT –-reject-with net-prohib –p tcp –i eth0 –-dport 22 == Target keyword: snat== '''''snat [to <a1[-a2][:p1-p2]]> [to <a3[-a4][:p3-p4]]>] ] [log [msg <message>] ] <qualifiers>'''''<br> This keyword is only valid in the chain POSTROUTING, table nat. And ofcourse, source NATting does you little good if you haven't enabled forwarding (e.g. use this machine as a router for other machines on your network).<br> Calling snat with the right parameters will create a Source NATting rule for you, whereby a packet matching the qualifiers will be source NATted using the source IP address ''a1'' (or the range ''a1-a2''). Ofcourse, ''a1[-a2]'' should be valid IP address(es) of the firewalling machine.<br> Furthermore, if a port range ''p1-p2'' is specified, then you'll limit the range of ports that ''snat'' will use outbound (only valid for TCP or UDP packets).<br> Finally, it is possible to specify ''multiple'' IP address ranges and port ranges, using multiple ''to <a1[-a2][:p1-p2]]'' declarations in succession.<br> An example would be: context "POSTROUTING" "nat" snat to $inetIP -o $inetIF ! --src $inetIP If the variable ''$inetIP'' contains your public IP (e.g. 212.238.151.72), and ''$inetIF'' your interface connected to the Internet (e.g. ''eth0''), then this rule would expand to iptables -A POSTROUTING -t nat -o eth0 ! --src 212.238.151.72 -j SNAT --to-source 212.238.151.72 This would cause Iceditch to source NAT any outbound packet that is NOT sent by your firewall itself; in effect your server is now a nice fullblown NAT router for all machines on your private network. ed3b936386214de550c1128ebe60b26106fa6fbb 1597 1596 2008-08-05T08:38:06Z Saruman! 2 /* Context keyword: create_chain */ added wikitext text/x-wiki == Parameter: log == ''target '''log [msg <message>]''' <qualifiers>''<br> After most keywords, a "log" parameter can be added (see below). If the "log" parameter is followed by "msg", then the parameter following "msg" is read and used as log-prefix. The parameter is not allowed to have whitespace, and the maximum length of the log-prefix is determined by your version of netfilter/IPtables (usually some 31 characters). Thus a packet matching the rule will be logged with the default setting of the "log" target. If the "log" parameter is ''not'' followed by "msg", then the packet will be logged with the default log message for that particular target keyword, and all the other default setting of the "log" target. Thus, should you want to log a packet with more control over the logging parameters, then you need an extra line, beginning with the ''target keyword'' "log", instead of just following the target keyword with parameter ''log''. For more information, see the target keyword "log" below. == Context keyword: context == '''''context <chain> &lt;table&gt;'''''<br> Every IPtables rule is written to a chain in a table; with Iceditch, you don't have to specify the chain and table in every line. Just precede the lines with the ''context'' statement. Example: context POSTROUTING nat Notes: the order of chain and table does not matter; ''context nat POSTROUTING'' works just as well. Furthermore, <chain> and &lt;table&gt; have been made case-insensitive; whatever you specify as chain will be translated to uppercase, whatever you specify as table will be translated to lowercase. This gives you the possibility to write the context as you like to read it, e.g. ''context Postrouting Nat''; after processing this, Iceditch will have two variables $CHAIN="POSTROUTING" and $TABLE="nat" that it will use in every following command. For example: context "Input" "fIlTeR" accept -p tcp --dport 22 will result in the following IPtables call: iptables -A INPUT -t filter -p tcp --dport 22 --jump ACCEPT If you do NOT specify a [[Iceditch IPtables language | valid combination]] of chain and table, the execution of Iceditch will halt with a fatal error. It is allowed (but not recommended) to call ''context'' multiple times for the same combination of chain and table; the order in which the rules are added to that chain in that table, is the same in which they appear in your rulefile, top to bottom. This is not recommended, because we feel it decreases readability, and thus maintainability, of the rules file. But hey, it's going to be ''your'' rulefile anyway... == Context keyword: create_chain == '''''create_chain <chain> [&lt;table&gt;]'''''<br> This command creates a new chain named <chain>, in the specified table &lt;table&gt;. If no table is specified, then the ''filter'' table is assumed. Just as with the ''context'' command, the <chain> name you specify will be translated to all uppercase.<br> The name for your new chain must be unique, i.e. unlike the built-in chains, you can't specify the same name in different tables. If you create "fun-filter" in table ''filter'', then you're not allowed to also create a "fun-filter" in table ''nat''.<br> NOTE: after you've run ''create_chain'', you still have to switch context to create rules in the new chain! example:<br> create_chain fun-filter context fun-filter filter accept -p tcp --dport 22 This will result in iptables -N FUN-FILTER -t filter iptables -A FUN-FILTER -t filter -p tcp --dport 22 --jump ACCEPT == Target keyword: accept == '''''accept [log [msg <message>]] <qualifiers>'''''<br> If a network packet matches the qualifiers, then it will be accepted (passed) through the table/chain defined in the context where you put the accept rule. Example: <pre>context "INPUT" "filter" accept –p tcp --dport 22</pre> Iceditch works this out to iptables –t filter –A INPUT –p tcp –-dport 22 –-jump ACCEPT Should you want to log the packet, you’d use context "INPUT" "filter" accept log –p tcp --dport 22 Iceditch works this out to iptables –t filter –A INPUT –p tcp –-dport 22 \ –-jump LOG --log-prefix INPUT_accept iptables –t filter –A INPUT –p tcp –-dport 22 –-jump ACCEPT Note: the ACCEPT target is valid in any user-manipulable table/chain combination == Target keyword: classify == '''''classify <classval> [log [msg <message>]] <qualifiers>'''''<br> If a packet travelling through the mangle table in the POSTROUTING chain matches the qualifiers, then it will be classified with the <classval> specified. An example: classify 2:11 –p tcp --dport 22 The script works this out to iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump CLASSIFY --setclass 2:11 Should you want to also log the packet, you’d use classify 2:11 log –p tcp --dport 22 The script works this out to iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump LOG \ --log-prefix classified_2:11: iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump CLASSIFY \ --setclass 2:11 Should you not give a msg, then the log-prefix becomes POSTROUTING_CLASSIFY_set_<classval>. Because of how iptables handles the CLASSIFY target, you can only use it in contexts where the chain is “POSTROUTING” and the table is “mangle”. == Target keyword: drop == '''''drop [log [msg <message>]] <qualifiers> '''''<br> In essence, this does the same as the “accept” target keyword, only it jumps to DROP instead of ACCEPT. Thus any packet matching the qualifiers gets discarded; it will not get sent on to its final destination (or next hop), it will not get processed by any other firewall rule, and the sender of the packet is unaware of your treatment of his packet. Should you want to also log the packet, you’d use context "FORWARD" "filter" drop log –p tcp -s 10.0.0.0/16 The script works this out to iptables –t filter –A FORWARD –p tcp -s 10.0.0.0/16 –-jump LOG \ --log-prefix FORWARD_DROP: iptables –t filter –A FORWARD –p tcp -s 10.0.0.0/16 –-jump DROP Because of how iptables handles the DROP target, you can only use it in contexts where the table is “filter”. == Target keyword: log == '''''log [msg <message>] [lvl <loglevel>] <qualifiers>'''''<br> Sometimes, the standard ''log'' parameter is just not enough. This is mostly the case when you want to log a packet to a log-level other than the default level, which for most systems is ''4'' (''warning''). Furthermore, maybe you want to log a certain type or class of packets, without performing an action on those packets just yet. For this reason, AND for flexibility and clarity, Iceditch has the dedicated target keyword ''log''.<br> Just as when you use the ''log'' parameter, Iceditch will call the log target specified in the Iceditch [[Iceditch file structure | config file]]. Standard this is LOG, but optionally you could specify ULOG in the config file. ''<message>'' can be any string of 32 characters max (letters, numbers and underscores; no spaces); the ''<loglevel>'' can either be numeric or the corresponding keyword (e.g. ''crit''); Iceditch translates it to its numeric value anyway. Furthermore, the order in which <msg> and <lvl> appear is not important.<br> Depending on which log target you have specified, there are some options you can use with the Iceditch target keyword ''log''; it is currently deemed unnecessary to make specific Iceditch parameters for them, but as a reference we'll list the official IPtables options here, which you can put in the <qualifiers> list: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" ! colspan="2" style="background:#ffdead;"|LOG options | ! colspan="2" style="background:#ffdead;"|ULOG options |- !style="background:#ffdead;"|Option !style="background:#ffdead;"|Description | !style="background:#ffdead;"|Option !style="background:#ffdead;"|Description |- | --log-ip-options |Makes Netfilter include the IP options in the log entry | | --ulog-cprange <''size''> |log the first ''size'' bytes of each packet |- | --log-tcp-options |Makes Netfilter include the TCP options in the log entry | | --ulog-nlgroup <''nlgroup''> |Log to Netlink group number ''nlgroup'' (must match ''/etc/ulogd.conf'') |- | --log-tcp-sequence |Makes Netfilter include the TCP sequence number in the log entry | | --ulog-qthreshold <''value''> |Queue ''value'' packets before sending them to ''ulogd'' (default = 1, max = 50) |- |} <br> For completeness, we here reproduce the list of logging levels that ''log'' understands: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Level !style="background:#ffdead;"|Description |- |0 |''emerg'' or ''panic'' |- |1 |''alert'' |- |2 |''crit'' |- |3 |''err'' |- |4 |''warn'' (default) |- |5 |''notice'' |- |6 |''info'' |- |7 |''debug'' |- |} Now an example: context "INPUT" "filter" log lvl info msg SSH_incoming -p tcp --dport 22 -i $inetIF Iceditch works this out into iptables -A INPUT -t filter -p tcp --dport 22 -i $inetIF --jump ULOG --ulog-prefix "SSH_incoming" --log-level 6 == Target keyword: mark == '''''mark <markval> [log [msg <message>]] <qualifiers>'''''<br> If a packet matches the qualifiers, then it will be marked with the <markval> specified. An example from the context “PREROUTING” “mangle”: mark 2 –p tcp --dport 22 Iceditch works this out to iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump MARK --setmark 2 Should you want to also log the packet, you’d use mark 2 log –p tcp --dport 22 Iceditch works this out to iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump LOG \ --log-prefix PREROUTING_MARK_set_2: iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump MARK --setmark 2 Because of how iptables handles the MARK target, you can only use it in contexts where the table is “mangle”. == Target keyword: redirect == '''''redirect [to <to-ports>] [log [msg <message>]] <qualifiers>'''''<br> If a packet matches the qualifiers, then it will be redirected to the local machine, by setting the destination IP to a fitting IP address of the local machine (i.e. 127.0.0.1, or the first-bound IP address of the interface over which it came in. Additionally, by specifying “to <to-ports>” you can have the destination ports redirected to a port or portrange. <to-ports> can either be a port number (e.g. 8080) or a port range (e.g. 6661-6669; the latter is inclusive). Example for a transparent HTTP proxy: context "OUTPUT" "nat" redirect to 8080 –p tcp --dport 80 Iceditch works this out to iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump REDIRECT –to-ports 8080 Should you want to log the packet, you could use redirect to 8080 log –p tcp --dport 80 Iceditch works this out to iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump LOG \ --log-prefix OUTPUT_REDIRECT_to_8080: iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump REDIRECT –-to-ports 8080 Because of how iptables handles the REDIRECT target, you can only use it in contexts where the table is “nat” and the chain is PREROUTING or OUTPUT. == Target keyword: reject == '''''reject [with <type>] [log [msg <message>]] <qualifiers>'''''<br> In essence, this does the same as the “drop” target keyword, only it jumps to REJECT instead of DROP. This means the packet is discarded (just as with DROP), but the sender is notified using ICMP (by default, your machine will send an ICMP-packet of type "icmp-port-unreachable"). Because of how iptables handles the REJECT target, you can only use it in contexts where the table is “filter”. Optionally, you can follow “reject” with the keyword “with”, and then use one of the following rejection types: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Type !style="background:#ffdead;"|Description |- | icmp-host-prohibited | will send an ICMP-message "host prohibited" |- | icmp-host-unreachable | will send an ICMP-message "host unreachable" |- | icmp-net-prohibited | will send an ICMP-message "net prohibited" |- | icmp-net-unreachable | will send an ICMP-message "net unreachable" |- | icmp-port-unreachable | DEFAULT; will send an ICMP-message "port unreachable" |- | icmp-proto-unreachable | DEFAULT; will send an ICMP-message "protocol unreachable" |- | tcp-reset | will send a TCP reset, a packet with the RST flag set (as a response to a TCP packet only) |- | host-prohib | synonymous to icmp-host-prohibited |- | host-unreach | synonymous to icmp-host-unreachable |- | net-prohib | synonymous to icmp-net-prohibited |- | net-unreach | synonymous to icmp-net-unreachable |- | port-unreach | synonymous to icmp-port-unreachable |- | proto-unreach | synonymous to icmp-proto-unreachable |- |} If you don’t specify “with <type>”, then netfilter will assume icmp-port-unreachable. Thus, should you want to reject a packet in context filter_INPUT (and log it) with reason net-prohib, you’d use reject with net-prohib log –p tcp –i eth0 --dport 22 Iceditch works this out to iptables –t filter –A INPUT –p tcp –i eth0 –-dport 22 –-jump LOG \ --log-prefix INPUT_REJECT_with_net-prohib: iptables –t filter –A INPUT –p tcp –i eth0 –-dport 22 \ –-jump REJECT –-reject-with net-prohib –p tcp –i eth0 –-dport 22 == Target keyword: snat== '''''snat [to <a1[-a2][:p1-p2]]> [to <a3[-a4][:p3-p4]]>] ] [log [msg <message>] ] <qualifiers>'''''<br> This keyword is only valid in the chain POSTROUTING, table nat. And ofcourse, source NATting does you little good if you haven't enabled forwarding (e.g. use this machine as a router for other machines on your network).<br> Calling snat with the right parameters will create a Source NATting rule for you, whereby a packet matching the qualifiers will be source NATted using the source IP address ''a1'' (or the range ''a1-a2''). Ofcourse, ''a1[-a2]'' should be valid IP address(es) of the firewalling machine.<br> Furthermore, if a port range ''p1-p2'' is specified, then you'll limit the range of ports that ''snat'' will use outbound (only valid for TCP or UDP packets).<br> Finally, it is possible to specify ''multiple'' IP address ranges and port ranges, using multiple ''to <a1[-a2][:p1-p2]]'' declarations in succession.<br> An example would be: context "POSTROUTING" "nat" snat to $inetIP -o $inetIF ! --src $inetIP If the variable ''$inetIP'' contains your public IP (e.g. 212.238.151.72), and ''$inetIF'' your interface connected to the Internet (e.g. ''eth0''), then this rule would expand to iptables -A POSTROUTING -t nat -o eth0 ! --src 212.238.151.72 -j SNAT --to-source 212.238.151.72 This would cause Iceditch to source NAT any outbound packet that is NOT sent by your firewall itself; in effect your server is now a nice fullblown NAT router for all machines on your private network. 7fbc0fe556eb8702ceea7a64f36c0358c23b5679 1598 1597 2008-08-05T13:09:27Z Saruman! 2 /* Context keyword: create_chain */ changed chain creation in different tables wikitext text/x-wiki == Parameter: log == ''target '''log [msg <message>]''' <qualifiers>''<br> After most keywords, a "log" parameter can be added (see below). If the "log" parameter is followed by "msg", then the parameter following "msg" is read and used as log-prefix. The parameter is not allowed to have whitespace, and the maximum length of the log-prefix is determined by your version of netfilter/IPtables (usually some 31 characters). Thus a packet matching the rule will be logged with the default setting of the "log" target. If the "log" parameter is ''not'' followed by "msg", then the packet will be logged with the default log message for that particular target keyword, and all the other default setting of the "log" target. Thus, should you want to log a packet with more control over the logging parameters, then you need an extra line, beginning with the ''target keyword'' "log", instead of just following the target keyword with parameter ''log''. For more information, see the target keyword "log" below. == Context keyword: context == '''''context <chain> &lt;table&gt;'''''<br> Every IPtables rule is written to a chain in a table; with Iceditch, you don't have to specify the chain and table in every line. Just precede the lines with the ''context'' statement. Example: context POSTROUTING nat Notes: the order of chain and table does not matter; ''context nat POSTROUTING'' works just as well. Furthermore, <chain> and &lt;table&gt; have been made case-insensitive; whatever you specify as chain will be translated to uppercase, whatever you specify as table will be translated to lowercase. This gives you the possibility to write the context as you like to read it, e.g. ''context Postrouting Nat''; after processing this, Iceditch will have two variables $CHAIN="POSTROUTING" and $TABLE="nat" that it will use in every following command. For example: context "Input" "fIlTeR" accept -p tcp --dport 22 will result in the following IPtables call: iptables -A INPUT -t filter -p tcp --dport 22 --jump ACCEPT If you do NOT specify a [[Iceditch IPtables language | valid combination]] of chain and table, the execution of Iceditch will halt with a fatal error. It is allowed (but not recommended) to call ''context'' multiple times for the same combination of chain and table; the order in which the rules are added to that chain in that table, is the same in which they appear in your rulefile, top to bottom. This is not recommended, because we feel it decreases readability, and thus maintainability, of the rules file. But hey, it's going to be ''your'' rulefile anyway... == Context keyword: create_chain == '''''create_chain <chain> [&lt;table&gt;]'''''<br> This command creates a new chain named <chain>, in the specified table &lt;table&gt;. If no table is specified, then the ''filter'' table is assumed. Just as with the ''context'' command, the <chain> name you specify will be translated to all uppercase.<br> The name for your new chain must be unique, although just like the built-in chains, you can specify the same name in different tables. If you create "fun-filter" in table ''filter'', and then create a "fun-filter" in table ''nat'', then you actually have two different chains. But remember: since Iceditch translates every chain name to uppercase, you can't create "Fun-filter" AND "fun-FILTER" in the same table - they're the same chain.<br> NOTE: after you've run ''create_chain'', you still have to switch context to create rules in the new chain! example:<br> create_chain fun-filter context fun-filter filter accept -p tcp --dport 22 This will result in iptables -N FUN-FILTER -t filter iptables -A FUN-FILTER -t filter -p tcp --dport 22 --jump ACCEPT == Target keyword: accept == '''''accept [log [msg <message>]] <qualifiers>'''''<br> If a network packet matches the qualifiers, then it will be accepted (passed) through the table/chain defined in the context where you put the accept rule. Example: <pre>context "INPUT" "filter" accept –p tcp --dport 22</pre> Iceditch works this out to iptables –t filter –A INPUT –p tcp –-dport 22 –-jump ACCEPT Should you want to log the packet, you’d use context "INPUT" "filter" accept log –p tcp --dport 22 Iceditch works this out to iptables –t filter –A INPUT –p tcp –-dport 22 \ –-jump LOG --log-prefix INPUT_accept iptables –t filter –A INPUT –p tcp –-dport 22 –-jump ACCEPT Note: the ACCEPT target is valid in any user-manipulable table/chain combination == Target keyword: classify == '''''classify <classval> [log [msg <message>]] <qualifiers>'''''<br> If a packet travelling through the mangle table in the POSTROUTING chain matches the qualifiers, then it will be classified with the <classval> specified. An example: classify 2:11 –p tcp --dport 22 The script works this out to iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump CLASSIFY --setclass 2:11 Should you want to also log the packet, you’d use classify 2:11 log –p tcp --dport 22 The script works this out to iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump LOG \ --log-prefix classified_2:11: iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump CLASSIFY \ --setclass 2:11 Should you not give a msg, then the log-prefix becomes POSTROUTING_CLASSIFY_set_<classval>. Because of how iptables handles the CLASSIFY target, you can only use it in contexts where the chain is “POSTROUTING” and the table is “mangle”. == Target keyword: drop == '''''drop [log [msg <message>]] <qualifiers> '''''<br> In essence, this does the same as the “accept” target keyword, only it jumps to DROP instead of ACCEPT. Thus any packet matching the qualifiers gets discarded; it will not get sent on to its final destination (or next hop), it will not get processed by any other firewall rule, and the sender of the packet is unaware of your treatment of his packet. Should you want to also log the packet, you’d use context "FORWARD" "filter" drop log –p tcp -s 10.0.0.0/16 The script works this out to iptables –t filter –A FORWARD –p tcp -s 10.0.0.0/16 –-jump LOG \ --log-prefix FORWARD_DROP: iptables –t filter –A FORWARD –p tcp -s 10.0.0.0/16 –-jump DROP Because of how iptables handles the DROP target, you can only use it in contexts where the table is “filter”. == Target keyword: log == '''''log [msg <message>] [lvl <loglevel>] <qualifiers>'''''<br> Sometimes, the standard ''log'' parameter is just not enough. This is mostly the case when you want to log a packet to a log-level other than the default level, which for most systems is ''4'' (''warning''). Furthermore, maybe you want to log a certain type or class of packets, without performing an action on those packets just yet. For this reason, AND for flexibility and clarity, Iceditch has the dedicated target keyword ''log''.<br> Just as when you use the ''log'' parameter, Iceditch will call the log target specified in the Iceditch [[Iceditch file structure | config file]]. Standard this is LOG, but optionally you could specify ULOG in the config file. ''<message>'' can be any string of 32 characters max (letters, numbers and underscores; no spaces); the ''<loglevel>'' can either be numeric or the corresponding keyword (e.g. ''crit''); Iceditch translates it to its numeric value anyway. Furthermore, the order in which <msg> and <lvl> appear is not important.<br> Depending on which log target you have specified, there are some options you can use with the Iceditch target keyword ''log''; it is currently deemed unnecessary to make specific Iceditch parameters for them, but as a reference we'll list the official IPtables options here, which you can put in the <qualifiers> list: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" ! colspan="2" style="background:#ffdead;"|LOG options | ! colspan="2" style="background:#ffdead;"|ULOG options |- !style="background:#ffdead;"|Option !style="background:#ffdead;"|Description | !style="background:#ffdead;"|Option !style="background:#ffdead;"|Description |- | --log-ip-options |Makes Netfilter include the IP options in the log entry | | --ulog-cprange <''size''> |log the first ''size'' bytes of each packet |- | --log-tcp-options |Makes Netfilter include the TCP options in the log entry | | --ulog-nlgroup <''nlgroup''> |Log to Netlink group number ''nlgroup'' (must match ''/etc/ulogd.conf'') |- | --log-tcp-sequence |Makes Netfilter include the TCP sequence number in the log entry | | --ulog-qthreshold <''value''> |Queue ''value'' packets before sending them to ''ulogd'' (default = 1, max = 50) |- |} <br> For completeness, we here reproduce the list of logging levels that ''log'' understands: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Level !style="background:#ffdead;"|Description |- |0 |''emerg'' or ''panic'' |- |1 |''alert'' |- |2 |''crit'' |- |3 |''err'' |- |4 |''warn'' (default) |- |5 |''notice'' |- |6 |''info'' |- |7 |''debug'' |- |} Now an example: context "INPUT" "filter" log lvl info msg SSH_incoming -p tcp --dport 22 -i $inetIF Iceditch works this out into iptables -A INPUT -t filter -p tcp --dport 22 -i $inetIF --jump ULOG --ulog-prefix "SSH_incoming" --log-level 6 == Target keyword: mark == '''''mark <markval> [log [msg <message>]] <qualifiers>'''''<br> If a packet matches the qualifiers, then it will be marked with the <markval> specified. An example from the context “PREROUTING” “mangle”: mark 2 –p tcp --dport 22 Iceditch works this out to iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump MARK --setmark 2 Should you want to also log the packet, you’d use mark 2 log –p tcp --dport 22 Iceditch works this out to iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump LOG \ --log-prefix PREROUTING_MARK_set_2: iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump MARK --setmark 2 Because of how iptables handles the MARK target, you can only use it in contexts where the table is “mangle”. == Target keyword: redirect == '''''redirect [to <to-ports>] [log [msg <message>]] <qualifiers>'''''<br> If a packet matches the qualifiers, then it will be redirected to the local machine, by setting the destination IP to a fitting IP address of the local machine (i.e. 127.0.0.1, or the first-bound IP address of the interface over which it came in. Additionally, by specifying “to <to-ports>” you can have the destination ports redirected to a port or portrange. <to-ports> can either be a port number (e.g. 8080) or a port range (e.g. 6661-6669; the latter is inclusive). Example for a transparent HTTP proxy: context "OUTPUT" "nat" redirect to 8080 –p tcp --dport 80 Iceditch works this out to iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump REDIRECT –to-ports 8080 Should you want to log the packet, you could use redirect to 8080 log –p tcp --dport 80 Iceditch works this out to iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump LOG \ --log-prefix OUTPUT_REDIRECT_to_8080: iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump REDIRECT –-to-ports 8080 Because of how iptables handles the REDIRECT target, you can only use it in contexts where the table is “nat” and the chain is PREROUTING or OUTPUT. == Target keyword: reject == '''''reject [with <type>] [log [msg <message>]] <qualifiers>'''''<br> In essence, this does the same as the “drop” target keyword, only it jumps to REJECT instead of DROP. This means the packet is discarded (just as with DROP), but the sender is notified using ICMP (by default, your machine will send an ICMP-packet of type "icmp-port-unreachable"). Because of how iptables handles the REJECT target, you can only use it in contexts where the table is “filter”. Optionally, you can follow “reject” with the keyword “with”, and then use one of the following rejection types: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Type !style="background:#ffdead;"|Description |- | icmp-host-prohibited | will send an ICMP-message "host prohibited" |- | icmp-host-unreachable | will send an ICMP-message "host unreachable" |- | icmp-net-prohibited | will send an ICMP-message "net prohibited" |- | icmp-net-unreachable | will send an ICMP-message "net unreachable" |- | icmp-port-unreachable | DEFAULT; will send an ICMP-message "port unreachable" |- | icmp-proto-unreachable | DEFAULT; will send an ICMP-message "protocol unreachable" |- | tcp-reset | will send a TCP reset, a packet with the RST flag set (as a response to a TCP packet only) |- | host-prohib | synonymous to icmp-host-prohibited |- | host-unreach | synonymous to icmp-host-unreachable |- | net-prohib | synonymous to icmp-net-prohibited |- | net-unreach | synonymous to icmp-net-unreachable |- | port-unreach | synonymous to icmp-port-unreachable |- | proto-unreach | synonymous to icmp-proto-unreachable |- |} If you don’t specify “with <type>”, then netfilter will assume icmp-port-unreachable. Thus, should you want to reject a packet in context filter_INPUT (and log it) with reason net-prohib, you’d use reject with net-prohib log –p tcp –i eth0 --dport 22 Iceditch works this out to iptables –t filter –A INPUT –p tcp –i eth0 –-dport 22 –-jump LOG \ --log-prefix INPUT_REJECT_with_net-prohib: iptables –t filter –A INPUT –p tcp –i eth0 –-dport 22 \ –-jump REJECT –-reject-with net-prohib –p tcp –i eth0 –-dport 22 == Target keyword: snat== '''''snat [to <a1[-a2][:p1-p2]]> [to <a3[-a4][:p3-p4]]>] ] [log [msg <message>] ] <qualifiers>'''''<br> This keyword is only valid in the chain POSTROUTING, table nat. And ofcourse, source NATting does you little good if you haven't enabled forwarding (e.g. use this machine as a router for other machines on your network).<br> Calling snat with the right parameters will create a Source NATting rule for you, whereby a packet matching the qualifiers will be source NATted using the source IP address ''a1'' (or the range ''a1-a2''). Ofcourse, ''a1[-a2]'' should be valid IP address(es) of the firewalling machine.<br> Furthermore, if a port range ''p1-p2'' is specified, then you'll limit the range of ports that ''snat'' will use outbound (only valid for TCP or UDP packets).<br> Finally, it is possible to specify ''multiple'' IP address ranges and port ranges, using multiple ''to <a1[-a2][:p1-p2]]'' declarations in succession.<br> An example would be: context "POSTROUTING" "nat" snat to $inetIP -o $inetIF ! --src $inetIP If the variable ''$inetIP'' contains your public IP (e.g. 212.238.151.72), and ''$inetIF'' your interface connected to the Internet (e.g. ''eth0''), then this rule would expand to iptables -A POSTROUTING -t nat -o eth0 ! --src 212.238.151.72 -j SNAT --to-source 212.238.151.72 This would cause Iceditch to source NAT any outbound packet that is NOT sent by your firewall itself; in effect your server is now a nice fullblown NAT router for all machines on your private network. c47ef857a712234e12245579dd413b1a53089dc7 1599 1598 2008-08-06T08:20:45Z Saruman! 2 /* Parameter: log */ expanded msg to msg|message wikitext text/x-wiki == Parameter: log == ''target '''log [(msg|message) <message>]''' <qualifiers>''<br> After most keywords, a "log" parameter can be added (see below). If the "log" parameter is followed by "msg" (or "message"), then the parameter following "msg" is read and used as log-prefix. The parameter is not allowed to have whitespace, and the maximum length of the log-prefix is determined by your version of netfilter/IPtables and your IPtables logging utility (syslogemu or ulog); this limit is usually some 31 characters. Note that Iceditch does not perform any sanity checks on the message. Thus a packet matching the rule will be logged with the default setting of the "log" target. If the "log" parameter is ''not'' followed by "msg", then the packet will be logged with the default log message for that particular target keyword, and all the other default setting of the "log" target. Thus, should you want to log a packet with more control over the logging parameters, then you need an extra line, beginning with the ''target keyword'' "log", instead of just following the target keyword with parameter ''log''. For more information, see the target keyword "log" below. == Context keyword: context == '''''context <chain> &lt;table&gt;'''''<br> Every IPtables rule is written to a chain in a table; with Iceditch, you don't have to specify the chain and table in every line. Just precede the lines with the ''context'' statement. Example: context POSTROUTING nat Notes: the order of chain and table does not matter; ''context nat POSTROUTING'' works just as well. Furthermore, <chain> and &lt;table&gt; have been made case-insensitive; whatever you specify as chain will be translated to uppercase, whatever you specify as table will be translated to lowercase. This gives you the possibility to write the context as you like to read it, e.g. ''context Postrouting Nat''; after processing this, Iceditch will have two variables $CHAIN="POSTROUTING" and $TABLE="nat" that it will use in every following command. For example: context "Input" "fIlTeR" accept -p tcp --dport 22 will result in the following IPtables call: iptables -A INPUT -t filter -p tcp --dport 22 --jump ACCEPT If you do NOT specify a [[Iceditch IPtables language | valid combination]] of chain and table, the execution of Iceditch will halt with a fatal error. It is allowed (but not recommended) to call ''context'' multiple times for the same combination of chain and table; the order in which the rules are added to that chain in that table, is the same in which they appear in your rulefile, top to bottom. This is not recommended, because we feel it decreases readability, and thus maintainability, of the rules file. But hey, it's going to be ''your'' rulefile anyway... == Context keyword: create_chain == '''''create_chain <chain> [&lt;table&gt;]'''''<br> This command creates a new chain named <chain>, in the specified table &lt;table&gt;. If no table is specified, then the ''filter'' table is assumed. Just as with the ''context'' command, the <chain> name you specify will be translated to all uppercase.<br> The name for your new chain must be unique, although just like the built-in chains, you can specify the same name in different tables. If you create "fun-filter" in table ''filter'', and then create a "fun-filter" in table ''nat'', then you actually have two different chains. But remember: since Iceditch translates every chain name to uppercase, you can't create "Fun-filter" AND "fun-FILTER" in the same table - they're the same chain.<br> NOTE: after you've run ''create_chain'', you still have to switch context to create rules in the new chain! example:<br> create_chain fun-filter context fun-filter filter accept -p tcp --dport 22 This will result in iptables -N FUN-FILTER -t filter iptables -A FUN-FILTER -t filter -p tcp --dport 22 --jump ACCEPT == Target keyword: accept == '''''accept [log [msg <message>]] <qualifiers>'''''<br> If a network packet matches the qualifiers, then it will be accepted (passed) through the table/chain defined in the context where you put the accept rule. Example: <pre>context "INPUT" "filter" accept –p tcp --dport 22</pre> Iceditch works this out to iptables –t filter –A INPUT –p tcp –-dport 22 –-jump ACCEPT Should you want to log the packet, you’d use context "INPUT" "filter" accept log –p tcp --dport 22 Iceditch works this out to iptables –t filter –A INPUT –p tcp –-dport 22 \ –-jump LOG --log-prefix INPUT_accept iptables –t filter –A INPUT –p tcp –-dport 22 –-jump ACCEPT Note: the ACCEPT target is valid in any user-manipulable table/chain combination == Target keyword: classify == '''''classify <classval> [log [msg <message>]] <qualifiers>'''''<br> If a packet travelling through the mangle table in the POSTROUTING chain matches the qualifiers, then it will be classified with the <classval> specified. An example: classify 2:11 –p tcp --dport 22 The script works this out to iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump CLASSIFY --setclass 2:11 Should you want to also log the packet, you’d use classify 2:11 log –p tcp --dport 22 The script works this out to iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump LOG \ --log-prefix classified_2:11: iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump CLASSIFY \ --setclass 2:11 Should you not give a msg, then the log-prefix becomes POSTROUTING_CLASSIFY_set_<classval>. Because of how iptables handles the CLASSIFY target, you can only use it in contexts where the chain is “POSTROUTING” and the table is “mangle”. == Target keyword: drop == '''''drop [log [msg <message>]] <qualifiers> '''''<br> In essence, this does the same as the “accept” target keyword, only it jumps to DROP instead of ACCEPT. Thus any packet matching the qualifiers gets discarded; it will not get sent on to its final destination (or next hop), it will not get processed by any other firewall rule, and the sender of the packet is unaware of your treatment of his packet. Should you want to also log the packet, you’d use context "FORWARD" "filter" drop log –p tcp -s 10.0.0.0/16 The script works this out to iptables –t filter –A FORWARD –p tcp -s 10.0.0.0/16 –-jump LOG \ --log-prefix FORWARD_DROP: iptables –t filter –A FORWARD –p tcp -s 10.0.0.0/16 –-jump DROP Because of how iptables handles the DROP target, you can only use it in contexts where the table is “filter”. == Target keyword: log == '''''log [msg <message>] [lvl <loglevel>] <qualifiers>'''''<br> Sometimes, the standard ''log'' parameter is just not enough. This is mostly the case when you want to log a packet to a log-level other than the default level, which for most systems is ''4'' (''warning''). Furthermore, maybe you want to log a certain type or class of packets, without performing an action on those packets just yet. For this reason, AND for flexibility and clarity, Iceditch has the dedicated target keyword ''log''.<br> Just as when you use the ''log'' parameter, Iceditch will call the log target specified in the Iceditch [[Iceditch file structure | config file]]. Standard this is LOG, but optionally you could specify ULOG in the config file. ''<message>'' can be any string of 32 characters max (letters, numbers and underscores; no spaces); the ''<loglevel>'' can either be numeric or the corresponding keyword (e.g. ''crit''); Iceditch translates it to its numeric value anyway. Furthermore, the order in which <msg> and <lvl> appear is not important.<br> Depending on which log target you have specified, there are some options you can use with the Iceditch target keyword ''log''; it is currently deemed unnecessary to make specific Iceditch parameters for them, but as a reference we'll list the official IPtables options here, which you can put in the <qualifiers> list: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" ! colspan="2" style="background:#ffdead;"|LOG options | ! colspan="2" style="background:#ffdead;"|ULOG options |- !style="background:#ffdead;"|Option !style="background:#ffdead;"|Description | !style="background:#ffdead;"|Option !style="background:#ffdead;"|Description |- | --log-ip-options |Makes Netfilter include the IP options in the log entry | | --ulog-cprange <''size''> |log the first ''size'' bytes of each packet |- | --log-tcp-options |Makes Netfilter include the TCP options in the log entry | | --ulog-nlgroup <''nlgroup''> |Log to Netlink group number ''nlgroup'' (must match ''/etc/ulogd.conf'') |- | --log-tcp-sequence |Makes Netfilter include the TCP sequence number in the log entry | | --ulog-qthreshold <''value''> |Queue ''value'' packets before sending them to ''ulogd'' (default = 1, max = 50) |- |} <br> For completeness, we here reproduce the list of logging levels that ''log'' understands: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Level !style="background:#ffdead;"|Description |- |0 |''emerg'' or ''panic'' |- |1 |''alert'' |- |2 |''crit'' |- |3 |''err'' |- |4 |''warn'' (default) |- |5 |''notice'' |- |6 |''info'' |- |7 |''debug'' |- |} Now an example: context "INPUT" "filter" log lvl info msg SSH_incoming -p tcp --dport 22 -i $inetIF Iceditch works this out into iptables -A INPUT -t filter -p tcp --dport 22 -i $inetIF --jump ULOG --ulog-prefix "SSH_incoming" --log-level 6 == Target keyword: mark == '''''mark <markval> [log [msg <message>]] <qualifiers>'''''<br> If a packet matches the qualifiers, then it will be marked with the <markval> specified. An example from the context “PREROUTING” “mangle”: mark 2 –p tcp --dport 22 Iceditch works this out to iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump MARK --setmark 2 Should you want to also log the packet, you’d use mark 2 log –p tcp --dport 22 Iceditch works this out to iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump LOG \ --log-prefix PREROUTING_MARK_set_2: iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump MARK --setmark 2 Because of how iptables handles the MARK target, you can only use it in contexts where the table is “mangle”. == Target keyword: redirect == '''''redirect [to <to-ports>] [log [msg <message>]] <qualifiers>'''''<br> If a packet matches the qualifiers, then it will be redirected to the local machine, by setting the destination IP to a fitting IP address of the local machine (i.e. 127.0.0.1, or the first-bound IP address of the interface over which it came in. Additionally, by specifying “to <to-ports>” you can have the destination ports redirected to a port or portrange. <to-ports> can either be a port number (e.g. 8080) or a port range (e.g. 6661-6669; the latter is inclusive). Example for a transparent HTTP proxy: context "OUTPUT" "nat" redirect to 8080 –p tcp --dport 80 Iceditch works this out to iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump REDIRECT –to-ports 8080 Should you want to log the packet, you could use redirect to 8080 log –p tcp --dport 80 Iceditch works this out to iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump LOG \ --log-prefix OUTPUT_REDIRECT_to_8080: iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump REDIRECT –-to-ports 8080 Because of how iptables handles the REDIRECT target, you can only use it in contexts where the table is “nat” and the chain is PREROUTING or OUTPUT. == Target keyword: reject == '''''reject [with <type>] [log [msg <message>]] <qualifiers>'''''<br> In essence, this does the same as the “drop” target keyword, only it jumps to REJECT instead of DROP. This means the packet is discarded (just as with DROP), but the sender is notified using ICMP (by default, your machine will send an ICMP-packet of type "icmp-port-unreachable"). Because of how iptables handles the REJECT target, you can only use it in contexts where the table is “filter”. Optionally, you can follow “reject” with the keyword “with”, and then use one of the following rejection types: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Type !style="background:#ffdead;"|Description |- | icmp-host-prohibited | will send an ICMP-message "host prohibited" |- | icmp-host-unreachable | will send an ICMP-message "host unreachable" |- | icmp-net-prohibited | will send an ICMP-message "net prohibited" |- | icmp-net-unreachable | will send an ICMP-message "net unreachable" |- | icmp-port-unreachable | DEFAULT; will send an ICMP-message "port unreachable" |- | icmp-proto-unreachable | DEFAULT; will send an ICMP-message "protocol unreachable" |- | tcp-reset | will send a TCP reset, a packet with the RST flag set (as a response to a TCP packet only) |- | host-prohib | synonymous to icmp-host-prohibited |- | host-unreach | synonymous to icmp-host-unreachable |- | net-prohib | synonymous to icmp-net-prohibited |- | net-unreach | synonymous to icmp-net-unreachable |- | port-unreach | synonymous to icmp-port-unreachable |- | proto-unreach | synonymous to icmp-proto-unreachable |- |} If you don’t specify “with <type>”, then netfilter will assume icmp-port-unreachable. Thus, should you want to reject a packet in context filter_INPUT (and log it) with reason net-prohib, you’d use reject with net-prohib log –p tcp –i eth0 --dport 22 Iceditch works this out to iptables –t filter –A INPUT –p tcp –i eth0 –-dport 22 –-jump LOG \ --log-prefix INPUT_REJECT_with_net-prohib: iptables –t filter –A INPUT –p tcp –i eth0 –-dport 22 \ –-jump REJECT –-reject-with net-prohib –p tcp –i eth0 –-dport 22 == Target keyword: snat== '''''snat [to <a1[-a2][:p1-p2]]> [to <a3[-a4][:p3-p4]]>] ] [log [msg <message>] ] <qualifiers>'''''<br> This keyword is only valid in the chain POSTROUTING, table nat. And ofcourse, source NATting does you little good if you haven't enabled forwarding (e.g. use this machine as a router for other machines on your network).<br> Calling snat with the right parameters will create a Source NATting rule for you, whereby a packet matching the qualifiers will be source NATted using the source IP address ''a1'' (or the range ''a1-a2''). Ofcourse, ''a1[-a2]'' should be valid IP address(es) of the firewalling machine.<br> Furthermore, if a port range ''p1-p2'' is specified, then you'll limit the range of ports that ''snat'' will use outbound (only valid for TCP or UDP packets).<br> Finally, it is possible to specify ''multiple'' IP address ranges and port ranges, using multiple ''to <a1[-a2][:p1-p2]]'' declarations in succession.<br> An example would be: context "POSTROUTING" "nat" snat to $inetIP -o $inetIF ! --src $inetIP If the variable ''$inetIP'' contains your public IP (e.g. 212.238.151.72), and ''$inetIF'' your interface connected to the Internet (e.g. ''eth0''), then this rule would expand to iptables -A POSTROUTING -t nat -o eth0 ! --src 212.238.151.72 -j SNAT --to-source 212.238.151.72 This would cause Iceditch to source NAT any outbound packet that is NOT sent by your firewall itself; in effect your server is now a nice fullblown NAT router for all machines on your private network. 684a1f92cdde836ae0f19d879a0e4fc4dbdf4ce9 1600 1599 2008-08-06T13:13:01Z Saruman! 2 /* Target keyword: log */ wikitext text/x-wiki == Parameter: log == ''target '''log [(msg|message) <message>]''' <qualifiers>''<br> After most keywords, a "log" parameter can be added (see below). If the "log" parameter is followed by "msg" (or "message"), then the parameter following "msg" is read and used as log-prefix. The parameter is not allowed to have whitespace, and the maximum length of the log-prefix is determined by your version of netfilter/IPtables and your IPtables logging utility (syslogemu or ulog); this limit is usually some 31 characters. Note that Iceditch does not perform any sanity checks on the message. Thus a packet matching the rule will be logged with the default setting of the "log" target. If the "log" parameter is ''not'' followed by "msg", then the packet will be logged with the default log message for that particular target keyword, and all the other default setting of the "log" target. Thus, should you want to log a packet with more control over the logging parameters, then you need an extra line, beginning with the ''target keyword'' "log", instead of just following the target keyword with parameter ''log''. For more information, see the target keyword "log" below. == Context keyword: context == '''''context <chain> &lt;table&gt;'''''<br> Every IPtables rule is written to a chain in a table; with Iceditch, you don't have to specify the chain and table in every line. Just precede the lines with the ''context'' statement. Example: context POSTROUTING nat Notes: the order of chain and table does not matter; ''context nat POSTROUTING'' works just as well. Furthermore, <chain> and &lt;table&gt; have been made case-insensitive; whatever you specify as chain will be translated to uppercase, whatever you specify as table will be translated to lowercase. This gives you the possibility to write the context as you like to read it, e.g. ''context Postrouting Nat''; after processing this, Iceditch will have two variables $CHAIN="POSTROUTING" and $TABLE="nat" that it will use in every following command. For example: context "Input" "fIlTeR" accept -p tcp --dport 22 will result in the following IPtables call: iptables -A INPUT -t filter -p tcp --dport 22 --jump ACCEPT If you do NOT specify a [[Iceditch IPtables language | valid combination]] of chain and table, the execution of Iceditch will halt with a fatal error. It is allowed (but not recommended) to call ''context'' multiple times for the same combination of chain and table; the order in which the rules are added to that chain in that table, is the same in which they appear in your rulefile, top to bottom. This is not recommended, because we feel it decreases readability, and thus maintainability, of the rules file. But hey, it's going to be ''your'' rulefile anyway... == Context keyword: create_chain == '''''create_chain <chain> [&lt;table&gt;]'''''<br> This command creates a new chain named <chain>, in the specified table &lt;table&gt;. If no table is specified, then the ''filter'' table is assumed. Just as with the ''context'' command, the <chain> name you specify will be translated to all uppercase.<br> The name for your new chain must be unique, although just like the built-in chains, you can specify the same name in different tables. If you create "fun-filter" in table ''filter'', and then create a "fun-filter" in table ''nat'', then you actually have two different chains. But remember: since Iceditch translates every chain name to uppercase, you can't create "Fun-filter" AND "fun-FILTER" in the same table - they're the same chain.<br> NOTE: after you've run ''create_chain'', you still have to switch context to create rules in the new chain! example:<br> create_chain fun-filter context fun-filter filter accept -p tcp --dport 22 This will result in iptables -N FUN-FILTER -t filter iptables -A FUN-FILTER -t filter -p tcp --dport 22 --jump ACCEPT == Target keyword: accept == '''''accept [log [msg <message>]] <qualifiers>'''''<br> If a network packet matches the qualifiers, then it will be accepted (passed) through the table/chain defined in the context where you put the accept rule. Example: <pre>context "INPUT" "filter" accept –p tcp --dport 22</pre> Iceditch works this out to iptables –t filter –A INPUT –p tcp –-dport 22 –-jump ACCEPT Should you want to log the packet, you’d use context "INPUT" "filter" accept log –p tcp --dport 22 Iceditch works this out to iptables –t filter –A INPUT –p tcp –-dport 22 \ –-jump LOG --log-prefix INPUT_accept iptables –t filter –A INPUT –p tcp –-dport 22 –-jump ACCEPT Note: the ACCEPT target is valid in any user-manipulable table/chain combination == Target keyword: classify == '''''classify <classval> [log [msg <message>]] <qualifiers>'''''<br> If a packet travelling through the mangle table in the POSTROUTING chain matches the qualifiers, then it will be classified with the <classval> specified. An example: classify 2:11 –p tcp --dport 22 The script works this out to iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump CLASSIFY --setclass 2:11 Should you want to also log the packet, you’d use classify 2:11 log –p tcp --dport 22 The script works this out to iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump LOG \ --log-prefix classified_2:11: iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump CLASSIFY \ --setclass 2:11 Should you not give a msg, then the log-prefix becomes POSTROUTING_CLASSIFY_set_<classval>. Because of how iptables handles the CLASSIFY target, you can only use it in contexts where the chain is “POSTROUTING” and the table is “mangle”. == Target keyword: drop == '''''drop [log [msg <message>]] <qualifiers> '''''<br> In essence, this does the same as the “accept” target keyword, only it jumps to DROP instead of ACCEPT. Thus any packet matching the qualifiers gets discarded; it will not get sent on to its final destination (or next hop), it will not get processed by any other firewall rule, and the sender of the packet is unaware of your treatment of his packet. Should you want to also log the packet, you’d use context "FORWARD" "filter" drop log –p tcp -s 10.0.0.0/16 The script works this out to iptables –t filter –A FORWARD –p tcp -s 10.0.0.0/16 –-jump LOG \ --log-prefix FORWARD_DROP: iptables –t filter –A FORWARD –p tcp -s 10.0.0.0/16 –-jump DROP Because of how iptables handles the DROP target, you can only use it in contexts where the table is “filter”. == Target keyword: log == '''''log [(msg|message) <message>] [(lvl|level) <loglevel>] <qualifiers>'''''<br> Sometimes, the standard ''log'' parameter is just not enough. This can be the case when you want to log a packet to a log-level other than the default level, which for most systems is ''4'' (''warning''). Furthermore, maybe you want to log a certain type or class of packets, without performing an action on those packets just yet. For this reason, AND for flexibility and clarity, Iceditch has the dedicated target keyword ''log''.<br> Just as when you use the ''log'' parameter after another target, Iceditch will call the log target specified in the Iceditch [[Iceditch file structure | config file]]. Standard this is LOG, but optionally you could specify ULOG in the config file. ''<message>'' can be any string of 32 characters max (letters, numbers and underscores; no spaces); the ''<loglevel>'' can either be numeric or the corresponding keyword (e.g. ''crit''); Iceditch translates it to its numeric value anyway. Furthermore, the order in which <msg> and <lvl> appear is not important.<br> Depending on which log target you have specified, there are some options you can use with the Iceditch target keyword ''log''; it is currently deemed unnecessary to make specific Iceditch parameters for them, but as a reference we'll list the official IPtables options here, which you can put in the <qualifiers> list: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" ! colspan="2" style="background:#ffdead;"|LOG options | ! colspan="2" style="background:#ffdead;"|ULOG options |- !style="background:#ffdead;"|Option !style="background:#ffdead;"|Description | !style="background:#ffdead;"|Option !style="background:#ffdead;"|Description |- | --log-ip-options |Makes Netfilter include the IP options in the log entry | | --ulog-cprange <''size''> |log the first ''size'' bytes of each packet |- | --log-tcp-options |Makes Netfilter include the TCP options in the log entry | | --ulog-nlgroup <''nlgroup''> |Log to Netlink group number ''nlgroup'' (must match ''/etc/ulogd.conf'') |- | --log-tcp-sequence |Makes Netfilter include the TCP sequence number in the log entry | | --ulog-qthreshold <''value''> |Queue ''value'' packets before sending them to ''ulogd'' (default = 1, max = 50) |- |} <br> For completeness, we here reproduce the list of logging levels that ''log'' understands: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Level !style="background:#ffdead;"|Description |- |0 |''emerg'' or ''panic'' |- |1 |''alert'' |- |2 |''crit'' |- |3 |''err'' |- |4 |''warn'' (default) |- |5 |''notice'' |- |6 |''info'' |- |7 |''debug'' |- |} Now an example: context "INPUT" "filter" log lvl info msg SSH_incoming -p tcp --dport 22 -i $inetIF Iceditch works this out into iptables -A INPUT -t filter -p tcp --dport 22 -i $inetIF --jump ULOG --ulog-prefix "SSH_incoming" --log-level 6 == Target keyword: mark == '''''mark <markval> [log [msg <message>]] <qualifiers>'''''<br> If a packet matches the qualifiers, then it will be marked with the <markval> specified. An example from the context “PREROUTING” “mangle”: mark 2 –p tcp --dport 22 Iceditch works this out to iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump MARK --setmark 2 Should you want to also log the packet, you’d use mark 2 log –p tcp --dport 22 Iceditch works this out to iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump LOG \ --log-prefix PREROUTING_MARK_set_2: iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump MARK --setmark 2 Because of how iptables handles the MARK target, you can only use it in contexts where the table is “mangle”. == Target keyword: redirect == '''''redirect [to <to-ports>] [log [msg <message>]] <qualifiers>'''''<br> If a packet matches the qualifiers, then it will be redirected to the local machine, by setting the destination IP to a fitting IP address of the local machine (i.e. 127.0.0.1, or the first-bound IP address of the interface over which it came in. Additionally, by specifying “to <to-ports>” you can have the destination ports redirected to a port or portrange. <to-ports> can either be a port number (e.g. 8080) or a port range (e.g. 6661-6669; the latter is inclusive). Example for a transparent HTTP proxy: context "OUTPUT" "nat" redirect to 8080 –p tcp --dport 80 Iceditch works this out to iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump REDIRECT –to-ports 8080 Should you want to log the packet, you could use redirect to 8080 log –p tcp --dport 80 Iceditch works this out to iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump LOG \ --log-prefix OUTPUT_REDIRECT_to_8080: iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump REDIRECT –-to-ports 8080 Because of how iptables handles the REDIRECT target, you can only use it in contexts where the table is “nat” and the chain is PREROUTING or OUTPUT. == Target keyword: reject == '''''reject [with <type>] [log [msg <message>]] <qualifiers>'''''<br> In essence, this does the same as the “drop” target keyword, only it jumps to REJECT instead of DROP. This means the packet is discarded (just as with DROP), but the sender is notified using ICMP (by default, your machine will send an ICMP-packet of type "icmp-port-unreachable"). Because of how iptables handles the REJECT target, you can only use it in contexts where the table is “filter”. Optionally, you can follow “reject” with the keyword “with”, and then use one of the following rejection types: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Type !style="background:#ffdead;"|Description |- | icmp-host-prohibited | will send an ICMP-message "host prohibited" |- | icmp-host-unreachable | will send an ICMP-message "host unreachable" |- | icmp-net-prohibited | will send an ICMP-message "net prohibited" |- | icmp-net-unreachable | will send an ICMP-message "net unreachable" |- | icmp-port-unreachable | DEFAULT; will send an ICMP-message "port unreachable" |- | icmp-proto-unreachable | DEFAULT; will send an ICMP-message "protocol unreachable" |- | tcp-reset | will send a TCP reset, a packet with the RST flag set (as a response to a TCP packet only) |- | host-prohib | synonymous to icmp-host-prohibited |- | host-unreach | synonymous to icmp-host-unreachable |- | net-prohib | synonymous to icmp-net-prohibited |- | net-unreach | synonymous to icmp-net-unreachable |- | port-unreach | synonymous to icmp-port-unreachable |- | proto-unreach | synonymous to icmp-proto-unreachable |- |} If you don’t specify “with <type>”, then netfilter will assume icmp-port-unreachable. Thus, should you want to reject a packet in context filter_INPUT (and log it) with reason net-prohib, you’d use reject with net-prohib log –p tcp –i eth0 --dport 22 Iceditch works this out to iptables –t filter –A INPUT –p tcp –i eth0 –-dport 22 –-jump LOG \ --log-prefix INPUT_REJECT_with_net-prohib: iptables –t filter –A INPUT –p tcp –i eth0 –-dport 22 \ –-jump REJECT –-reject-with net-prohib –p tcp –i eth0 –-dport 22 == Target keyword: snat== '''''snat [to <a1[-a2][:p1-p2]]> [to <a3[-a4][:p3-p4]]>] ] [log [msg <message>] ] <qualifiers>'''''<br> This keyword is only valid in the chain POSTROUTING, table nat. And ofcourse, source NATting does you little good if you haven't enabled forwarding (e.g. use this machine as a router for other machines on your network).<br> Calling snat with the right parameters will create a Source NATting rule for you, whereby a packet matching the qualifiers will be source NATted using the source IP address ''a1'' (or the range ''a1-a2''). Ofcourse, ''a1[-a2]'' should be valid IP address(es) of the firewalling machine.<br> Furthermore, if a port range ''p1-p2'' is specified, then you'll limit the range of ports that ''snat'' will use outbound (only valid for TCP or UDP packets).<br> Finally, it is possible to specify ''multiple'' IP address ranges and port ranges, using multiple ''to <a1[-a2][:p1-p2]]'' declarations in succession.<br> An example would be: context "POSTROUTING" "nat" snat to $inetIP -o $inetIF ! --src $inetIP If the variable ''$inetIP'' contains your public IP (e.g. 212.238.151.72), and ''$inetIF'' your interface connected to the Internet (e.g. ''eth0''), then this rule would expand to iptables -A POSTROUTING -t nat -o eth0 ! --src 212.238.151.72 -j SNAT --to-source 212.238.151.72 This would cause Iceditch to source NAT any outbound packet that is NOT sent by your firewall itself; in effect your server is now a nice fullblown NAT router for all machines on your private network. 4b20890422b681c953308db73f7835d530eff11b 1601 1600 2008-08-06T18:40:49Z Saruman! 2 added target keyword DNAT wikitext text/x-wiki == Parameter: log == ''target '''log [(msg|message) <message>]''' <qualifiers>''<br> After most keywords, a "log" parameter can be added (see below). If the "log" parameter is followed by "msg" (or "message"), then the parameter following "msg" is read and used as log-prefix. The parameter is not allowed to have whitespace, and the maximum length of the log-prefix is determined by your version of netfilter/IPtables and your IPtables logging utility (syslogemu or ulog); this limit is usually some 31 characters. Note that Iceditch does not perform any sanity checks on the message. Thus a packet matching the rule will be logged with the default setting of the "log" target. If the "log" parameter is ''not'' followed by "msg", then the packet will be logged with the default log message for that particular target keyword, and all the other default setting of the "log" target. Thus, should you want to log a packet with more control over the logging parameters, then you need an extra line, beginning with the ''target keyword'' "log", instead of just following the target keyword with parameter ''log''. For more information, see the target keyword "log" below. == Context keyword: context == '''''context <chain> &lt;table&gt;'''''<br> Every IPtables rule is written to a chain in a table; with Iceditch, you don't have to specify the chain and table in every line. Just precede the lines with the ''context'' statement. Example: context POSTROUTING nat Notes: the order of chain and table does not matter; ''context nat POSTROUTING'' works just as well. Furthermore, <chain> and &lt;table&gt; have been made case-insensitive; whatever you specify as chain will be translated to uppercase, whatever you specify as table will be translated to lowercase. This gives you the possibility to write the context as you like to read it, e.g. ''context Postrouting Nat''; after processing this, Iceditch will have two variables $CHAIN="POSTROUTING" and $TABLE="nat" that it will use in every following command. For example: context "Input" "fIlTeR" accept -p tcp --dport 22 will result in the following IPtables call: iptables -A INPUT -t filter -p tcp --dport 22 --jump ACCEPT If you do NOT specify a [[Iceditch IPtables language | valid combination]] of chain and table, the execution of Iceditch will halt with a fatal error. It is allowed (but not recommended) to call ''context'' multiple times for the same combination of chain and table; the order in which the rules are added to that chain in that table, is the same in which they appear in your rulefile, top to bottom. This is not recommended, because we feel it decreases readability, and thus maintainability, of the rules file. But hey, it's going to be ''your'' rulefile anyway... == Context keyword: create_chain == '''''create_chain <chain> [&lt;table&gt;]'''''<br> This command creates a new chain named <chain>, in the specified table &lt;table&gt;. If no table is specified, then the ''filter'' table is assumed. Just as with the ''context'' command, the <chain> name you specify will be translated to all uppercase.<br> The name for your new chain must be unique, although just like the built-in chains, you can specify the same name in different tables. If you create "fun-filter" in table ''filter'', and then create a "fun-filter" in table ''nat'', then you actually have two different chains. But remember: since Iceditch translates every chain name to uppercase, you can't create "Fun-filter" AND "fun-FILTER" in the same table - they're the same chain.<br> NOTE: after you've run ''create_chain'', you still have to switch context to create rules in the new chain! example:<br> create_chain fun-filter context fun-filter filter accept -p tcp --dport 22 This will result in iptables -N FUN-FILTER -t filter iptables -A FUN-FILTER -t filter -p tcp --dport 22 --jump ACCEPT == Target keyword: accept == '''''accept [log [msg <message>]] <qualifiers>'''''<br> If a network packet matches the qualifiers, then it will be accepted (passed) through the table/chain defined in the context where you put the accept rule. Example: <pre>context "INPUT" "filter" accept –p tcp --dport 22</pre> Iceditch works this out to iptables –t filter –A INPUT –p tcp –-dport 22 –-jump ACCEPT Should you want to log the packet, you’d use context "INPUT" "filter" accept log –p tcp --dport 22 Iceditch works this out to iptables –t filter –A INPUT –p tcp –-dport 22 \ –-jump LOG --log-prefix INPUT_accept iptables –t filter –A INPUT –p tcp –-dport 22 –-jump ACCEPT Note: the ACCEPT target is valid in any user-manipulable table/chain combination == Target keyword: classify == '''''classify <classval> [log [msg <message>]] <qualifiers>'''''<br> If a packet travelling through the mangle table in the POSTROUTING chain matches the qualifiers, then it will be classified with the <classval> specified. An example: classify 2:11 –p tcp --dport 22 The script works this out to iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump CLASSIFY --setclass 2:11 Should you want to also log the packet, you’d use classify 2:11 log –p tcp --dport 22 The script works this out to iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump LOG \ --log-prefix classified_2:11: iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump CLASSIFY \ --setclass 2:11 Should you not give a msg, then the log-prefix becomes POSTROUTING_CLASSIFY_set_<classval>. Because of how iptables handles the CLASSIFY target, you can only use it in contexts where the chain is “POSTROUTING” and the table is “mangle”. == Target keyword: dnat == '''''dnat [to] <a1[-a2][:p1[-p2]]> [log [msg <message>]] <qualifiers>'''''<br> In the above, a1 and a2 are used to specify a (range of) IP address(es); for TCP and UDP protocols, a destination port or port range can be provided. Note that the "to" in the command is optional, and serves only readability.<br> If a packet matches the qualifiers, then it will be destination-NATted to the provided IP address or address range. For example, if you want to DNAT port 81 on your external interface eth1 to an internal webserver on 10.0.0.1, you could use context "PREROUTING" "nat" dnat to 10.0.0.1:80 –p tcp –i eth1 –-dport 81 If you give a range of IP addresses, then the DNAT logic of IPtables will randomly pick an address and DNAT the packet there. However, note that a single stream will always use the same IP address from that range, and that each stream will randomly be given an IP address that it will always be destined for, within that stream.<br> Furthermore, note that the DNAT target is only available within the PREROUTING and OUTPUT chains in the nat table, and any of the chains called upon from any of those listed chains. Note that chains containing DNAT targets may not be used from any other chains, such as the POSTROUTING chain. However, the bad news is that Iceditch currently does not know how to check for the latter case, so the dnat keyword only works from contexts "PREROUTING" "nat" and "OUTPUT" "nat". == Target keyword: drop == '''''drop [log [msg <message>]] <qualifiers> '''''<br> In essence, this does the same as the “accept” target keyword, only it jumps to DROP instead of ACCEPT. Thus any packet matching the qualifiers gets discarded; it will not get sent on to its final destination (or next hop), it will not get processed by any other firewall rule, and the sender of the packet is unaware of your treatment of his packet. Should you want to also log the packet, you’d use context "FORWARD" "filter" drop log –p tcp -s 10.0.0.0/16 The script works this out to iptables –t filter –A FORWARD –p tcp -s 10.0.0.0/16 –-jump LOG \ --log-prefix FORWARD_DROP: iptables –t filter –A FORWARD –p tcp -s 10.0.0.0/16 –-jump DROP Because of how iptables handles the DROP target, you can only use it in contexts where the table is “filter”. == Target keyword: log == '''''log [(msg|message) <message>] [(lvl|level) <loglevel>] <qualifiers>'''''<br> Sometimes, the standard ''log'' parameter is just not enough. This can be the case when you want to log a packet to a log-level other than the default level, which for most systems is ''4'' (''warning''). Furthermore, maybe you want to log a certain type or class of packets, without performing an action on those packets just yet. For this reason, AND for flexibility and clarity, Iceditch has the dedicated target keyword ''log''.<br> Just as when you use the ''log'' parameter after another target, Iceditch will call the log target specified in the Iceditch [[Iceditch file structure | config file]]. Standard this is LOG, but optionally you could specify ULOG in the config file. ''<message>'' can be any string of 32 characters max (letters, numbers and underscores; no spaces); the ''<loglevel>'' can either be numeric or the corresponding keyword (e.g. ''crit''); Iceditch translates it to its numeric value anyway. Furthermore, the order in which <msg> and <lvl> appear is not important.<br> Depending on which log target you have specified, there are some options you can use with the Iceditch target keyword ''log''; it is currently deemed unnecessary to make specific Iceditch parameters for them, but as a reference we'll list the official IPtables options here, which you can put in the <qualifiers> list: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" ! colspan="2" style="background:#ffdead;"|LOG options | ! colspan="2" style="background:#ffdead;"|ULOG options |- !style="background:#ffdead;"|Option !style="background:#ffdead;"|Description | !style="background:#ffdead;"|Option !style="background:#ffdead;"|Description |- | --log-ip-options |Makes Netfilter include the IP options in the log entry | | --ulog-cprange <''size''> |log the first ''size'' bytes of each packet |- | --log-tcp-options |Makes Netfilter include the TCP options in the log entry | | --ulog-nlgroup <''nlgroup''> |Log to Netlink group number ''nlgroup'' (must match ''/etc/ulogd.conf'') |- | --log-tcp-sequence |Makes Netfilter include the TCP sequence number in the log entry | | --ulog-qthreshold <''value''> |Queue ''value'' packets before sending them to ''ulogd'' (default = 1, max = 50) |- |} <br> For completeness, we here reproduce the list of logging levels that ''log'' understands: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Level !style="background:#ffdead;"|Description |- |0 |''emerg'' or ''panic'' |- |1 |''alert'' |- |2 |''crit'' |- |3 |''err'' |- |4 |''warn'' (default) |- |5 |''notice'' |- |6 |''info'' |- |7 |''debug'' |- |} Now an example: context "INPUT" "filter" log lvl info msg SSH_incoming -p tcp --dport 22 -i $inetIF Iceditch works this out into iptables -A INPUT -t filter -p tcp --dport 22 -i $inetIF --jump ULOG --ulog-prefix "SSH_incoming" --log-level 6 == Target keyword: mark == '''''mark <markval> [log [msg <message>]] <qualifiers>'''''<br> If a packet matches the qualifiers, then it will be marked with the <markval> specified. An example from the context “PREROUTING” “mangle”: mark 2 –p tcp --dport 22 Iceditch works this out to iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump MARK --setmark 2 Should you want to also log the packet, you’d use mark 2 log –p tcp --dport 22 Iceditch works this out to iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump LOG \ --log-prefix PREROUTING_MARK_set_2: iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump MARK --setmark 2 Because of how iptables handles the MARK target, you can only use it in contexts where the table is “mangle”. == Target keyword: redirect == '''''redirect [to <to-ports>] [log [msg <message>]] <qualifiers>'''''<br> If a packet matches the qualifiers, then it will be redirected to the local machine, by setting the destination IP to a fitting IP address of the local machine (i.e. 127.0.0.1, or the first-bound IP address of the interface over which it came in. Additionally, by specifying “to <to-ports>” you can have the destination ports redirected to a port or portrange. <to-ports> can either be a port number (e.g. 8080) or a port range (e.g. 6661-6669; the latter is inclusive). Example for a transparent HTTP proxy: context "OUTPUT" "nat" redirect to 8080 –p tcp --dport 80 Iceditch works this out to iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump REDIRECT –to-ports 8080 Should you want to log the packet, you could use redirect to 8080 log –p tcp --dport 80 Iceditch works this out to iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump LOG \ --log-prefix OUTPUT_REDIRECT_to_8080: iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump REDIRECT –-to-ports 8080 Because of how iptables handles the REDIRECT target, you can only use it in contexts where the table is “nat” and the chain is PREROUTING or OUTPUT. == Target keyword: reject == '''''reject [with <type>] [log [msg <message>]] <qualifiers>'''''<br> In essence, this does the same as the “drop” target keyword, only it jumps to REJECT instead of DROP. This means the packet is discarded (just as with DROP), but the sender is notified using ICMP (by default, your machine will send an ICMP-packet of type "icmp-port-unreachable"). Because of how iptables handles the REJECT target, you can only use it in contexts where the table is “filter”. Optionally, you can follow “reject” with the keyword “with”, and then use one of the following rejection types: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Type !style="background:#ffdead;"|Description |- | icmp-host-prohibited | will send an ICMP-message "host prohibited" |- | icmp-host-unreachable | will send an ICMP-message "host unreachable" |- | icmp-net-prohibited | will send an ICMP-message "net prohibited" |- | icmp-net-unreachable | will send an ICMP-message "net unreachable" |- | icmp-port-unreachable | DEFAULT; will send an ICMP-message "port unreachable" |- | icmp-proto-unreachable | DEFAULT; will send an ICMP-message "protocol unreachable" |- | tcp-reset | will send a TCP reset, a packet with the RST flag set (as a response to a TCP packet only) |- | host-prohib | synonymous to icmp-host-prohibited |- | host-unreach | synonymous to icmp-host-unreachable |- | net-prohib | synonymous to icmp-net-prohibited |- | net-unreach | synonymous to icmp-net-unreachable |- | port-unreach | synonymous to icmp-port-unreachable |- | proto-unreach | synonymous to icmp-proto-unreachable |- |} If you don’t specify “with <type>”, then netfilter will assume icmp-port-unreachable. Thus, should you want to reject a packet in context filter_INPUT (and log it) with reason net-prohib, you’d use reject with net-prohib log –p tcp –i eth0 --dport 22 Iceditch works this out to iptables –t filter –A INPUT –p tcp –i eth0 –-dport 22 –-jump LOG \ --log-prefix INPUT_REJECT_with_net-prohib: iptables –t filter –A INPUT –p tcp –i eth0 –-dport 22 \ –-jump REJECT –-reject-with net-prohib –p tcp –i eth0 –-dport 22 == Target keyword: snat== '''''snat [to <a1[-a2][:p1-p2]]> [to <a3[-a4][:p3-p4]]>] ] [log [msg <message>] ] <qualifiers>'''''<br> This keyword is only valid in the chain POSTROUTING, table nat. And ofcourse, source NATting does you little good if you haven't enabled forwarding (e.g. use this machine as a router for other machines on your network).<br> Calling snat with the right parameters will create a Source NATting rule for you, whereby a packet matching the qualifiers will be source NATted using the source IP address ''a1'' (or the range ''a1-a2''). Ofcourse, ''a1[-a2]'' should be valid IP address(es) of the firewalling machine.<br> Furthermore, if a port range ''p1-p2'' is specified, then you'll limit the range of ports that ''snat'' will use outbound (only valid for TCP or UDP packets).<br> Finally, it is possible to specify ''multiple'' IP address ranges and port ranges, using multiple ''to <a1[-a2][:p1-p2]]'' declarations in succession.<br> An example would be: context "POSTROUTING" "nat" snat to $inetIP -o $inetIF ! --src $inetIP If the variable ''$inetIP'' contains your public IP (e.g. 212.238.151.72), and ''$inetIF'' your interface connected to the Internet (e.g. ''eth0''), then this rule would expand to iptables -A POSTROUTING -t nat -o eth0 ! --src 212.238.151.72 -j SNAT --to-source 212.238.151.72 This would cause Iceditch to source NAT any outbound packet that is NOT sent by your firewall itself; in effect your server is now a nice fullblown NAT router for all machines on your private network. 2da6a06d2204483e55046e5d38200ec39403adab 1602 1601 2008-08-06T18:47:46Z Saruman! 2 /* Target keyword: drop */ usable in any chain wikitext text/x-wiki == Parameter: log == ''target '''log [(msg|message) <message>]''' <qualifiers>''<br> After most keywords, a "log" parameter can be added (see below). If the "log" parameter is followed by "msg" (or "message"), then the parameter following "msg" is read and used as log-prefix. The parameter is not allowed to have whitespace, and the maximum length of the log-prefix is determined by your version of netfilter/IPtables and your IPtables logging utility (syslogemu or ulog); this limit is usually some 31 characters. Note that Iceditch does not perform any sanity checks on the message. Thus a packet matching the rule will be logged with the default setting of the "log" target. If the "log" parameter is ''not'' followed by "msg", then the packet will be logged with the default log message for that particular target keyword, and all the other default setting of the "log" target. Thus, should you want to log a packet with more control over the logging parameters, then you need an extra line, beginning with the ''target keyword'' "log", instead of just following the target keyword with parameter ''log''. For more information, see the target keyword "log" below. == Context keyword: context == '''''context <chain> &lt;table&gt;'''''<br> Every IPtables rule is written to a chain in a table; with Iceditch, you don't have to specify the chain and table in every line. Just precede the lines with the ''context'' statement. Example: context POSTROUTING nat Notes: the order of chain and table does not matter; ''context nat POSTROUTING'' works just as well. Furthermore, <chain> and &lt;table&gt; have been made case-insensitive; whatever you specify as chain will be translated to uppercase, whatever you specify as table will be translated to lowercase. This gives you the possibility to write the context as you like to read it, e.g. ''context Postrouting Nat''; after processing this, Iceditch will have two variables $CHAIN="POSTROUTING" and $TABLE="nat" that it will use in every following command. For example: context "Input" "fIlTeR" accept -p tcp --dport 22 will result in the following IPtables call: iptables -A INPUT -t filter -p tcp --dport 22 --jump ACCEPT If you do NOT specify a [[Iceditch IPtables language | valid combination]] of chain and table, the execution of Iceditch will halt with a fatal error. It is allowed (but not recommended) to call ''context'' multiple times for the same combination of chain and table; the order in which the rules are added to that chain in that table, is the same in which they appear in your rulefile, top to bottom. This is not recommended, because we feel it decreases readability, and thus maintainability, of the rules file. But hey, it's going to be ''your'' rulefile anyway... == Context keyword: create_chain == '''''create_chain <chain> [&lt;table&gt;]'''''<br> This command creates a new chain named <chain>, in the specified table &lt;table&gt;. If no table is specified, then the ''filter'' table is assumed. Just as with the ''context'' command, the <chain> name you specify will be translated to all uppercase.<br> The name for your new chain must be unique, although just like the built-in chains, you can specify the same name in different tables. If you create "fun-filter" in table ''filter'', and then create a "fun-filter" in table ''nat'', then you actually have two different chains. But remember: since Iceditch translates every chain name to uppercase, you can't create "Fun-filter" AND "fun-FILTER" in the same table - they're the same chain.<br> NOTE: after you've run ''create_chain'', you still have to switch context to create rules in the new chain! example:<br> create_chain fun-filter context fun-filter filter accept -p tcp --dport 22 This will result in iptables -N FUN-FILTER -t filter iptables -A FUN-FILTER -t filter -p tcp --dport 22 --jump ACCEPT == Target keyword: accept == '''''accept [log [msg <message>]] <qualifiers>'''''<br> If a network packet matches the qualifiers, then it will be accepted (passed) through the table/chain defined in the context where you put the accept rule. Example: <pre>context "INPUT" "filter" accept –p tcp --dport 22</pre> Iceditch works this out to iptables –t filter –A INPUT –p tcp –-dport 22 –-jump ACCEPT Should you want to log the packet, you’d use context "INPUT" "filter" accept log –p tcp --dport 22 Iceditch works this out to iptables –t filter –A INPUT –p tcp –-dport 22 \ –-jump LOG --log-prefix INPUT_accept iptables –t filter –A INPUT –p tcp –-dport 22 –-jump ACCEPT Note: the ACCEPT target is valid in any user-manipulable table/chain combination == Target keyword: classify == '''''classify <classval> [log [msg <message>]] <qualifiers>'''''<br> If a packet travelling through the mangle table in the POSTROUTING chain matches the qualifiers, then it will be classified with the <classval> specified. An example: classify 2:11 –p tcp --dport 22 The script works this out to iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump CLASSIFY --setclass 2:11 Should you want to also log the packet, you’d use classify 2:11 log –p tcp --dport 22 The script works this out to iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump LOG \ --log-prefix classified_2:11: iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump CLASSIFY \ --setclass 2:11 Should you not give a msg, then the log-prefix becomes POSTROUTING_CLASSIFY_set_<classval>. Because of how iptables handles the CLASSIFY target, you can only use it in contexts where the chain is “POSTROUTING” and the table is “mangle”. == Target keyword: dnat == '''''dnat [to] <a1[-a2][:p1[-p2]]> [log [msg <message>]] <qualifiers>'''''<br> In the above, a1 and a2 are used to specify a (range of) IP address(es); for TCP and UDP protocols, a destination port or port range can be provided. Note that the "to" in the command is optional, and serves only readability.<br> If a packet matches the qualifiers, then it will be destination-NATted to the provided IP address or address range. For example, if you want to DNAT port 81 on your external interface eth1 to an internal webserver on 10.0.0.1, you could use context "PREROUTING" "nat" dnat to 10.0.0.1:80 –p tcp –i eth1 –-dport 81 If you give a range of IP addresses, then the DNAT logic of IPtables will randomly pick an address and DNAT the packet there. However, note that a single stream will always use the same IP address from that range, and that each stream will randomly be given an IP address that it will always be destined for, within that stream.<br> Furthermore, note that the DNAT target is only available within the PREROUTING and OUTPUT chains in the nat table, and any of the chains called upon from any of those listed chains. Note that chains containing DNAT targets may not be used from any other chains, such as the POSTROUTING chain. However, the bad news is that Iceditch currently does not know how to check for the latter case, so the dnat keyword only works from contexts "PREROUTING" "nat" and "OUTPUT" "nat". == Target keyword: drop == '''''drop [log [msg <message>]] <qualifiers> '''''<br> In essence, this does the same as the “accept” target keyword, only it jumps to DROP instead of ACCEPT. Thus any packet matching the qualifiers gets discarded; it will not get sent on to its final destination (or next hop), it will not get processed by any other firewall rule, and the sender of the packet is unaware of your treatment of his packet. Should you want to also log the packet, you’d use context "FORWARD" "filter" drop log –p tcp -s 10.0.0.0/16 The script works this out to iptables –t filter –A FORWARD –p tcp -s 10.0.0.0/16 –-jump LOG \ --log-prefix FORWARD_DROP: iptables –t filter –A FORWARD –p tcp -s 10.0.0.0/16 –-jump DROP However, be advised that using DROP may leave dead sockets on either the sending or receiving host. If you do not wish that, you might be better of using REJECT. On the other hand, dropping packets is a nice way of appearing like a black hole, so it's the weapon of choice against port scanners and the likes.<br> The DROP target can be used in any chain in any table. == Target keyword: log == '''''log [(msg|message) <message>] [(lvl|level) <loglevel>] <qualifiers>'''''<br> Sometimes, the standard ''log'' parameter is just not enough. This can be the case when you want to log a packet to a log-level other than the default level, which for most systems is ''4'' (''warning''). Furthermore, maybe you want to log a certain type or class of packets, without performing an action on those packets just yet. For this reason, AND for flexibility and clarity, Iceditch has the dedicated target keyword ''log''.<br> Just as when you use the ''log'' parameter after another target, Iceditch will call the log target specified in the Iceditch [[Iceditch file structure | config file]]. Standard this is LOG, but optionally you could specify ULOG in the config file. ''<message>'' can be any string of 32 characters max (letters, numbers and underscores; no spaces); the ''<loglevel>'' can either be numeric or the corresponding keyword (e.g. ''crit''); Iceditch translates it to its numeric value anyway. Furthermore, the order in which <msg> and <lvl> appear is not important.<br> Depending on which log target you have specified, there are some options you can use with the Iceditch target keyword ''log''; it is currently deemed unnecessary to make specific Iceditch parameters for them, but as a reference we'll list the official IPtables options here, which you can put in the <qualifiers> list: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" ! colspan="2" style="background:#ffdead;"|LOG options | ! colspan="2" style="background:#ffdead;"|ULOG options |- !style="background:#ffdead;"|Option !style="background:#ffdead;"|Description | !style="background:#ffdead;"|Option !style="background:#ffdead;"|Description |- | --log-ip-options |Makes Netfilter include the IP options in the log entry | | --ulog-cprange <''size''> |log the first ''size'' bytes of each packet |- | --log-tcp-options |Makes Netfilter include the TCP options in the log entry | | --ulog-nlgroup <''nlgroup''> |Log to Netlink group number ''nlgroup'' (must match ''/etc/ulogd.conf'') |- | --log-tcp-sequence |Makes Netfilter include the TCP sequence number in the log entry | | --ulog-qthreshold <''value''> |Queue ''value'' packets before sending them to ''ulogd'' (default = 1, max = 50) |- |} <br> For completeness, we here reproduce the list of logging levels that ''log'' understands: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Level !style="background:#ffdead;"|Description |- |0 |''emerg'' or ''panic'' |- |1 |''alert'' |- |2 |''crit'' |- |3 |''err'' |- |4 |''warn'' (default) |- |5 |''notice'' |- |6 |''info'' |- |7 |''debug'' |- |} Now an example: context "INPUT" "filter" log lvl info msg SSH_incoming -p tcp --dport 22 -i $inetIF Iceditch works this out into iptables -A INPUT -t filter -p tcp --dport 22 -i $inetIF --jump ULOG --ulog-prefix "SSH_incoming" --log-level 6 == Target keyword: mark == '''''mark <markval> [log [msg <message>]] <qualifiers>'''''<br> If a packet matches the qualifiers, then it will be marked with the <markval> specified. An example from the context “PREROUTING” “mangle”: mark 2 –p tcp --dport 22 Iceditch works this out to iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump MARK --setmark 2 Should you want to also log the packet, you’d use mark 2 log –p tcp --dport 22 Iceditch works this out to iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump LOG \ --log-prefix PREROUTING_MARK_set_2: iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump MARK --setmark 2 Because of how iptables handles the MARK target, you can only use it in contexts where the table is “mangle”. == Target keyword: redirect == '''''redirect [to <to-ports>] [log [msg <message>]] <qualifiers>'''''<br> If a packet matches the qualifiers, then it will be redirected to the local machine, by setting the destination IP to a fitting IP address of the local machine (i.e. 127.0.0.1, or the first-bound IP address of the interface over which it came in. Additionally, by specifying “to <to-ports>” you can have the destination ports redirected to a port or portrange. <to-ports> can either be a port number (e.g. 8080) or a port range (e.g. 6661-6669; the latter is inclusive). Example for a transparent HTTP proxy: context "OUTPUT" "nat" redirect to 8080 –p tcp --dport 80 Iceditch works this out to iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump REDIRECT –to-ports 8080 Should you want to log the packet, you could use redirect to 8080 log –p tcp --dport 80 Iceditch works this out to iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump LOG \ --log-prefix OUTPUT_REDIRECT_to_8080: iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump REDIRECT –-to-ports 8080 Because of how iptables handles the REDIRECT target, you can only use it in contexts where the table is “nat” and the chain is PREROUTING or OUTPUT. == Target keyword: reject == '''''reject [with <type>] [log [msg <message>]] <qualifiers>'''''<br> In essence, this does the same as the “drop” target keyword, only it jumps to REJECT instead of DROP. This means the packet is discarded (just as with DROP), but the sender is notified using ICMP (by default, your machine will send an ICMP-packet of type "icmp-port-unreachable"). Because of how iptables handles the REJECT target, you can only use it in contexts where the table is “filter”. Optionally, you can follow “reject” with the keyword “with”, and then use one of the following rejection types: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Type !style="background:#ffdead;"|Description |- | icmp-host-prohibited | will send an ICMP-message "host prohibited" |- | icmp-host-unreachable | will send an ICMP-message "host unreachable" |- | icmp-net-prohibited | will send an ICMP-message "net prohibited" |- | icmp-net-unreachable | will send an ICMP-message "net unreachable" |- | icmp-port-unreachable | DEFAULT; will send an ICMP-message "port unreachable" |- | icmp-proto-unreachable | DEFAULT; will send an ICMP-message "protocol unreachable" |- | tcp-reset | will send a TCP reset, a packet with the RST flag set (as a response to a TCP packet only) |- | host-prohib | synonymous to icmp-host-prohibited |- | host-unreach | synonymous to icmp-host-unreachable |- | net-prohib | synonymous to icmp-net-prohibited |- | net-unreach | synonymous to icmp-net-unreachable |- | port-unreach | synonymous to icmp-port-unreachable |- | proto-unreach | synonymous to icmp-proto-unreachable |- |} If you don’t specify “with <type>”, then netfilter will assume icmp-port-unreachable. Thus, should you want to reject a packet in context filter_INPUT (and log it) with reason net-prohib, you’d use reject with net-prohib log –p tcp –i eth0 --dport 22 Iceditch works this out to iptables –t filter –A INPUT –p tcp –i eth0 –-dport 22 –-jump LOG \ --log-prefix INPUT_REJECT_with_net-prohib: iptables –t filter –A INPUT –p tcp –i eth0 –-dport 22 \ –-jump REJECT –-reject-with net-prohib –p tcp –i eth0 –-dport 22 == Target keyword: snat== '''''snat [to <a1[-a2][:p1-p2]]> [to <a3[-a4][:p3-p4]]>] ] [log [msg <message>] ] <qualifiers>'''''<br> This keyword is only valid in the chain POSTROUTING, table nat. And ofcourse, source NATting does you little good if you haven't enabled forwarding (e.g. use this machine as a router for other machines on your network).<br> Calling snat with the right parameters will create a Source NATting rule for you, whereby a packet matching the qualifiers will be source NATted using the source IP address ''a1'' (or the range ''a1-a2''). Ofcourse, ''a1[-a2]'' should be valid IP address(es) of the firewalling machine.<br> Furthermore, if a port range ''p1-p2'' is specified, then you'll limit the range of ports that ''snat'' will use outbound (only valid for TCP or UDP packets).<br> Finally, it is possible to specify ''multiple'' IP address ranges and port ranges, using multiple ''to <a1[-a2][:p1-p2]]'' declarations in succession.<br> An example would be: context "POSTROUTING" "nat" snat to $inetIP -o $inetIF ! --src $inetIP If the variable ''$inetIP'' contains your public IP (e.g. 212.238.151.72), and ''$inetIF'' your interface connected to the Internet (e.g. ''eth0''), then this rule would expand to iptables -A POSTROUTING -t nat -o eth0 ! --src 212.238.151.72 -j SNAT --to-source 212.238.151.72 This would cause Iceditch to source NAT any outbound packet that is NOT sent by your firewall itself; in effect your server is now a nice fullblown NAT router for all machines on your private network. f2fe5ddbec925b216724345a288254250c0aa1f4 1603 1602 2008-08-06T18:59:05Z Saruman! 2 /* Parameter: log */ default prefix length is 29, not 31 wikitext text/x-wiki == Parameter: log == ''target '''log [(msg|message) <message>]''' <qualifiers>''<br> After most keywords, a "log" parameter can be added (see below). If the "log" parameter is followed by "msg" (or "message"), then the parameter following "msg" is read and used as log-prefix. The parameter is not allowed to have whitespace (that limitation is Iceditch-specific, not IPtables-related), and the maximum length of the log-prefix is determined by your version of netfilter/IPtables and your IPtables logging utility (syslogemu or ulog); this limit is usually some 29 characters. Note that Iceditch does not perform any sanity checks on the message. Thus a packet matching the rule will be logged with the default setting of the "log" target. If the "log" parameter is ''not'' followed by "msg", then the packet will be logged with a default log message, being "&lt;table&gt;_<chain>_<target>" and all the other default setting of the "log" target. Thus, should you want to log a packet with more control over the logging parameters, then you need an extra line, beginning with the ''target keyword'' "log", instead of just following the target keyword with parameter ''log''. For more information, see the target keyword "log" below. == Context keyword: context == '''''context <chain> &lt;table&gt;'''''<br> Every IPtables rule is written to a chain in a table; with Iceditch, you don't have to specify the chain and table in every line. Just precede the lines with the ''context'' statement. Example: context POSTROUTING nat Notes: the order of chain and table does not matter; ''context nat POSTROUTING'' works just as well. Furthermore, <chain> and &lt;table&gt; have been made case-insensitive; whatever you specify as chain will be translated to uppercase, whatever you specify as table will be translated to lowercase. This gives you the possibility to write the context as you like to read it, e.g. ''context Postrouting Nat''; after processing this, Iceditch will have two variables $CHAIN="POSTROUTING" and $TABLE="nat" that it will use in every following command. For example: context "Input" "fIlTeR" accept -p tcp --dport 22 will result in the following IPtables call: iptables -A INPUT -t filter -p tcp --dport 22 --jump ACCEPT If you do NOT specify a [[Iceditch IPtables language | valid combination]] of chain and table, the execution of Iceditch will halt with a fatal error. It is allowed (but not recommended) to call ''context'' multiple times for the same combination of chain and table; the order in which the rules are added to that chain in that table, is the same in which they appear in your rulefile, top to bottom. This is not recommended, because we feel it decreases readability, and thus maintainability, of the rules file. But hey, it's going to be ''your'' rulefile anyway... == Context keyword: create_chain == '''''create_chain <chain> [&lt;table&gt;]'''''<br> This command creates a new chain named <chain>, in the specified table &lt;table&gt;. If no table is specified, then the ''filter'' table is assumed. Just as with the ''context'' command, the <chain> name you specify will be translated to all uppercase.<br> The name for your new chain must be unique, although just like the built-in chains, you can specify the same name in different tables. If you create "fun-filter" in table ''filter'', and then create a "fun-filter" in table ''nat'', then you actually have two different chains. But remember: since Iceditch translates every chain name to uppercase, you can't create "Fun-filter" AND "fun-FILTER" in the same table - they're the same chain.<br> NOTE: after you've run ''create_chain'', you still have to switch context to create rules in the new chain! example:<br> create_chain fun-filter context fun-filter filter accept -p tcp --dport 22 This will result in iptables -N FUN-FILTER -t filter iptables -A FUN-FILTER -t filter -p tcp --dport 22 --jump ACCEPT == Target keyword: accept == '''''accept [log [msg <message>]] <qualifiers>'''''<br> If a network packet matches the qualifiers, then it will be accepted (passed) through the table/chain defined in the context where you put the accept rule. Example: <pre>context "INPUT" "filter" accept –p tcp --dport 22</pre> Iceditch works this out to iptables –t filter –A INPUT –p tcp –-dport 22 –-jump ACCEPT Should you want to log the packet, you’d use context "INPUT" "filter" accept log –p tcp --dport 22 Iceditch works this out to iptables –t filter –A INPUT –p tcp –-dport 22 \ –-jump LOG --log-prefix INPUT_accept iptables –t filter –A INPUT –p tcp –-dport 22 –-jump ACCEPT Note: the ACCEPT target is valid in any user-manipulable table/chain combination == Target keyword: classify == '''''classify <classval> [log [msg <message>]] <qualifiers>'''''<br> If a packet travelling through the mangle table in the POSTROUTING chain matches the qualifiers, then it will be classified with the <classval> specified. An example: classify 2:11 –p tcp --dport 22 The script works this out to iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump CLASSIFY --setclass 2:11 Should you want to also log the packet, you’d use classify 2:11 log –p tcp --dport 22 The script works this out to iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump LOG \ --log-prefix classified_2:11: iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump CLASSIFY \ --setclass 2:11 Should you not give a msg, then the log-prefix becomes POSTROUTING_CLASSIFY_set_<classval>. Because of how iptables handles the CLASSIFY target, you can only use it in contexts where the chain is “POSTROUTING” and the table is “mangle”. == Target keyword: dnat == '''''dnat [to] <a1[-a2][:p1[-p2]]> [log [msg <message>]] <qualifiers>'''''<br> In the above, a1 and a2 are used to specify a (range of) IP address(es); for TCP and UDP protocols, a destination port or port range can be provided. Note that the "to" in the command is optional, and serves only readability.<br> If a packet matches the qualifiers, then it will be destination-NATted to the provided IP address or address range. For example, if you want to DNAT port 81 on your external interface eth1 to an internal webserver on 10.0.0.1, you could use context "PREROUTING" "nat" dnat to 10.0.0.1:80 –p tcp –i eth1 –-dport 81 If you give a range of IP addresses, then the DNAT logic of IPtables will randomly pick an address and DNAT the packet there. However, note that a single stream will always use the same IP address from that range, and that each stream will randomly be given an IP address that it will always be destined for, within that stream.<br> Furthermore, note that the DNAT target is only available within the PREROUTING and OUTPUT chains in the nat table, and any of the chains called upon from any of those listed chains. Note that chains containing DNAT targets may not be used from any other chains, such as the POSTROUTING chain. However, the bad news is that Iceditch currently does not know how to check for the latter case, so the dnat keyword only works from contexts "PREROUTING" "nat" and "OUTPUT" "nat". == Target keyword: drop == '''''drop [log [msg <message>]] <qualifiers> '''''<br> In essence, this does the same as the “accept” target keyword, only it jumps to DROP instead of ACCEPT. Thus any packet matching the qualifiers gets discarded; it will not get sent on to its final destination (or next hop), it will not get processed by any other firewall rule, and the sender of the packet is unaware of your treatment of his packet. Should you want to also log the packet, you’d use context "FORWARD" "filter" drop log –p tcp -s 10.0.0.0/16 The script works this out to iptables –t filter –A FORWARD –p tcp -s 10.0.0.0/16 –-jump LOG \ --log-prefix FORWARD_DROP: iptables –t filter –A FORWARD –p tcp -s 10.0.0.0/16 –-jump DROP However, be advised that using DROP may leave dead sockets on either the sending or receiving host. If you do not wish that, you might be better of using REJECT. On the other hand, dropping packets is a nice way of appearing like a black hole, so it's the weapon of choice against port scanners and the likes.<br> The DROP target can be used in any chain in any table. == Target keyword: log == '''''log [(msg|message) <message>] [(lvl|level) <loglevel>] <qualifiers>'''''<br> Sometimes, the standard ''log'' parameter is just not enough. This can be the case when you want to log a packet to a log-level other than the default level, which for most systems is ''4'' (''warning''). Furthermore, maybe you want to log a certain type or class of packets, without performing an action on those packets just yet. For this reason, AND for flexibility and clarity, Iceditch has the dedicated target keyword ''log''.<br> Just as when you use the ''log'' parameter after another target, Iceditch will call the log target specified in the Iceditch [[Iceditch file structure | config file]]. Standard this is LOG, but optionally you could specify ULOG in the config file. ''<message>'' can be any string of 32 characters max (letters, numbers and underscores; no spaces); the ''<loglevel>'' can either be numeric or the corresponding keyword (e.g. ''crit''); Iceditch translates it to its numeric value anyway. Furthermore, the order in which <msg> and <lvl> appear is not important.<br> Depending on which log target you have specified, there are some options you can use with the Iceditch target keyword ''log''; it is currently deemed unnecessary to make specific Iceditch parameters for them, but as a reference we'll list the official IPtables options here, which you can put in the <qualifiers> list: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" ! colspan="2" style="background:#ffdead;"|LOG options | ! colspan="2" style="background:#ffdead;"|ULOG options |- !style="background:#ffdead;"|Option !style="background:#ffdead;"|Description | !style="background:#ffdead;"|Option !style="background:#ffdead;"|Description |- | --log-ip-options |Makes Netfilter include the IP options in the log entry | | --ulog-cprange <''size''> |log the first ''size'' bytes of each packet |- | --log-tcp-options |Makes Netfilter include the TCP options in the log entry | | --ulog-nlgroup <''nlgroup''> |Log to Netlink group number ''nlgroup'' (must match ''/etc/ulogd.conf'') |- | --log-tcp-sequence |Makes Netfilter include the TCP sequence number in the log entry | | --ulog-qthreshold <''value''> |Queue ''value'' packets before sending them to ''ulogd'' (default = 1, max = 50) |- |} <br> For completeness, we here reproduce the list of logging levels that ''log'' understands: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Level !style="background:#ffdead;"|Description |- |0 |''emerg'' or ''panic'' |- |1 |''alert'' |- |2 |''crit'' |- |3 |''err'' |- |4 |''warn'' (default) |- |5 |''notice'' |- |6 |''info'' |- |7 |''debug'' |- |} Now an example: context "INPUT" "filter" log lvl info msg SSH_incoming -p tcp --dport 22 -i $inetIF Iceditch works this out into iptables -A INPUT -t filter -p tcp --dport 22 -i $inetIF --jump ULOG --ulog-prefix "SSH_incoming" --log-level 6 == Target keyword: mark == '''''mark <markval> [log [msg <message>]] <qualifiers>'''''<br> If a packet matches the qualifiers, then it will be marked with the <markval> specified. An example from the context “PREROUTING” “mangle”: mark 2 –p tcp --dport 22 Iceditch works this out to iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump MARK --setmark 2 Should you want to also log the packet, you’d use mark 2 log –p tcp --dport 22 Iceditch works this out to iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump LOG \ --log-prefix PREROUTING_MARK_set_2: iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump MARK --setmark 2 Because of how iptables handles the MARK target, you can only use it in contexts where the table is “mangle”. == Target keyword: redirect == '''''redirect [to <to-ports>] [log [msg <message>]] <qualifiers>'''''<br> If a packet matches the qualifiers, then it will be redirected to the local machine, by setting the destination IP to a fitting IP address of the local machine (i.e. 127.0.0.1, or the first-bound IP address of the interface over which it came in. Additionally, by specifying “to <to-ports>” you can have the destination ports redirected to a port or portrange. <to-ports> can either be a port number (e.g. 8080) or a port range (e.g. 6661-6669; the latter is inclusive). Example for a transparent HTTP proxy: context "OUTPUT" "nat" redirect to 8080 –p tcp --dport 80 Iceditch works this out to iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump REDIRECT –to-ports 8080 Should you want to log the packet, you could use redirect to 8080 log –p tcp --dport 80 Iceditch works this out to iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump LOG \ --log-prefix OUTPUT_REDIRECT_to_8080: iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump REDIRECT –-to-ports 8080 Because of how iptables handles the REDIRECT target, you can only use it in contexts where the table is “nat” and the chain is PREROUTING or OUTPUT. == Target keyword: reject == '''''reject [with <type>] [log [msg <message>]] <qualifiers>'''''<br> In essence, this does the same as the “drop” target keyword, only it jumps to REJECT instead of DROP. This means the packet is discarded (just as with DROP), but the sender is notified using ICMP (by default, your machine will send an ICMP-packet of type "icmp-port-unreachable"). Because of how iptables handles the REJECT target, you can only use it in contexts where the table is “filter”. Optionally, you can follow “reject” with the keyword “with”, and then use one of the following rejection types: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Type !style="background:#ffdead;"|Description |- | icmp-host-prohibited | will send an ICMP-message "host prohibited" |- | icmp-host-unreachable | will send an ICMP-message "host unreachable" |- | icmp-net-prohibited | will send an ICMP-message "net prohibited" |- | icmp-net-unreachable | will send an ICMP-message "net unreachable" |- | icmp-port-unreachable | DEFAULT; will send an ICMP-message "port unreachable" |- | icmp-proto-unreachable | DEFAULT; will send an ICMP-message "protocol unreachable" |- | tcp-reset | will send a TCP reset, a packet with the RST flag set (as a response to a TCP packet only) |- | host-prohib | synonymous to icmp-host-prohibited |- | host-unreach | synonymous to icmp-host-unreachable |- | net-prohib | synonymous to icmp-net-prohibited |- | net-unreach | synonymous to icmp-net-unreachable |- | port-unreach | synonymous to icmp-port-unreachable |- | proto-unreach | synonymous to icmp-proto-unreachable |- |} If you don’t specify “with <type>”, then netfilter will assume icmp-port-unreachable. Thus, should you want to reject a packet in context filter_INPUT (and log it) with reason net-prohib, you’d use reject with net-prohib log –p tcp –i eth0 --dport 22 Iceditch works this out to iptables –t filter –A INPUT –p tcp –i eth0 –-dport 22 –-jump LOG \ --log-prefix INPUT_REJECT_with_net-prohib: iptables –t filter –A INPUT –p tcp –i eth0 –-dport 22 \ –-jump REJECT –-reject-with net-prohib –p tcp –i eth0 –-dport 22 == Target keyword: snat== '''''snat [to <a1[-a2][:p1-p2]]> [to <a3[-a4][:p3-p4]]>] ] [log [msg <message>] ] <qualifiers>'''''<br> This keyword is only valid in the chain POSTROUTING, table nat. And ofcourse, source NATting does you little good if you haven't enabled forwarding (e.g. use this machine as a router for other machines on your network).<br> Calling snat with the right parameters will create a Source NATting rule for you, whereby a packet matching the qualifiers will be source NATted using the source IP address ''a1'' (or the range ''a1-a2''). Ofcourse, ''a1[-a2]'' should be valid IP address(es) of the firewalling machine.<br> Furthermore, if a port range ''p1-p2'' is specified, then you'll limit the range of ports that ''snat'' will use outbound (only valid for TCP or UDP packets).<br> Finally, it is possible to specify ''multiple'' IP address ranges and port ranges, using multiple ''to <a1[-a2][:p1-p2]]'' declarations in succession.<br> An example would be: context "POSTROUTING" "nat" snat to $inetIP -o $inetIF ! --src $inetIP If the variable ''$inetIP'' contains your public IP (e.g. 212.238.151.72), and ''$inetIF'' your interface connected to the Internet (e.g. ''eth0''), then this rule would expand to iptables -A POSTROUTING -t nat -o eth0 ! --src 212.238.151.72 -j SNAT --to-source 212.238.151.72 This would cause Iceditch to source NAT any outbound packet that is NOT sent by your firewall itself; in effect your server is now a nice fullblown NAT router for all machines on your private network. cec14310ae874a1ed072966cb42e07305085853f 1604 1603 2008-08-06T19:27:04Z Saruman! 2 Target keyword: masquerade added wikitext text/x-wiki == Parameter: log == ''target '''log [(msg|message) <message>]''' <qualifiers>''<br> After most keywords, a "log" parameter can be added (see below). If the "log" parameter is followed by "msg" (or "message"), then the parameter following "msg" is read and used as log-prefix. The parameter is not allowed to have whitespace (that limitation is Iceditch-specific, not IPtables-related), and the maximum length of the log-prefix is determined by your version of netfilter/IPtables and your IPtables logging utility (syslogemu or ulog); this limit is usually some 29 characters. Note that Iceditch does not perform any sanity checks on the message. Thus a packet matching the rule will be logged with the default setting of the "log" target. If the "log" parameter is ''not'' followed by "msg", then the packet will be logged with a default log message, being "&lt;table&gt;_<chain>_<target>" and all the other default setting of the "log" target. Thus, should you want to log a packet with more control over the logging parameters, then you need an extra line, beginning with the ''target keyword'' "log", instead of just following the target keyword with parameter ''log''. For more information, see the target keyword "log" below. == Context keyword: context == '''''context <chain> &lt;table&gt;'''''<br> Every IPtables rule is written to a chain in a table; with Iceditch, you don't have to specify the chain and table in every line. Just precede the lines with the ''context'' statement. Example: context POSTROUTING nat Notes: the order of chain and table does not matter; ''context nat POSTROUTING'' works just as well. Furthermore, <chain> and &lt;table&gt; have been made case-insensitive; whatever you specify as chain will be translated to uppercase, whatever you specify as table will be translated to lowercase. This gives you the possibility to write the context as you like to read it, e.g. ''context Postrouting Nat''; after processing this, Iceditch will have two variables $CHAIN="POSTROUTING" and $TABLE="nat" that it will use in every following command. For example: context "Input" "fIlTeR" accept -p tcp --dport 22 will result in the following IPtables call: iptables -A INPUT -t filter -p tcp --dport 22 --jump ACCEPT If you do NOT specify a [[Iceditch IPtables language | valid combination]] of chain and table, the execution of Iceditch will halt with a fatal error. It is allowed (but not recommended) to call ''context'' multiple times for the same combination of chain and table; the order in which the rules are added to that chain in that table, is the same in which they appear in your rulefile, top to bottom. This is not recommended, because we feel it decreases readability, and thus maintainability, of the rules file. But hey, it's going to be ''your'' rulefile anyway... == Context keyword: create_chain == '''''create_chain <chain> [&lt;table&gt;]'''''<br> This command creates a new chain named <chain>, in the specified table &lt;table&gt;. If no table is specified, then the ''filter'' table is assumed. Just as with the ''context'' command, the <chain> name you specify will be translated to all uppercase.<br> The name for your new chain must be unique, although just like the built-in chains, you can specify the same name in different tables. If you create "fun-filter" in table ''filter'', and then create a "fun-filter" in table ''nat'', then you actually have two different chains. But remember: since Iceditch translates every chain name to uppercase, you can't create "Fun-filter" AND "fun-FILTER" in the same table - they're the same chain.<br> NOTE: after you've run ''create_chain'', you still have to switch context to create rules in the new chain! example:<br> create_chain fun-filter context fun-filter filter accept -p tcp --dport 22 This will result in iptables -N FUN-FILTER -t filter iptables -A FUN-FILTER -t filter -p tcp --dport 22 --jump ACCEPT == Target keyword: accept == '''''accept [log [msg <message>]] <qualifiers>'''''<br> If a network packet matches the qualifiers, then it will be accepted (passed) through the table/chain defined in the context where you put the accept rule. Example: <pre>context "INPUT" "filter" accept –p tcp --dport 22</pre> Iceditch works this out to iptables –t filter –A INPUT –p tcp –-dport 22 –-jump ACCEPT Should you want to log the packet, you’d use context "INPUT" "filter" accept log –p tcp --dport 22 Iceditch works this out to iptables –t filter –A INPUT –p tcp –-dport 22 \ –-jump LOG --log-prefix INPUT_accept iptables –t filter –A INPUT –p tcp –-dport 22 –-jump ACCEPT Note: the ACCEPT target is valid in any user-manipulable table/chain combination == Target keyword: classify == '''''classify <classval> [log [msg <message>]] <qualifiers>'''''<br> If a packet travelling through the mangle table in the POSTROUTING chain matches the qualifiers, then it will be classified with the <classval> specified. An example: classify 2:11 –p tcp --dport 22 The script works this out to iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump CLASSIFY --setclass 2:11 Should you want to also log the packet, you’d use classify 2:11 log –p tcp --dport 22 The script works this out to iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump LOG \ --log-prefix classified_2:11: iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump CLASSIFY \ --setclass 2:11 Should you not give a msg, then the log-prefix becomes POSTROUTING_CLASSIFY_set_<classval>. Because of how iptables handles the CLASSIFY target, you can only use it in contexts where the chain is “POSTROUTING” and the table is “mangle”. == Target keyword: dnat == '''''dnat [to] <a1[-a2][:p1[-p2]]> [log [msg <message>]] <qualifiers>'''''<br> In the above, a1 and a2 are used to specify a (range of) IP address(es); for TCP and UDP protocols, a destination port or port range can be provided. Note that the "to" in the command is optional, and serves only readability.<br> If a packet matches the qualifiers, then it will be destination-NATted to the provided IP address or address range. For example, if you want to DNAT port 81 on your external interface eth1 to an internal webserver on 10.0.0.1, you could use context "PREROUTING" "nat" dnat to 10.0.0.1:80 –p tcp –i eth1 –-dport 81 If you give a range of IP addresses, then the DNAT logic of IPtables will randomly pick an address and DNAT the packet there. However, note that a single stream will always use the same IP address from that range, and that each stream will randomly be given an IP address that it will always be destined for, within that stream.<br> Furthermore, note that the DNAT target is only available within the PREROUTING and OUTPUT chains in the nat table, and any of the chains called upon from any of those listed chains. Note that chains containing DNAT targets may not be used from any other chains, such as the POSTROUTING chain. However, the bad news is that Iceditch currently does not know how to check for the latter case, so the dnat keyword only works from contexts "PREROUTING" "nat" and "OUTPUT" "nat". == Target keyword: drop == '''''drop [log [msg <message>]] <qualifiers> '''''<br> In essence, this does the same as the “accept” target keyword, only it jumps to DROP instead of ACCEPT. Thus any packet matching the qualifiers gets discarded; it will not get sent on to its final destination (or next hop), it will not get processed by any other firewall rule, and the sender of the packet is unaware of your treatment of his packet. Should you want to also log the packet, you’d use context "FORWARD" "filter" drop log –p tcp -s 10.0.0.0/16 The script works this out to iptables –t filter –A FORWARD –p tcp -s 10.0.0.0/16 –-jump LOG \ --log-prefix FORWARD_DROP: iptables –t filter –A FORWARD –p tcp -s 10.0.0.0/16 –-jump DROP However, be advised that using DROP may leave dead sockets on either the sending or receiving host. If you do not wish that, you might be better of using REJECT. On the other hand, dropping packets is a nice way of appearing like a black hole, so it's the weapon of choice against port scanners and the likes.<br> The DROP target can be used in any chain in any table. == Target keyword: log == '''''log [(msg|message) <message>] [(lvl|level) <loglevel>] <qualifiers>'''''<br> Sometimes, the standard ''log'' parameter is just not enough. This can be the case when you want to log a packet to a log-level other than the default level, which for most systems is ''4'' (''warning''). Furthermore, maybe you want to log a certain type or class of packets, without performing an action on those packets just yet. For this reason, AND for flexibility and clarity, Iceditch has the dedicated target keyword ''log''.<br> Just as when you use the ''log'' parameter after another target, Iceditch will call the log target specified in the Iceditch [[Iceditch file structure | config file]]. Standard this is LOG, but optionally you could specify ULOG in the config file. ''<message>'' can be any string of 32 characters max (letters, numbers and underscores; no spaces); the ''<loglevel>'' can either be numeric or the corresponding keyword (e.g. ''crit''); Iceditch translates it to its numeric value anyway. Furthermore, the order in which <msg> and <lvl> appear is not important.<br> Depending on which log target you have specified, there are some options you can use with the Iceditch target keyword ''log''; it is currently deemed unnecessary to make specific Iceditch parameters for them, but as a reference we'll list the official IPtables options here, which you can put in the <qualifiers> list: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" ! colspan="2" style="background:#ffdead;"|LOG options | ! colspan="2" style="background:#ffdead;"|ULOG options |- !style="background:#ffdead;"|Option !style="background:#ffdead;"|Description | !style="background:#ffdead;"|Option !style="background:#ffdead;"|Description |- | --log-ip-options |Makes Netfilter include the IP options in the log entry | | --ulog-cprange <''size''> |log the first ''size'' bytes of each packet |- | --log-tcp-options |Makes Netfilter include the TCP options in the log entry | | --ulog-nlgroup <''nlgroup''> |Log to Netlink group number ''nlgroup'' (must match ''/etc/ulogd.conf'') |- | --log-tcp-sequence |Makes Netfilter include the TCP sequence number in the log entry | | --ulog-qthreshold <''value''> |Queue ''value'' packets before sending them to ''ulogd'' (default = 1, max = 50) |- |} <br> For completeness, we here reproduce the list of logging levels that ''log'' understands: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Level !style="background:#ffdead;"|Description |- |0 |''emerg'' or ''panic'' |- |1 |''alert'' |- |2 |''crit'' |- |3 |''err'' |- |4 |''warn'' (default) |- |5 |''notice'' |- |6 |''info'' |- |7 |''debug'' |- |} Now an example: context "INPUT" "filter" log lvl info msg SSH_incoming -p tcp --dport 22 -i $inetIF Iceditch works this out into iptables -A INPUT -t filter -p tcp --dport 22 -i $inetIF --jump ULOG --ulog-prefix "SSH_incoming" --log-level 6 == Target keyword: mark == '''''mark <markval> [log [msg <message>]] <qualifiers>'''''<br> If a packet matches the qualifiers, then it will be marked with the <markval> specified. An example from the context “PREROUTING” “mangle”: mark 2 –p tcp --dport 22 Iceditch works this out to iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump MARK --setmark 2 Should you want to also log the packet, you’d use mark 2 log –p tcp --dport 22 Iceditch works this out to iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump LOG \ --log-prefix PREROUTING_MARK_set_2: iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump MARK --setmark 2 Because of how iptables handles the MARK target, you can only use it in contexts where the table is “mangle”. == Target keyword: masquerade == '''''masquerade <iface> [to <p1[-p2]>] [log [msg <message>]] <qualifiers>''''' <iface> is the outward facing network interface that we should be masquerading.<br> The MASQUERADE target is used basically the same as the SNAT target, but it does not require any --to-source option. The reason for this is that the MASQUERADE target was made to work with connections which get dynamic IP addresses when connecting to the network in question, for example dial-up connections, or DHCP connections. This means that you should only use the MASQUERADE target with dynamically assigned IP connections, which we don't know the actual IP address of in advance. If you have a static IP connection, you should instead use the SNAT target.<br> When you masquerade a connection, it means that we set the IP address used on a specific network ''interface'', instead of getting it from the --to-source option. The necessary IP address is automatically grabbed from the information about the specific interface. Using the ''masquerade'' keyword also has the advantage that connections are forgotten when an interface goes down, which is extremely good if we, for example, kill a specific interface. If we would have used the SNAT target, we may have been left with a lot of old connection tracking data, which would be kept in connection tracking memory for days. forgetting about connections is, in general, the correct behavior when dealing with dial-up lines that are probably assigned a different IP every time they are brought up. In case we are assigned a different IP, the connection is lost anyways, and it is more or less idiotic to keep the entry around.<br> It is still possible to use the MASQUERADE target instead of SNAT even though you do have a static IP; however, it is not favorable since it will add extra overhead, and there may be inconsistencies in the future which will thwart your existing scripts and render them "unusable".<br> Note that the MASQUERADE target is only valid within the POSTROUTING chain in the nat table, just as the SNAT target. The MASQUERADE target takes one option specified below, which is optional. == Target keyword: redirect == '''''redirect [to <to-ports>] [log [msg <message>]] <qualifiers>'''''<br> If a packet matches the qualifiers, then it will be redirected to the local machine, by setting the destination IP to a fitting IP address of the local machine (i.e. 127.0.0.1, or the first-bound IP address of the interface over which it came in. Additionally, by specifying “to <to-ports>” you can have the destination ports redirected to a port or portrange. <to-ports> can either be a port number (e.g. 8080) or a port range (e.g. 6661-6669; the latter is inclusive). Example for a transparent HTTP proxy: context "OUTPUT" "nat" redirect to 8080 –p tcp --dport 80 Iceditch works this out to iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump REDIRECT –to-ports 8080 Should you want to log the packet, you could use redirect to 8080 log –p tcp --dport 80 Iceditch works this out to iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump LOG \ --log-prefix OUTPUT_REDIRECT_to_8080: iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump REDIRECT –-to-ports 8080 Because of how iptables handles the REDIRECT target, you can only use it in contexts where the table is “nat” and the chain is PREROUTING or OUTPUT. == Target keyword: reject == '''''reject [with <type>] [log [msg <message>]] <qualifiers>'''''<br> In essence, this does the same as the “drop” target keyword, only it jumps to REJECT instead of DROP. This means the packet is discarded (just as with DROP), but the sender is notified using ICMP (by default, your machine will send an ICMP-packet of type "icmp-port-unreachable"). Because of how iptables handles the REJECT target, you can only use it in contexts where the table is “filter”. Optionally, you can follow “reject” with the keyword “with”, and then use one of the following rejection types: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Type !style="background:#ffdead;"|Description |- | icmp-host-prohibited | will send an ICMP-message "host prohibited" |- | icmp-host-unreachable | will send an ICMP-message "host unreachable" |- | icmp-net-prohibited | will send an ICMP-message "net prohibited" |- | icmp-net-unreachable | will send an ICMP-message "net unreachable" |- | icmp-port-unreachable | DEFAULT; will send an ICMP-message "port unreachable" |- | icmp-proto-unreachable | DEFAULT; will send an ICMP-message "protocol unreachable" |- | tcp-reset | will send a TCP reset, a packet with the RST flag set (as a response to a TCP packet only) |- | host-prohib | synonymous to icmp-host-prohibited |- | host-unreach | synonymous to icmp-host-unreachable |- | net-prohib | synonymous to icmp-net-prohibited |- | net-unreach | synonymous to icmp-net-unreachable |- | port-unreach | synonymous to icmp-port-unreachable |- | proto-unreach | synonymous to icmp-proto-unreachable |- |} If you don’t specify “with <type>”, then netfilter will assume icmp-port-unreachable. Thus, should you want to reject a packet in context filter_INPUT (and log it) with reason net-prohib, you’d use reject with net-prohib log –p tcp –i eth0 --dport 22 Iceditch works this out to iptables –t filter –A INPUT –p tcp –i eth0 –-dport 22 –-jump LOG \ --log-prefix INPUT_REJECT_with_net-prohib: iptables –t filter –A INPUT –p tcp –i eth0 –-dport 22 \ –-jump REJECT –-reject-with net-prohib –p tcp –i eth0 –-dport 22 == Target keyword: snat== '''''snat [to <a1[-a2][:p1-p2]]> [to <a3[-a4][:p3-p4]]>] ] [log [msg <message>] ] <qualifiers>'''''<br> This keyword is only valid in the chain POSTROUTING, table nat. And ofcourse, source NATting does you little good if you haven't enabled forwarding (e.g. use this machine as a router for other machines on your network).<br> Calling snat with the right parameters will create a Source NATting rule for you, whereby a packet matching the qualifiers will be source NATted using the source IP address ''a1'' (or the range ''a1-a2''). Ofcourse, ''a1[-a2]'' should be valid IP address(es) of the firewalling machine.<br> Furthermore, if a port range ''p1-p2'' is specified, then you'll limit the range of ports that ''snat'' will use outbound (only valid for TCP or UDP packets).<br> Finally, it is possible to specify ''multiple'' IP address ranges and port ranges, using multiple ''to <a1[-a2][:p1-p2]]'' declarations in succession.<br> An example would be: context "POSTROUTING" "nat" snat to $inetIP -o $inetIF ! --src $inetIP If the variable ''$inetIP'' contains your public IP (e.g. 212.238.151.72), and ''$inetIF'' your interface connected to the Internet (e.g. ''eth0''), then this rule would expand to iptables -A POSTROUTING -t nat -o eth0 ! --src 212.238.151.72 -j SNAT --to-source 212.238.151.72 This would cause Iceditch to source NAT any outbound packet that is NOT sent by your firewall itself; in effect your server is now a nice fullblown NAT router for all machines on your private network. d6c676ed76c5c99bc8bff93cd66e7f0bc55f5e15 1605 1604 2008-08-07T14:39:45Z Saruman! 2 Target keyword: same wikitext text/x-wiki == Parameter: log == ''target '''log [(msg|message) <message>]''' <qualifiers>''<br> After most keywords, a "log" parameter can be added (see below). If the "log" parameter is followed by "msg" (or "message"), then the parameter following "msg" is read and used as log-prefix. The parameter is not allowed to have whitespace (that limitation is Iceditch-specific, not IPtables-related), and the maximum length of the log-prefix is determined by your version of netfilter/IPtables and your IPtables logging utility (syslogemu or ulog); this limit is usually some 29 characters. Note that Iceditch does not perform any sanity checks on the message. Thus a packet matching the rule will be logged with the default setting of the "log" target. If the "log" parameter is ''not'' followed by "msg", then the packet will be logged with a default log message, being "&lt;table&gt;_<chain>_<target>" and all the other default setting of the "log" target. Thus, should you want to log a packet with more control over the logging parameters, then you need an extra line, beginning with the ''target keyword'' "log", instead of just following the target keyword with parameter ''log''. For more information, see the target keyword "log" below. == Context keyword: context == '''''context <chain> &lt;table&gt;'''''<br> Every IPtables rule is written to a chain in a table; with Iceditch, you don't have to specify the chain and table in every line. Just precede the lines with the ''context'' statement. Example: context POSTROUTING nat Notes: the order of chain and table does not matter; ''context nat POSTROUTING'' works just as well. Furthermore, <chain> and &lt;table&gt; have been made case-insensitive; whatever you specify as chain will be translated to uppercase, whatever you specify as table will be translated to lowercase. This gives you the possibility to write the context as you like to read it, e.g. ''context Postrouting Nat''; after processing this, Iceditch will have two variables $CHAIN="POSTROUTING" and $TABLE="nat" that it will use in every following command. For example: context "Input" "fIlTeR" accept -p tcp --dport 22 will result in the following IPtables call: iptables -A INPUT -t filter -p tcp --dport 22 --jump ACCEPT If you do NOT specify a [[Iceditch IPtables language | valid combination]] of chain and table, the execution of Iceditch will halt with a fatal error. It is allowed (but not recommended) to call ''context'' multiple times for the same combination of chain and table; the order in which the rules are added to that chain in that table, is the same in which they appear in your rulefile, top to bottom. This is not recommended, because we feel it decreases readability, and thus maintainability, of the rules file. But hey, it's going to be ''your'' rulefile anyway... == Context keyword: create_chain == '''''create_chain <chain> [&lt;table&gt;]'''''<br> This command creates a new chain named <chain>, in the specified table &lt;table&gt;. If no table is specified, then the ''filter'' table is assumed. Just as with the ''context'' command, the <chain> name you specify will be translated to all uppercase.<br> The name for your new chain must be unique, although just like the built-in chains, you can specify the same name in different tables. If you create "fun-filter" in table ''filter'', and then create a "fun-filter" in table ''nat'', then you actually have two different chains. But remember: since Iceditch translates every chain name to uppercase, you can't create "Fun-filter" AND "fun-FILTER" in the same table - they're the same chain.<br> NOTE: after you've run ''create_chain'', you still have to switch context to create rules in the new chain! example:<br> create_chain fun-filter context fun-filter filter accept -p tcp --dport 22 This will result in iptables -N FUN-FILTER -t filter iptables -A FUN-FILTER -t filter -p tcp --dport 22 --jump ACCEPT == Target keyword: accept == '''''accept [log [msg <message>]] <qualifiers>'''''<br> If a network packet matches the qualifiers, then it will be accepted (passed) through the table/chain defined in the context where you put the accept rule. Example: <pre>context "INPUT" "filter" accept –p tcp --dport 22</pre> Iceditch works this out to iptables –t filter –A INPUT –p tcp –-dport 22 –-jump ACCEPT Should you want to log the packet, you’d use context "INPUT" "filter" accept log –p tcp --dport 22 Iceditch works this out to iptables –t filter –A INPUT –p tcp –-dport 22 \ –-jump LOG --log-prefix INPUT_accept iptables –t filter –A INPUT –p tcp –-dport 22 –-jump ACCEPT Note: the ACCEPT target is valid in any user-manipulable table/chain combination == Target keyword: classify == '''''classify <classval> [log [msg <message>]] <qualifiers>'''''<br> If a packet travelling through the mangle table in the POSTROUTING chain matches the qualifiers, then it will be classified with the <classval> specified. An example: classify 2:11 –p tcp --dport 22 The script works this out to iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump CLASSIFY --setclass 2:11 Should you want to also log the packet, you’d use classify 2:11 log –p tcp --dport 22 The script works this out to iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump LOG \ --log-prefix classified_2:11: iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump CLASSIFY \ --setclass 2:11 Should you not give a msg, then the log-prefix becomes POSTROUTING_CLASSIFY_set_<classval>. Because of how iptables handles the CLASSIFY target, you can only use it in contexts where the chain is “POSTROUTING” and the table is “mangle”. == Target keyword: dnat == '''''dnat [to] <a1[-a2][:p1[-p2]]> [log [msg <message>]] <qualifiers>'''''<br> In the above, a1 and a2 are used to specify a (range of) IP address(es); for TCP and UDP protocols, a destination port or port range can be provided. Note that the "to" in the command is optional, and serves only readability.<br> If a packet matches the qualifiers, then it will be destination-NATted to the provided IP address or address range. For example, if you want to DNAT port 81 on your external interface eth1 to an internal webserver on 10.0.0.1, you could use context "PREROUTING" "nat" dnat to 10.0.0.1:80 –p tcp –i eth1 –-dport 81 If you give a range of IP addresses, then the DNAT logic of IPtables will randomly pick an address and DNAT the packet there. However, note that a single stream will always use the same IP address from that range, and that each stream will randomly be given an IP address that it will always be destined for, within that stream.<br> Furthermore, note that the DNAT target is only available within the PREROUTING and OUTPUT chains in the nat table, and any of the chains called upon from any of those listed chains. Note that chains containing DNAT targets may not be used from any other chains, such as the POSTROUTING chain. However, the bad news is that Iceditch currently does not know how to check for the latter case, so the dnat keyword only works from contexts "PREROUTING" "nat" and "OUTPUT" "nat". == Target keyword: drop == '''''drop [log [msg <message>]] <qualifiers> '''''<br> In essence, this does the same as the “accept” target keyword, only it jumps to DROP instead of ACCEPT. Thus any packet matching the qualifiers gets discarded; it will not get sent on to its final destination (or next hop), it will not get processed by any other firewall rule, and the sender of the packet is unaware of your treatment of his packet. Should you want to also log the packet, you’d use context "FORWARD" "filter" drop log –p tcp -s 10.0.0.0/16 The script works this out to iptables –t filter –A FORWARD –p tcp -s 10.0.0.0/16 –-jump LOG \ --log-prefix FORWARD_DROP: iptables –t filter –A FORWARD –p tcp -s 10.0.0.0/16 –-jump DROP However, be advised that using DROP may leave dead sockets on either the sending or receiving host. If you do not wish that, you might be better of using REJECT. On the other hand, dropping packets is a nice way of appearing like a black hole, so it's the weapon of choice against port scanners and the likes.<br> The DROP target can be used in any chain in any table. == Target keyword: log == '''''log [(msg|message) <message>] [(lvl|level) <loglevel>] <qualifiers>'''''<br> Sometimes, the standard ''log'' parameter is just not enough. This can be the case when you want to log a packet to a log-level other than the default level, which for most systems is ''4'' (''warning''). Furthermore, maybe you want to log a certain type or class of packets, without performing an action on those packets just yet. For this reason, AND for flexibility and clarity, Iceditch has the dedicated target keyword ''log''.<br> Just as when you use the ''log'' parameter after another target, Iceditch will call the log target specified in the Iceditch [[Iceditch file structure | config file]]. Standard this is LOG, but optionally you could specify ULOG in the config file. ''<message>'' can be any string of 32 characters max (letters, numbers and underscores; no spaces); the ''<loglevel>'' can either be numeric or the corresponding keyword (e.g. ''crit''); Iceditch translates it to its numeric value anyway. Furthermore, the order in which <msg> and <lvl> appear is not important.<br> Depending on which log target you have specified, there are some options you can use with the Iceditch target keyword ''log''; it is currently deemed unnecessary to make specific Iceditch parameters for them, but as a reference we'll list the official IPtables options here, which you can put in the <qualifiers> list: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" ! colspan="2" style="background:#ffdead;"|LOG options | ! colspan="2" style="background:#ffdead;"|ULOG options |- !style="background:#ffdead;"|Option !style="background:#ffdead;"|Description | !style="background:#ffdead;"|Option !style="background:#ffdead;"|Description |- | --log-ip-options |Makes Netfilter include the IP options in the log entry | | --ulog-cprange <''size''> |log the first ''size'' bytes of each packet |- | --log-tcp-options |Makes Netfilter include the TCP options in the log entry | | --ulog-nlgroup <''nlgroup''> |Log to Netlink group number ''nlgroup'' (must match ''/etc/ulogd.conf'') |- | --log-tcp-sequence |Makes Netfilter include the TCP sequence number in the log entry | | --ulog-qthreshold <''value''> |Queue ''value'' packets before sending them to ''ulogd'' (default = 1, max = 50) |- |} <br> For completeness, we here reproduce the list of logging levels that ''log'' understands: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Level !style="background:#ffdead;"|Description |- |0 |''emerg'' or ''panic'' |- |1 |''alert'' |- |2 |''crit'' |- |3 |''err'' |- |4 |''warn'' (default) |- |5 |''notice'' |- |6 |''info'' |- |7 |''debug'' |- |} Now an example: context "INPUT" "filter" log lvl info msg SSH_incoming -p tcp --dport 22 -i $inetIF Iceditch works this out into iptables -A INPUT -t filter -p tcp --dport 22 -i $inetIF --jump ULOG --ulog-prefix "SSH_incoming" --log-level 6 == Target keyword: mark == '''''mark <markval> [log [msg <message>]] <qualifiers>'''''<br> If a packet matches the qualifiers, then it will be marked with the <markval> specified. An example from the context “PREROUTING” “mangle”: mark 2 –p tcp --dport 22 Iceditch works this out to iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump MARK --setmark 2 Should you want to also log the packet, you’d use mark 2 log –p tcp --dport 22 Iceditch works this out to iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump LOG \ --log-prefix PREROUTING_MARK_set_2: iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump MARK --setmark 2 Because of how iptables handles the MARK target, you can only use it in contexts where the table is “mangle”. == Target keyword: masquerade == '''''masquerade <iface> [to <p1[-p2]>] [log [msg <message>]] <qualifiers>''''' <iface> is the outward facing network interface that we should be masquerading.<br> The MASQUERADE target is used basically the same as the SNAT target, but it does not require any --to-source option. The reason for this is that the MASQUERADE target was made to work with connections which get dynamic IP addresses when connecting to the network in question, for example dial-up connections, or DHCP connections. This means that you should only use the MASQUERADE target with dynamically assigned IP connections, which we don't know the actual IP address of in advance. If you have a static IP connection, you should instead use the SNAT target.<br> When you masquerade a connection, it means that we set the IP address used on a specific network ''interface'', instead of getting it from the --to-source option. The necessary IP address is automatically grabbed from the information about the specific interface. Using the ''masquerade'' keyword also has the advantage that connections are forgotten when an interface goes down, which is extremely good if we, for example, kill a specific interface. If we would have used the SNAT target, we may have been left with a lot of old connection tracking data, which would be kept in connection tracking memory for days. forgetting about connections is, in general, the correct behavior when dealing with dial-up lines that are probably assigned a different IP every time they are brought up. In case we are assigned a different IP, the connection is lost anyways, and it is more or less idiotic to keep the entry around.<br> It is still possible to use the MASQUERADE target instead of SNAT even though you do have a static IP; however, it is not favorable since it will add extra overhead, and there may be inconsistencies in the future which will thwart your existing scripts and render them "unusable".<br> Note that the MASQUERADE target is only valid within the POSTROUTING chain in the nat table, just as the SNAT target. The MASQUERADE target takes one option specified below, which is optional. == Target keyword: redirect == '''''redirect [to <to-ports>] [log [msg <message>]] <qualifiers>'''''<br> If a packet matches the qualifiers, then it will be redirected to the local machine, by setting the destination IP to a fitting IP address of the local machine (i.e. 127.0.0.1, or the first-bound IP address of the interface over which it came in. Additionally, by specifying “to <to-ports>” you can have the destination ports redirected to a port or portrange. <to-ports> can either be a port number (e.g. 8080) or a port range (e.g. 6661-6669; the latter is inclusive). Example for a transparent HTTP proxy: context "OUTPUT" "nat" redirect to 8080 –p tcp --dport 80 Iceditch works this out to iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump REDIRECT –to-ports 8080 Should you want to log the packet, you could use redirect to 8080 log –p tcp --dport 80 Iceditch works this out to iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump LOG \ --log-prefix OUTPUT_REDIRECT_to_8080: iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump REDIRECT –-to-ports 8080 Because of how iptables handles the REDIRECT target, you can only use it in contexts where the table is “nat” and the chain is PREROUTING or OUTPUT. == Target keyword: reject == '''''reject [with <type>] [log [msg <message>]] <qualifiers>'''''<br> In essence, this does the same as the “drop” target keyword, only it jumps to REJECT instead of DROP. This means the packet is discarded (just as with DROP), but the sender is notified using ICMP (by default, your machine will send an ICMP-packet of type "icmp-port-unreachable"). Because of how iptables handles the REJECT target, you can only use it in contexts where the table is “filter”. Optionally, you can follow “reject” with the keyword “with”, and then use one of the following rejection types: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Type !style="background:#ffdead;"|Description |- | icmp-host-prohibited | will send an ICMP-message "host prohibited" |- | icmp-host-unreachable | will send an ICMP-message "host unreachable" |- | icmp-net-prohibited | will send an ICMP-message "net prohibited" |- | icmp-net-unreachable | will send an ICMP-message "net unreachable" |- | icmp-port-unreachable | DEFAULT; will send an ICMP-message "port unreachable" |- | icmp-proto-unreachable | DEFAULT; will send an ICMP-message "protocol unreachable" |- | tcp-reset | will send a TCP reset, a packet with the RST flag set (as a response to a TCP packet only) |- | host-prohib | synonymous to icmp-host-prohibited |- | host-unreach | synonymous to icmp-host-unreachable |- | net-prohib | synonymous to icmp-net-prohibited |- | net-unreach | synonymous to icmp-net-unreachable |- | port-unreach | synonymous to icmp-port-unreachable |- | proto-unreach | synonymous to icmp-proto-unreachable |- |} If you don’t specify “with <type>”, then netfilter will assume icmp-port-unreachable. Thus, should you want to reject a packet in context filter_INPUT (and log it) with reason net-prohib, you’d use reject with net-prohib log –p tcp –i eth0 --dport 22 Iceditch works this out to iptables –t filter –A INPUT –p tcp –i eth0 –-dport 22 –-jump LOG \ --log-prefix INPUT_REJECT_with_net-prohib: iptables –t filter –A INPUT –p tcp –i eth0 –-dport 22 \ –-jump REJECT –-reject-with net-prohib –p tcp –i eth0 –-dport 22 == Target keyword: same== '''''same [to <a1[-a2]> [to <a3[-a4]>] ] [nodest] [log [msg <message>] ] <qualifiers>'''''<br> ''same'' only works in the nat table, in the POSTROUTING chain. It is very closely related to ''snat'' (see below), because it does virtually the same thing. Basically, the ''same'' target will try to always use the same outgoing IP address for all connections initiated by a single host on your network. For example, say you have one "internal" /24 network (192.168.1.0) and 3 "external" IP addresses (10.5.6.11-13) on your firewall/router machine. Now, if internal machine 192.168.1.20 went out through the .11 address the first time, then the firewall will try to keep that machine always going out through that same IP address. So basically ''same'' might be a better fit than ''snat'' if you have multiple external IP addresses.<br> However, there is also functionality lacking in ''same'' that ''snat'' has, namely the specification of (TCP and UDP) ports or port ranges to use for the NATting operation. See ''snat'' for its port possibilities.<br> Furthermore, ''same'' has an extra option that ''snat'' does not have: under normal action, the ''same'' target is calculating the followup connections based on both destination and source IP addresses. Using the ''nodest'' option (which corresponds with --nodst in the actual IPtables command), it uses only the source IP address to find out which outgoing IP the NAT function should use for the specific connection. Without this argument, it uses a combination of the destination and source IP address. == Target keyword: snat== '''''snat [to <a1[-a2][:p1-p2]]> [to <a3[-a4][:p3-p4]]>] ] [log [msg <message>] ] <qualifiers>'''''<br> This keyword is only valid in the chain POSTROUTING, table nat. And ofcourse, source NATting does you little good if you haven't enabled forwarding (e.g. use this machine as a router for other machines on your network).<br> Calling snat with the right parameters will create a Source NATting rule for you, whereby a packet matching the qualifiers will be source NATted using the source IP address ''a1'' (or the range ''a1-a2''). Ofcourse, ''a1[-a2]'' should be valid IP address(es) of the firewalling machine.<br> Furthermore, if a port range ''p1-p2'' is specified, then you'll limit the range of ports that ''snat'' will use outbound (only valid for TCP or UDP packets).<br> Finally, it is possible to specify ''multiple'' IP address ranges and port ranges, using multiple ''to <a1[-a2][:p1-p2]]'' declarations in succession.<br> An example would be: context "POSTROUTING" "nat" snat to $inetIP -o $inetIF ! --src $inetIP If the variable ''$inetIP'' contains your public IP (e.g. 212.238.151.72), and ''$inetIF'' your interface connected to the Internet (e.g. ''eth0''), then this rule would expand to iptables -A POSTROUTING -t nat -o eth0 ! --src 212.238.151.72 -j SNAT --to-source 212.238.151.72 This would cause Iceditch to source NAT any outbound packet that is NOT sent by your firewall itself; in effect your server is now a nice fullblown NAT router for all machines on your private network. e58a37c155efdc3d6496182f88157244c06a055d 1606 1605 2008-08-07T14:57:34Z Saruman! 2 Target keyword: route wikitext text/x-wiki == Parameter: log == ''target '''log [(msg|message) <message>]''' <qualifiers>''<br> After most keywords, a "log" parameter can be added (see below). If the "log" parameter is followed by "msg" (or "message"), then the parameter following "msg" is read and used as log-prefix. The parameter is not allowed to have whitespace (that limitation is Iceditch-specific, not IPtables-related), and the maximum length of the log-prefix is determined by your version of netfilter/IPtables and your IPtables logging utility (syslogemu or ulog); this limit is usually some 29 characters. Note that Iceditch does not perform any sanity checks on the message. Thus a packet matching the rule will be logged with the default setting of the "log" target. If the "log" parameter is ''not'' followed by "msg", then the packet will be logged with a default log message, being "&lt;table&gt;_<chain>_<target>" and all the other default setting of the "log" target. Thus, should you want to log a packet with more control over the logging parameters, then you need an extra line, beginning with the ''target keyword'' "log", instead of just following the target keyword with parameter ''log''. For more information, see the target keyword "log" below. == Context keyword: context == '''''context <chain> &lt;table&gt;'''''<br> Every IPtables rule is written to a chain in a table; with Iceditch, you don't have to specify the chain and table in every line. Just precede the lines with the ''context'' statement. Example: context POSTROUTING nat Notes: the order of chain and table does not matter; ''context nat POSTROUTING'' works just as well. Furthermore, <chain> and &lt;table&gt; have been made case-insensitive; whatever you specify as chain will be translated to uppercase, whatever you specify as table will be translated to lowercase. This gives you the possibility to write the context as you like to read it, e.g. ''context Postrouting Nat''; after processing this, Iceditch will have two variables $CHAIN="POSTROUTING" and $TABLE="nat" that it will use in every following command. For example: context "Input" "fIlTeR" accept -p tcp --dport 22 will result in the following IPtables call: iptables -A INPUT -t filter -p tcp --dport 22 --jump ACCEPT If you do NOT specify a [[Iceditch IPtables language | valid combination]] of chain and table, the execution of Iceditch will halt with a fatal error. It is allowed (but not recommended) to call ''context'' multiple times for the same combination of chain and table; the order in which the rules are added to that chain in that table, is the same in which they appear in your rulefile, top to bottom. This is not recommended, because we feel it decreases readability, and thus maintainability, of the rules file. But hey, it's going to be ''your'' rulefile anyway... == Context keyword: create_chain == '''''create_chain <chain> [&lt;table&gt;]'''''<br> This command creates a new chain named <chain>, in the specified table &lt;table&gt;. If no table is specified, then the ''filter'' table is assumed. Just as with the ''context'' command, the <chain> name you specify will be translated to all uppercase.<br> The name for your new chain must be unique, although just like the built-in chains, you can specify the same name in different tables. If you create "fun-filter" in table ''filter'', and then create a "fun-filter" in table ''nat'', then you actually have two different chains. But remember: since Iceditch translates every chain name to uppercase, you can't create "Fun-filter" AND "fun-FILTER" in the same table - they're the same chain.<br> NOTE: after you've run ''create_chain'', you still have to switch context to create rules in the new chain! example:<br> create_chain fun-filter context fun-filter filter accept -p tcp --dport 22 This will result in iptables -N FUN-FILTER -t filter iptables -A FUN-FILTER -t filter -p tcp --dport 22 --jump ACCEPT == Target keyword: accept == '''''accept [log [msg <message>]] <qualifiers>'''''<br> If a network packet matches the qualifiers, then it will be accepted (passed) through the table/chain defined in the context where you put the accept rule. Example: <pre>context "INPUT" "filter" accept –p tcp --dport 22</pre> Iceditch works this out to iptables –t filter –A INPUT –p tcp –-dport 22 –-jump ACCEPT Should you want to log the packet, you’d use context "INPUT" "filter" accept log –p tcp --dport 22 Iceditch works this out to iptables –t filter –A INPUT –p tcp –-dport 22 \ –-jump LOG --log-prefix INPUT_accept iptables –t filter –A INPUT –p tcp –-dport 22 –-jump ACCEPT Note: the ACCEPT target is valid in any user-manipulable table/chain combination == Target keyword: classify == '''''classify <classval> [log [msg <message>]] <qualifiers>'''''<br> If a packet travelling through the mangle table in the POSTROUTING chain matches the qualifiers, then it will be classified with the <classval> specified. An example: classify 2:11 –p tcp --dport 22 The script works this out to iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump CLASSIFY --setclass 2:11 Should you want to also log the packet, you’d use classify 2:11 log –p tcp --dport 22 The script works this out to iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump LOG \ --log-prefix classified_2:11: iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump CLASSIFY \ --setclass 2:11 Should you not give a msg, then the log-prefix becomes POSTROUTING_CLASSIFY_set_<classval>. Because of how iptables handles the CLASSIFY target, you can only use it in contexts where the chain is “POSTROUTING” and the table is “mangle”. == Target keyword: dnat == '''''dnat [to] <a1[-a2][:p1[-p2]]> [log [msg <message>]] <qualifiers>'''''<br> In the above, a1 and a2 are used to specify a (range of) IP address(es); for TCP and UDP protocols, a destination port or port range can be provided. Note that the "to" in the command is optional, and serves only readability.<br> If a packet matches the qualifiers, then it will be destination-NATted to the provided IP address or address range. For example, if you want to DNAT port 81 on your external interface eth1 to an internal webserver on 10.0.0.1, you could use context "PREROUTING" "nat" dnat to 10.0.0.1:80 –p tcp –i eth1 –-dport 81 If you give a range of IP addresses, then the DNAT logic of IPtables will randomly pick an address and DNAT the packet there. However, note that a single stream will always use the same IP address from that range, and that each stream will randomly be given an IP address that it will always be destined for, within that stream.<br> Furthermore, note that the DNAT target is only available within the PREROUTING and OUTPUT chains in the nat table, and any of the chains called upon from any of those listed chains. Note that chains containing DNAT targets may not be used from any other chains, such as the POSTROUTING chain. However, the bad news is that Iceditch currently does not know how to check for the latter case, so the dnat keyword only works from contexts "PREROUTING" "nat" and "OUTPUT" "nat". == Target keyword: drop == '''''drop [log [msg <message>]] <qualifiers> '''''<br> In essence, this does the same as the “accept” target keyword, only it jumps to DROP instead of ACCEPT. Thus any packet matching the qualifiers gets discarded; it will not get sent on to its final destination (or next hop), it will not get processed by any other firewall rule, and the sender of the packet is unaware of your treatment of his packet. Should you want to also log the packet, you’d use context "FORWARD" "filter" drop log –p tcp -s 10.0.0.0/16 The script works this out to iptables –t filter –A FORWARD –p tcp -s 10.0.0.0/16 –-jump LOG \ --log-prefix FORWARD_DROP: iptables –t filter –A FORWARD –p tcp -s 10.0.0.0/16 –-jump DROP However, be advised that using DROP may leave dead sockets on either the sending or receiving host. If you do not wish that, you might be better of using REJECT. On the other hand, dropping packets is a nice way of appearing like a black hole, so it's the weapon of choice against port scanners and the likes.<br> The DROP target can be used in any chain in any table. == Target keyword: log == '''''log [(msg|message) <message>] [(lvl|level) <loglevel>] <qualifiers>'''''<br> Sometimes, the standard ''log'' parameter is just not enough. This can be the case when you want to log a packet to a log-level other than the default level, which for most systems is ''4'' (''warning''). Furthermore, maybe you want to log a certain type or class of packets, without performing an action on those packets just yet. For this reason, AND for flexibility and clarity, Iceditch has the dedicated target keyword ''log''.<br> Just as when you use the ''log'' parameter after another target, Iceditch will call the log target specified in the Iceditch [[Iceditch file structure | config file]]. Standard this is LOG, but optionally you could specify ULOG in the config file. ''<message>'' can be any string of 32 characters max (letters, numbers and underscores; no spaces); the ''<loglevel>'' can either be numeric or the corresponding keyword (e.g. ''crit''); Iceditch translates it to its numeric value anyway. Furthermore, the order in which <msg> and <lvl> appear is not important.<br> Depending on which log target you have specified, there are some options you can use with the Iceditch target keyword ''log''; it is currently deemed unnecessary to make specific Iceditch parameters for them, but as a reference we'll list the official IPtables options here, which you can put in the <qualifiers> list: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" ! colspan="2" style="background:#ffdead;"|LOG options | ! colspan="2" style="background:#ffdead;"|ULOG options |- !style="background:#ffdead;"|Option !style="background:#ffdead;"|Description | !style="background:#ffdead;"|Option !style="background:#ffdead;"|Description |- | --log-ip-options |Makes Netfilter include the IP options in the log entry | | --ulog-cprange <''size''> |log the first ''size'' bytes of each packet |- | --log-tcp-options |Makes Netfilter include the TCP options in the log entry | | --ulog-nlgroup <''nlgroup''> |Log to Netlink group number ''nlgroup'' (must match ''/etc/ulogd.conf'') |- | --log-tcp-sequence |Makes Netfilter include the TCP sequence number in the log entry | | --ulog-qthreshold <''value''> |Queue ''value'' packets before sending them to ''ulogd'' (default = 1, max = 50) |- |} <br> For completeness, we here reproduce the list of logging levels that ''log'' understands: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Level !style="background:#ffdead;"|Description |- |0 |''emerg'' or ''panic'' |- |1 |''alert'' |- |2 |''crit'' |- |3 |''err'' |- |4 |''warn'' (default) |- |5 |''notice'' |- |6 |''info'' |- |7 |''debug'' |- |} Now an example: context "INPUT" "filter" log lvl info msg SSH_incoming -p tcp --dport 22 -i $inetIF Iceditch works this out into iptables -A INPUT -t filter -p tcp --dport 22 -i $inetIF --jump ULOG --ulog-prefix "SSH_incoming" --log-level 6 == Target keyword: mark == '''''mark <markval> [log [msg <message>]] <qualifiers>'''''<br> If a packet matches the qualifiers, then it will be marked with the <markval> specified. An example from the context “PREROUTING” “mangle”: mark 2 –p tcp --dport 22 Iceditch works this out to iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump MARK --setmark 2 Should you want to also log the packet, you’d use mark 2 log –p tcp --dport 22 Iceditch works this out to iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump LOG \ --log-prefix PREROUTING_MARK_set_2: iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump MARK --setmark 2 Because of how iptables handles the MARK target, you can only use it in contexts where the table is “mangle”. == Target keyword: masquerade == '''''masquerade <iface> [to <p1[-p2]>] [log [msg <message>]] <qualifiers>''''' <iface> is the outward facing network interface that we should be masquerading.<br> The MASQUERADE target is used basically the same as the SNAT target, but it does not require any --to-source option. The reason for this is that the MASQUERADE target was made to work with connections which get dynamic IP addresses when connecting to the network in question, for example dial-up connections, or DHCP connections. This means that you should only use the MASQUERADE target with dynamically assigned IP connections, which we don't know the actual IP address of in advance. If you have a static IP connection, you should instead use the SNAT target.<br> When you masquerade a connection, it means that we set the IP address used on a specific network ''interface'', instead of getting it from the --to-source option. The necessary IP address is automatically grabbed from the information about the specific interface. Using the ''masquerade'' keyword also has the advantage that connections are forgotten when an interface goes down, which is extremely good if we, for example, kill a specific interface. If we would have used the SNAT target, we may have been left with a lot of old connection tracking data, which would be kept in connection tracking memory for days. forgetting about connections is, in general, the correct behavior when dealing with dial-up lines that are probably assigned a different IP every time they are brought up. In case we are assigned a different IP, the connection is lost anyways, and it is more or less idiotic to keep the entry around.<br> It is still possible to use the MASQUERADE target instead of SNAT even though you do have a static IP; however, it is not favorable since it will add extra overhead, and there may be inconsistencies in the future which will thwart your existing scripts and render them "unusable".<br> Note that the MASQUERADE target is only valid within the POSTROUTING chain in the nat table, just as the SNAT target. The MASQUERADE target takes one option specified below, which is optional. == Target keyword: redirect == '''''redirect [to <to-ports>] [log [msg <message>]] <qualifiers>'''''<br> If a packet matches the qualifiers, then it will be redirected to the local machine, by setting the destination IP to a fitting IP address of the local machine (i.e. 127.0.0.1, or the first-bound IP address of the interface over which it came in. Additionally, by specifying “to <to-ports>” you can have the destination ports redirected to a port or portrange. <to-ports> can either be a port number (e.g. 8080) or a port range (e.g. 6661-6669; the latter is inclusive). Example for a transparent HTTP proxy: context "OUTPUT" "nat" redirect to 8080 –p tcp --dport 80 Iceditch works this out to iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump REDIRECT –to-ports 8080 Should you want to log the packet, you could use redirect to 8080 log –p tcp --dport 80 Iceditch works this out to iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump LOG \ --log-prefix OUTPUT_REDIRECT_to_8080: iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump REDIRECT –-to-ports 8080 Because of how iptables handles the REDIRECT target, you can only use it in contexts where the table is “nat” and the chain is PREROUTING or OUTPUT. == Target keyword: reject == '''''reject [with <type>] [log [msg <message>]] <qualifiers>'''''<br> In essence, this does the same as the “drop” target keyword, only it jumps to REJECT instead of DROP. This means the packet is discarded (just as with DROP), but the sender is notified using ICMP (by default, your machine will send an ICMP-packet of type "icmp-port-unreachable"). Because of how iptables handles the REJECT target, you can only use it in contexts where the table is “filter”. Optionally, you can follow “reject” with the keyword “with”, and then use one of the following rejection types: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Type !style="background:#ffdead;"|Description |- | icmp-host-prohibited | will send an ICMP-message "host prohibited" |- | icmp-host-unreachable | will send an ICMP-message "host unreachable" |- | icmp-net-prohibited | will send an ICMP-message "net prohibited" |- | icmp-net-unreachable | will send an ICMP-message "net unreachable" |- | icmp-port-unreachable | DEFAULT; will send an ICMP-message "port unreachable" |- | icmp-proto-unreachable | DEFAULT; will send an ICMP-message "protocol unreachable" |- | tcp-reset | will send a TCP reset, a packet with the RST flag set (as a response to a TCP packet only) |- | host-prohib | synonymous to icmp-host-prohibited |- | host-unreach | synonymous to icmp-host-unreachable |- | net-prohib | synonymous to icmp-net-prohibited |- | net-unreach | synonymous to icmp-net-unreachable |- | port-unreach | synonymous to icmp-port-unreachable |- | proto-unreach | synonymous to icmp-proto-unreachable |- |} If you don’t specify “with <type>”, then netfilter will assume icmp-port-unreachable. Thus, should you want to reject a packet in context filter_INPUT (and log it) with reason net-prohib, you’d use reject with net-prohib log –p tcp –i eth0 --dport 22 Iceditch works this out to iptables –t filter –A INPUT –p tcp –i eth0 –-dport 22 –-jump LOG \ --log-prefix INPUT_REJECT_with_net-prohib: iptables –t filter –A INPUT –p tcp –i eth0 –-dport 22 \ –-jump REJECT –-reject-with net-prohib –p tcp –i eth0 –-dport 22 ==Target keyword: route== '''''route {<iface>|<ifaceindex>} [log [msg <message>]] <qualifiers>'''''<br> The ''route'' target lets you route a received packet through an interface or towards a host, even if the regular destination of the packet is the router itself. The ROUTE target is also able to change the incoming interface of a packet. Packets are directly put on the wire and do not traverse any other table.<br> ''route'' takes one mandatory option, which may be either the interface name over which to route the packet that matches the qualifiers, or the index number of that interface (based on the order in /proc/net/dev). Iceditch is pretty lazy in how to interpret that option: if it's all numerals, Iceditch treats it as the interface index number, if it contains any other character, it is considered the interface name (e.g. ''eth0''). == Target keyword: same== '''''same [to <a1[-a2]> [to <a3[-a4]>] ] [nodest] [log [msg <message>] ] <qualifiers>'''''<br> ''same'' only works in the nat table, in the POSTROUTING chain. It is very closely related to ''snat'' (see below), because it does virtually the same thing. Basically, the ''same'' target will try to always use the same outgoing IP address for all connections initiated by a single host on your network. For example, say you have one "internal" /24 network (192.168.1.0) and 3 "external" IP addresses (10.5.6.11-13) on your firewall/router machine. Now, if internal machine 192.168.1.20 went out through the .11 address the first time, then the firewall will try to keep that machine always going out through that same IP address. So basically ''same'' might be a better fit than ''snat'' if you have multiple external IP addresses.<br> However, there is also functionality lacking in ''same'' that ''snat'' has, namely the specification of (TCP and UDP) ports or port ranges to use for the NATting operation. See ''snat'' for its port possibilities.<br> Furthermore, ''same'' has an extra option that ''snat'' does not have: under normal action, the ''same'' target is calculating the followup connections based on both destination and source IP addresses. Using the ''nodest'' option (which corresponds with --nodst in the actual IPtables command), it uses only the source IP address to find out which outgoing IP the NAT function should use for the specific connection. Without this argument, it uses a combination of the destination and source IP address. == Target keyword: snat== '''''snat [to <a1[-a2][:p1-p2]]> [to <a3[-a4][:p3-p4]]>] ] [log [msg <message>] ] <qualifiers>'''''<br> This keyword is only valid in the chain POSTROUTING, table nat. And ofcourse, source NATting does you little good if you haven't enabled forwarding (e.g. use this machine as a router for other machines on your network).<br> Calling snat with the right parameters will create a Source NATting rule for you, whereby a packet matching the qualifiers will be source NATted using the source IP address ''a1'' (or the range ''a1-a2''). Ofcourse, ''a1[-a2]'' should be valid IP address(es) of the firewalling machine.<br> Furthermore, if a port range ''p1-p2'' is specified, then you'll limit the range of ports that ''snat'' will use outbound (only valid for TCP or UDP packets).<br> Finally, it is possible to specify ''multiple'' IP address ranges and port ranges, using multiple ''to <a1[-a2][:p1-p2]]'' declarations in succession.<br> An example would be: context "POSTROUTING" "nat" snat to $inetIP -o $inetIF ! --src $inetIP If the variable ''$inetIP'' contains your public IP (e.g. 212.238.151.72), and ''$inetIF'' your interface connected to the Internet (e.g. ''eth0''), then this rule would expand to iptables -A POSTROUTING -t nat -o eth0 ! --src 212.238.151.72 -j SNAT --to-source 212.238.151.72 This would cause Iceditch to source NAT any outbound packet that is NOT sent by your firewall itself; in effect your server is now a nice fullblown NAT router for all machines on your private network. 93d37fee544853eb23080ed380b4c32b97efdb2c 1609 1606 2008-08-10T14:47:48Z Saruman! 2 changed <qualifiers> to <matches> & added tochain wikitext text/x-wiki == Parameter: log == ''target '''log [(msg|message) <message>]''' <matches>''<br> After most keywords, a "log" parameter can be added (see below). If the "log" parameter is followed by "msg" (or "message"), then the parameter following "msg" is read and used as log-prefix. The parameter is not allowed to have whitespace (that limitation is Iceditch-specific, not IPtables-related), and the maximum length of the log-prefix is determined by your version of netfilter/IPtables and your IPtables logging utility (syslogemu or ulog); this limit is usually some 29 characters. Note that Iceditch does not perform any sanity checks on the message. Thus a packet matching the <matches> part of the rule will be logged with the default setting of the "log" target. If the "log" parameter is ''not'' followed by "msg", then the packet will be logged with a default log message, being "&lt;table&gt;_<chain>_<target>" and all the other default setting of the "log" target. Thus, should you want to log a packet with more control over the logging parameters, then you need an extra line, beginning with the ''target keyword'' "log", instead of just following the target keyword with parameter ''log''. For more information, see the target keyword "log" below. == Context keyword: context == '''''context <chain> &lt;table&gt;'''''<br> Every IPtables rule is written to a chain in a table; with Iceditch, you don't have to specify the chain and table in every line. Just precede the lines with the ''context'' statement. Example: context POSTROUTING nat Notes: the order of chain and table does not matter; ''context nat POSTROUTING'' works just as well. Furthermore, <chain> and &lt;table&gt; have been made case-insensitive; whatever you specify as chain will be translated to uppercase, whatever you specify as table will be translated to lowercase. This gives you the possibility to write the context as you like to read it, e.g. ''context Postrouting Nat''; after processing this, Iceditch will have two variables $CHAIN="POSTROUTING" and $TABLE="nat" that it will use in every following command. For example: context "Input" "fIlTeR" accept -p tcp --dport 22 will result in the following IPtables call: iptables -A INPUT -t filter -p tcp --dport 22 --jump ACCEPT If you do NOT specify a [[Iceditch IPtables language | valid combination]] of chain and table, the execution of Iceditch will halt with a fatal error. It is allowed (but not recommended) to call ''context'' multiple times for the same combination of chain and table; the order in which the rules are added to that chain in that table, is the same in which they appear in your rulefile, top to bottom. This is not recommended, because we feel it decreases readability, and thus maintainability, of the rules file. But hey, it's going to be ''your'' rulefile anyway...<br> Note: you cannot create custom chains by the names of mangle, nat or filter, since Iceditch will always interpret these names as those of tables. == Context keyword: create_chain == '''''create_chain <chain> [&lt;table&gt;]'''''<br> This command creates a new chain named <chain>, in the specified table &lt;table&gt;. If no table is specified, then the ''filter'' table is assumed. Just as with the ''context'' command, the <chain> name you specify will be translated to all uppercase.<br> The name for your new chain must be unique, although just like the built-in chains, you can specify the same name in different tables. If you create "fun-filter" in table ''filter'', and then create a "fun-filter" in table ''nat'', then you actually have two different chains. But remember: since Iceditch translates every chain name to uppercase, you can't create "Fun-filter" AND "fun-FILTER" in the same table - they're the same chain.<br> NOTE: after you've run ''create_chain'', you still have to switch context to create rules in the new chain! example:<br> create_chain fun-filter context fun-filter filter accept -p tcp --dport 22 This will result in iptables -N FUN-FILTER -t filter iptables -A FUN-FILTER -t filter -p tcp --dport 22 --jump ACCEPT == Target keyword: accept == '''''accept [log [msg <message>]] <matches>'''''<br> If a network packet fits the <matches>, then it will be accepted (passed) through the table/chain defined in the context where you put the accept rule. Example: context Input Filter accept –p tcp --dport 22 Iceditch works this out to iptables –t filter –A INPUT –p tcp –-dport 22 –-jump ACCEPT Should you want to log the packet, you’d use context Input Filter accept log –p tcp --dport 22 Iceditch works this out to iptables –t filter –A INPUT –p tcp –-dport 22 \ –-jump LOG --log-prefix accept_INPUT_filter iptables –t filter –A INPUT –p tcp –-dport 22 –-jump ACCEPT Note: the ACCEPT target is valid in any user-manipulable table/chain combination == Target keyword: classify == '''''classify <classval> [log [msg <message>]] <matches>'''''<br> If a packet travelling through the mangle table in the POSTROUTING chain matches the <matches>, then it will be classified with the <classval> specified. An example: classify 2:11 –p tcp --dport 22 The script works this out to iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump CLASSIFY --setclass 2:11 Should you want to also log the packet, you’d use classify 2:11 log msg classified_2:11 –p tcp --dport 22 The script works this out to iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump LOG \ --log-prefix classified_2:11: iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump CLASSIFY \ --setclass 2:11 Should you not give a msg, then the log-prefix becomes classify_POSTROUTING_mangle. Because of how iptables handles the CLASSIFY target, you can only use it in contexts where the chain is "POSTROUTING" and the table is "mangle". == Target keyword: dnat == '''''dnat [to] <a1[-a2][:p1[-p2]]> [log [msg <message>]] <matches>'''''<br> In the above, a1 and a2 are used to specify a (range of) IP address(es); for TCP and UDP protocols, a destination port or port range can be provided. Note that the "to" in the command is optional, and serves only readability.<br> If a packet matches the qualifiers, then it will be destination-NATted to the provided IP address or address range. For example, if you want to DNAT port 81 on your external interface eth1 to an internal webserver on 10.0.0.1, you could use context "PREROUTING" "nat" dnat to 10.0.0.1:80 –p tcp –i eth1 –-dport 81 If you give a range of IP addresses, then the DNAT logic of IPtables will randomly pick an address and DNAT the packet there. However, note that a single stream will always use the same IP address from that range, and that each stream will randomly be given an IP address that it will always be destined for, within that stream.<br> Furthermore, note that the DNAT target is only available within the PREROUTING and OUTPUT chains in the nat table, and any of the chains called upon from any of those listed chains. Note that chains containing DNAT targets may not be used from any other chains, such as the POSTROUTING chain. However, the bad news is that Iceditch currently does not know how to check for the latter case, so the dnat keyword only works from contexts "PREROUTING" "nat" and "OUTPUT" "nat". == Target keyword: drop == '''''drop [log [msg <message>]] <matches> '''''<br> In essence, this does the same as the "accept" target keyword, only it jumps to DROP instead of ACCEPT. Thus any packet matching the <matches> gets discarded; it will not get sent on to its final destination (or next hop), it will not get processed by any other firewall rule, and the sender of the packet is unaware of your treatment of his packet. Should you want to also log the packet, you’d use context "FORWARD" "filter" drop log –p tcp -s 10.0.0.0/16 The script works this out to iptables –t filter –A FORWARD –p tcp -s 10.0.0.0/16 –-jump LOG \ --log-prefix drop_FORWARD_filter: iptables –t filter –A FORWARD –p tcp -s 10.0.0.0/16 –-jump DROP However, be advised that using DROP may leave dead sockets on either the sending or receiving host. If you do not wish that, you might be better of using REJECT. On the other hand, dropping packets is a nice way of appearing like a black hole, so it's the weapon of choice against port scanners and the likes.<br> The DROP target can be used in any chain in any table. == Target keyword: ipv4optsstrip == '''''ipv4optsstrip [log [msg <message>]] <matches>'''''<br> This target takes any packet that fits the <matches>, and then strips off all IPv4 options from its header. It can only be used in the ''mangle'' table. For example, the following rule strips the IPv4 options from any packet incoming on ''eth0'': context PREROUTING mangle ipv4optsstrip -i eth0 == Target keyword: tochain == '''''tochain <customchain> [log [msg <message>]] <matches>'''''<br> If you've created a custom chain within a certain table, then you can jump to this custom chain using ''tochain'', as long as the ''tochain'' invocation appears in a context with the same table. For example: create_chain FTPtraffic filter (...) context INPUT filter (...) tochain FTPtraffic -p tcp --dport 20 In this example, any TCP packet that appears in table filter, chain INPUT and is directed at port 20, is sent on through to the previously created chain FTPTRAFFIC (keep in mind that Iceditch will always translate any chain name to all uppercase). Rule matching and packet processing will continue in that chain, until an ACCEPT or DROP is encountered, or a RETURN, or all rules in the custom chain have been exhausted. After that, the implicit return policy on your custom chain will return the packet to whence it came (context INPUT filter, the line below the ''tochain'' invocation). == Target keyword: log == '''''log [(msg|message) <message>] [(lvl|level) <loglevel>] <matches>'''''<br> Sometimes, the standard ''log'' parameter is just not enough. This can be the case when you want to log a packet to a log-level other than the default level, which for most systems is ''4'' (''warning''). Furthermore, maybe you want to log a certain type or class of packets, without performing an action on those packets just yet. For this reason, AND for flexibility and clarity, Iceditch has the dedicated target keyword ''log''.<br> Just as when you use the ''log'' parameter after another target, Iceditch will call the log target specified in the Iceditch [[Iceditch file structure | config file]]. Standard this is LOG, but optionally you could specify ULOG in the config file. ''<message>'' can be any string of 32 characters max (letters, numbers and underscores; no spaces); the ''<loglevel>'' can either be numeric or the corresponding keyword (e.g. ''crit''); Iceditch translates it to its numeric value anyway. Furthermore, the order in which <msg> and <lvl> appear is not important.<br> Depending on which log target you have specified, there are some options you can use with the Iceditch target keyword ''log''; it is currently deemed unnecessary to make specific Iceditch parameters for them, but as a reference we'll list the official IPtables options here, which you can put in with the <matches> list: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" ! colspan="2" style="background:#ffdead;"|LOG options | ! colspan="2" style="background:#ffdead;"|ULOG options |- !style="background:#ffdead;"|Option !style="background:#ffdead;"|Description | !style="background:#ffdead;"|Option !style="background:#ffdead;"|Description |- | --log-ip-options |Makes Netfilter include the IP options in the log entry | | --ulog-cprange <''size''> |log the first ''size'' bytes of each packet |- | --log-tcp-options |Makes Netfilter include the TCP options in the log entry | | --ulog-nlgroup <''nlgroup''> |Log to Netlink group number ''nlgroup'' (must match ''/etc/ulogd.conf'') |- | --log-tcp-sequence |Makes Netfilter include the TCP sequence number in the log entry | | --ulog-qthreshold <''value''> |Queue ''value'' packets before sending them to ''ulogd'' (default = 1, max = 50) |- |} <br> For completeness, we here reproduce the list of logging levels that ''log'' understands: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Level !style="background:#ffdead;"|Description |- |0 |''emerg'' or ''panic'' |- |1 |''alert'' |- |2 |''crit'' |- |3 |''err'' |- |4 |''warn'' (default) |- |5 |''notice'' |- |6 |''info'' |- |7 |''debug'' |- |} Now an example: context "INPUT" "filter" log lvl info msg SSH_incoming -p tcp --dport 22 -i $inetIF Iceditch works this out into iptables -A INPUT -t filter -p tcp --dport 22 -i $inetIF --jump ULOG --ulog-prefix "SSH_incoming" --log-level 6 == Target keyword: mark == '''''mark <markval> [log [msg <message>]] <matches>'''''<br> If a packet matches the <matches>, then it will be marked with the <markval> specified. An example from the context PREROUTING mangle: mark 2 –p tcp --dport 22 Iceditch works this out to iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump MARK --setmark 2 Should you want to also log the packet, you’d use mark 2 log –p tcp --dport 22 Iceditch works this out to iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump LOG \ --log-prefix mark_PREROUTING_mangle: iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump MARK --setmark 2 Because of how iptables handles the MARK target, you can only use it in contexts where the table is ''mangle''. == Target keyword: masquerade == '''''masquerade <iface> [to <p1[-p2]>] [log [msg <message>]] <matches>'''''<br> <iface> is the (outward facing) network interface that we want to masquerade on.<br> The MASQUERADE target is used basically the same as the SNAT target, but it does not require any ''--to-source'' option. The reason for this is that the MASQUERADE target was made to work with connections which get dynamic IP addresses when connecting to the network in question, for example dial-up connections, or DHCP connections. This means that you should only use the MASQUERADE target with dynamically assigned IP connections, which we don't know the actual IP address of in advance. If you have a static IP connection, you should instead use the SNAT target.<br> When you masquerade a connection, it means that we set the IP address used on a specific network ''interface'', instead of getting it from the ''--to-source option''. The necessary IP address is automatically grabbed from the information about the specific interface. Using the ''masquerade'' keyword also has the advantage that connections are forgotten when an interface goes down, which is extremely good if we, for example, kill a specific interface. If we would have used the SNAT target, we may have been left with a lot of old connection tracking data, which would be kept in connection tracking memory for days. forgetting about connections is, in general, the correct behavior when dealing with dial-up lines that are probably assigned a different IP every time they are brought up. In case we are assigned a different IP, the connection is lost anyways, and it is more or less idiotic to keep the entry around.<br> It is still possible to use the MASQUERADE target instead of SNAT even though you do have a static IP; however, it is not favorable since it will add extra overhead, and there may be inconsistencies in the future which will thwart your existing scripts and render them "unusable".<br> Note that the MASQUERADE target is only valid within the POSTROUTING chain in the nat table, just as the SNAT target. == Target keyword: redirect == '''''redirect [to <to-ports>] [log [msg <message>]] <matches>'''''<br> If a packet matches the <matches>, then it will be redirected to the local machine, by setting the destination IP to a fitting IP address of the local machine (i.e. 127.0.0.1, or the first-bound IP address of the interface over which it came in. Additionally, by specifying “to <to-ports>” you can have the destination ports redirected to a port or portrange. <to-ports> can either be a port number (e.g. 8080) or a port range (e.g. 6661-6669; the latter is inclusive). Example for a transparent HTTP proxy: context "OUTPUT" "nat" redirect to 8080 –p tcp --dport 80 Iceditch works this out to iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump REDIRECT –to-ports 8080 Should you want to log the packet, you could use redirect to 8080 log –p tcp --dport 80 Iceditch works this out to iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump LOG \ --log-prefix OUTPUT_REDIRECT_to_8080: iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump REDIRECT –-to-ports 8080 Because of how iptables handles the REDIRECT target, you can only use it in contexts where the table is "nat" and the chain is PREROUTING or OUTPUT. == Target keyword: reject == '''''reject [with <type>] [log [msg <message>]] <matches>'''''<br> In essence, this does the same as the "drop" target keyword, only it jumps to REJECT instead of DROP. This means the packet is discarded (just as with DROP), but the sender is notified using ICMP (by default, your machine will send an ICMP-packet of type "icmp-port-unreachable"). Because of how iptables handles the REJECT target, you can only use it in contexts where the table is "filter". Optionally, you can follow "reject" with the keyword "with", and then use one of the following rejection types: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Type !style="background:#ffdead;"|Description |- | icmp-host-prohibited | will send an ICMP-message "host prohibited" |- | icmp-host-unreachable | will send an ICMP-message "host unreachable" |- | icmp-net-prohibited | will send an ICMP-message "net prohibited" |- | icmp-net-unreachable | will send an ICMP-message "net unreachable" |- | icmp-port-unreachable | DEFAULT; will send an ICMP-message "port unreachable" |- | icmp-proto-unreachable | DEFAULT; will send an ICMP-message "protocol unreachable" |- | tcp-reset | will send a TCP reset, a packet with the RST flag set (as a response to a TCP packet only) |- | host-prohib | synonymous to icmp-host-prohibited |- | host-unreach | synonymous to icmp-host-unreachable |- | net-prohib | synonymous to icmp-net-prohibited |- | net-unreach | synonymous to icmp-net-unreachable |- | port-unreach | synonymous to icmp-port-unreachable |- | proto-unreach | synonymous to icmp-proto-unreachable |- |} If you don’t specify "with <type>", then netfilter will assume icmp-port-unreachable. Thus, should you want to reject a packet in context filter INPUT (and log it) with reason net-prohib, you’d use reject with net-prohib log –p tcp –i eth0 --dport 22 Iceditch works this out to iptables –t filter –A INPUT –p tcp –i eth0 –-dport 22 –-jump LOG \ --log-prefix INPUT_REJECT_with_net-prohib: iptables –t filter –A INPUT –p tcp –i eth0 –-dport 22 \ –-jump REJECT –-reject-with net-prohib –p tcp –i eth0 –-dport 22 ==Target keyword: route== '''''route {<iface>|<ifaceindex>} [log [msg <message>]] <matches>'''''<br> The ''route'' target lets you route a received packet through an interface or towards a host, even if the regular destination of the packet is the router itself. The ROUTE target is also able to change the incoming interface of a packet. Packets are directly put on the wire and do not traverse any other table.<br> ''route'' takes one mandatory option, which may be either the interface name over which to route the packet that matches the <matches>, or the index number of that interface (based on the order in /proc/net/dev). Iceditch is pretty lazy in how to interpret that option: if it's all numerals, Iceditch treats it as the interface index number, if it contains any other character, it is considered the interface name (e.g. ''eth0''); and no sanity check is performed on the specified <iface|ifaceindex>. == Target keyword: same== '''''same [to <a1[-a2]> [to <a3[-a4]>] ] [nodest] [log [msg <message>] ] <matches>'''''<br> ''same'' only works in the nat table, in the POSTROUTING chain. It is very closely related to ''snat'' (see below), because it does virtually the same thing. Basically, the ''same'' target will try to always use the same outgoing IP address for all connections initiated by a single host on your network. For example, say you have one "internal" /24 network (192.168.1.0) and 3 "external" IP addresses (10.5.6.11-13) on your firewall/router machine. Now, if internal machine 192.168.1.20 went out through the .11 address the first time, then the firewall will try to keep that machine always going out through that same IP address. So basically ''same'' might be a better fit than ''snat'' if you have multiple external IP addresses.<br> However, there is also functionality lacking in ''same'' that ''snat'' has, namely the specification of (TCP and UDP) ports or port ranges to use for the NATting operation. See ''snat'' for its port possibilities.<br> Furthermore, ''same'' has an extra option that ''snat'' does not have: under normal action, the ''same'' target is calculating the followup connections based on both destination and source IP addresses. Using the ''nodest'' option (which corresponds with --nodst in the actual IPtables command), it uses only the source IP address to find out which outgoing IP the NAT function should use for the specific connection. Without this argument, it uses a combination of the destination and source IP address. == Target keyword: snat== '''''snat [to <a1[-a2][:p1-p2]]> [to <a3[-a4][:p3-p4]]>] ] [log [msg <message>] ] <matches>'''''<br> This keyword is only valid in the chain POSTROUTING, table nat. And ofcourse, source NATting does you little good if you haven't enabled forwarding (e.g. use this machine as a router for other machines on your network).<br> Calling snat with the right parameters will create a Source NATting rule for you, whereby a packet matching the <matches> will be source NATted using the source IP address ''a1'' (or the range ''a1-a2''). Ofcourse, ''a1[-a2]'' should be valid IP address(es) of the firewalling machine.<br> Furthermore, if a port range ''p1-p2'' is specified, then you'll limit the range of ports that ''snat'' will use outbound (only valid for TCP or UDP packets).<br> Finally, it is possible to specify ''multiple'' IP address ranges and port ranges, using multiple ''to <a1[-a2][:p1-p2]]'' declarations in succession.<br> An example would be: context "POSTROUTING" "nat" snat to $inetIP -o $inetIF ! --src $inetIP If the variable ''$inetIP'' contains your public IP (e.g. 212.238.151.72), and ''$inetIF'' your interface connected to the Internet (e.g. ''eth0''), then this rule would expand to iptables -A POSTROUTING -t nat -o eth0 ! --src 212.238.151.72 -j SNAT --to-source 212.238.151.72 This would cause Iceditch to source NAT any outbound packet that is NOT sent by your firewall itself; in effect your server is now a nice fullblown NAT router for all machines on your private network. e824ef70394613ad351e4bee85bdefbf74275079 1614 1609 2008-08-11T21:49:35Z Saruman! 2 /* Parameter: log */ added link wikitext text/x-wiki == Parameter: log == ''target '''log [(msg|message) <message>]''' <matches>''<br> After most keywords, a "log" parameter can be added (see below). If the "log" parameter is followed by "msg" (or "message"), then the parameter following "msg" is read and used as log-prefix. The parameter is not allowed to have whitespace (that limitation is Iceditch-specific, not IPtables-related), and the maximum length of the log-prefix is determined by your version of netfilter/IPtables and your choice of IPtables logging utility (syslogemu or ulog); this limit is usually some 29 characters. Note that Iceditch does not perform any sanity checks on the message. Thus a packet matching the <matches> part of the rule will be logged with the default setting of the "log" target. If the "log" parameter is ''not'' followed by "msg", then the packet will be logged with a default log message, being "&lt;table&gt;_<chain>_<target>" and all the other default setting of the "log" target. Thus, should you want to log a packet with more control over the logging parameters, then you need an extra line, beginning with the ''target keyword'' "log", instead of just following the target keyword with parameter ''log''. For more information, see the [[Iceditch_Command_Reference#Target_keyword:_log | target keyword "log"]] below. == Context keyword: context == '''''context <chain> &lt;table&gt;'''''<br> Every IPtables rule is written to a chain in a table; with Iceditch, you don't have to specify the chain and table in every line. Just precede the lines with the ''context'' statement. Example: context POSTROUTING nat Notes: the order of chain and table does not matter; ''context nat POSTROUTING'' works just as well. Furthermore, <chain> and &lt;table&gt; have been made case-insensitive; whatever you specify as chain will be translated to uppercase, whatever you specify as table will be translated to lowercase. This gives you the possibility to write the context as you like to read it, e.g. ''context Postrouting Nat''; after processing this, Iceditch will have two variables $CHAIN="POSTROUTING" and $TABLE="nat" that it will use in every following command. For example: context "Input" "fIlTeR" accept -p tcp --dport 22 will result in the following IPtables call: iptables -A INPUT -t filter -p tcp --dport 22 --jump ACCEPT If you do NOT specify a [[Iceditch IPtables language | valid combination]] of chain and table, the execution of Iceditch will halt with a fatal error. It is allowed (but not recommended) to call ''context'' multiple times for the same combination of chain and table; the order in which the rules are added to that chain in that table, is the same in which they appear in your rulefile, top to bottom. This is not recommended, because we feel it decreases readability, and thus maintainability, of the rules file. But hey, it's going to be ''your'' rulefile anyway...<br> Note: you cannot create custom chains by the names of mangle, nat or filter, since Iceditch will always interpret these names as those of tables. == Context keyword: create_chain == '''''create_chain <chain> [&lt;table&gt;]'''''<br> This command creates a new chain named <chain>, in the specified table &lt;table&gt;. If no table is specified, then the ''filter'' table is assumed. Just as with the ''context'' command, the <chain> name you specify will be translated to all uppercase.<br> The name for your new chain must be unique, although just like the built-in chains, you can specify the same name in different tables. If you create "fun-filter" in table ''filter'', and then create a "fun-filter" in table ''nat'', then you actually have two different chains. But remember: since Iceditch translates every chain name to uppercase, you can't create "Fun-filter" AND "fun-FILTER" in the same table - they're the same chain.<br> NOTE: after you've run ''create_chain'', you still have to switch context to create rules in the new chain! example:<br> create_chain fun-filter context fun-filter filter accept -p tcp --dport 22 This will result in iptables -N FUN-FILTER -t filter iptables -A FUN-FILTER -t filter -p tcp --dport 22 --jump ACCEPT == Target keyword: accept == '''''accept [log [msg <message>]] <matches>'''''<br> If a network packet fits the <matches>, then it will be accepted (passed) through the table/chain defined in the context where you put the accept rule. Example: context Input Filter accept –p tcp --dport 22 Iceditch works this out to iptables –t filter –A INPUT –p tcp –-dport 22 –-jump ACCEPT Should you want to log the packet, you’d use context Input Filter accept log –p tcp --dport 22 Iceditch works this out to iptables –t filter –A INPUT –p tcp –-dport 22 \ –-jump LOG --log-prefix accept_INPUT_filter iptables –t filter –A INPUT –p tcp –-dport 22 –-jump ACCEPT Note: the ACCEPT target is valid in any user-manipulable table/chain combination == Target keyword: classify == '''''classify <classval> [log [msg <message>]] <matches>'''''<br> If a packet travelling through the mangle table in the POSTROUTING chain matches the <matches>, then it will be classified with the <classval> specified. An example: classify 2:11 –p tcp --dport 22 The script works this out to iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump CLASSIFY --setclass 2:11 Should you want to also log the packet, you’d use classify 2:11 log msg classified_2:11 –p tcp --dport 22 The script works this out to iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump LOG \ --log-prefix classified_2:11: iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump CLASSIFY \ --setclass 2:11 Should you not give a msg, then the log-prefix becomes classify_POSTROUTING_mangle. Because of how iptables handles the CLASSIFY target, you can only use it in contexts where the chain is "POSTROUTING" and the table is "mangle". == Target keyword: dnat == '''''dnat [to] <a1[-a2][:p1[-p2]]> [log [msg <message>]] <matches>'''''<br> In the above, a1 and a2 are used to specify a (range of) IP address(es); for TCP and UDP protocols, a destination port or port range can be provided. Note that the "to" in the command is optional, and serves only readability.<br> If a packet matches the qualifiers, then it will be destination-NATted to the provided IP address or address range. For example, if you want to DNAT port 81 on your external interface eth1 to an internal webserver on 10.0.0.1, you could use context "PREROUTING" "nat" dnat to 10.0.0.1:80 –p tcp –i eth1 –-dport 81 If you give a range of IP addresses, then the DNAT logic of IPtables will randomly pick an address and DNAT the packet there. However, note that a single stream will always use the same IP address from that range, and that each stream will randomly be given an IP address that it will always be destined for, within that stream.<br> Furthermore, note that the DNAT target is only available within the PREROUTING and OUTPUT chains in the nat table, and any of the chains called upon from any of those listed chains. Note that chains containing DNAT targets may not be used from any other chains, such as the POSTROUTING chain. However, the bad news is that Iceditch currently does not know how to check for the latter case, so the dnat keyword only works from contexts "PREROUTING" "nat" and "OUTPUT" "nat". == Target keyword: drop == '''''drop [log [msg <message>]] <matches> '''''<br> In essence, this does the same as the "accept" target keyword, only it jumps to DROP instead of ACCEPT. Thus any packet matching the <matches> gets discarded; it will not get sent on to its final destination (or next hop), it will not get processed by any other firewall rule, and the sender of the packet is unaware of your treatment of his packet. Should you want to also log the packet, you’d use context "FORWARD" "filter" drop log –p tcp -s 10.0.0.0/16 The script works this out to iptables –t filter –A FORWARD –p tcp -s 10.0.0.0/16 –-jump LOG \ --log-prefix drop_FORWARD_filter: iptables –t filter –A FORWARD –p tcp -s 10.0.0.0/16 –-jump DROP However, be advised that using DROP may leave dead sockets on either the sending or receiving host. If you do not wish that, you might be better of using REJECT. On the other hand, dropping packets is a nice way of appearing like a black hole, so it's the weapon of choice against port scanners and the likes.<br> The DROP target can be used in any chain in any table. == Target keyword: ipv4optsstrip == '''''ipv4optsstrip [log [msg <message>]] <matches>'''''<br> This target takes any packet that fits the <matches>, and then strips off all IPv4 options from its header. It can only be used in the ''mangle'' table. For example, the following rule strips the IPv4 options from any packet incoming on ''eth0'': context PREROUTING mangle ipv4optsstrip -i eth0 == Target keyword: tochain == '''''tochain <customchain> [log [msg <message>]] <matches>'''''<br> If you've created a custom chain within a certain table, then you can jump to this custom chain using ''tochain'', as long as the ''tochain'' invocation appears in a context with the same table. For example: create_chain FTPtraffic filter (...) context INPUT filter (...) tochain FTPtraffic -p tcp --dport 20 In this example, any TCP packet that appears in table filter, chain INPUT and is directed at port 20, is sent on through to the previously created chain FTPTRAFFIC (keep in mind that Iceditch will always translate any chain name to all uppercase). Rule matching and packet processing will continue in that chain, until an ACCEPT or DROP is encountered, or a RETURN, or all rules in the custom chain have been exhausted. After that, the implicit return policy on your custom chain will return the packet to whence it came (context INPUT filter, the line below the ''tochain'' invocation). == Target keyword: log == '''''log [(msg|message) <message>] [(lvl|level) <loglevel>] <matches>'''''<br> Sometimes, the standard ''log'' parameter is just not enough. This can be the case when you want to log a packet to a log-level other than the default level, which for most systems is ''4'' (''warning''). Furthermore, maybe you want to log a certain type or class of packets, without performing an action on those packets just yet. For this reason, AND for flexibility and clarity, Iceditch has the dedicated target keyword ''log''.<br> Just as when you use the ''log'' parameter after another target, Iceditch will call the log target specified in the Iceditch [[Iceditch file structure | config file]]. Standard this is LOG, but optionally you could specify ULOG in the config file. ''<message>'' can be any string of 32 characters max (letters, numbers and underscores; no spaces); the ''<loglevel>'' can either be numeric or the corresponding keyword (e.g. ''crit''); Iceditch translates it to its numeric value anyway. Furthermore, the order in which <msg> and <lvl> appear is not important.<br> Depending on which log target you have specified, there are some options you can use with the Iceditch target keyword ''log''; it is currently deemed unnecessary to make specific Iceditch parameters for them, but as a reference we'll list the official IPtables options here, which you can put in with the <matches> list: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" ! colspan="2" style="background:#ffdead;"|LOG options | ! colspan="2" style="background:#ffdead;"|ULOG options |- !style="background:#ffdead;"|Option !style="background:#ffdead;"|Description | !style="background:#ffdead;"|Option !style="background:#ffdead;"|Description |- | --log-ip-options |Makes Netfilter include the IP options in the log entry | | --ulog-cprange <''size''> |log the first ''size'' bytes of each packet |- | --log-tcp-options |Makes Netfilter include the TCP options in the log entry | | --ulog-nlgroup <''nlgroup''> |Log to Netlink group number ''nlgroup'' (must match ''/etc/ulogd.conf'') |- | --log-tcp-sequence |Makes Netfilter include the TCP sequence number in the log entry | | --ulog-qthreshold <''value''> |Queue ''value'' packets before sending them to ''ulogd'' (default = 1, max = 50) |- |} <br> For completeness, we here reproduce the list of logging levels that ''log'' understands: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Level !style="background:#ffdead;"|Description |- |0 |''emerg'' or ''panic'' |- |1 |''alert'' |- |2 |''crit'' |- |3 |''err'' |- |4 |''warn'' (default) |- |5 |''notice'' |- |6 |''info'' |- |7 |''debug'' |- |} Now an example: context "INPUT" "filter" log lvl info msg SSH_incoming -p tcp --dport 22 -i $inetIF Iceditch works this out into iptables -A INPUT -t filter -p tcp --dport 22 -i $inetIF --jump ULOG --ulog-prefix "SSH_incoming" --log-level 6 == Target keyword: mark == '''''mark <markval> [log [msg <message>]] <matches>'''''<br> If a packet matches the <matches>, then it will be marked with the <markval> specified. An example from the context PREROUTING mangle: mark 2 –p tcp --dport 22 Iceditch works this out to iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump MARK --setmark 2 Should you want to also log the packet, you’d use mark 2 log –p tcp --dport 22 Iceditch works this out to iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump LOG \ --log-prefix mark_PREROUTING_mangle: iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump MARK --setmark 2 Because of how iptables handles the MARK target, you can only use it in contexts where the table is ''mangle''. == Target keyword: masquerade == '''''masquerade <iface> [to <p1[-p2]>] [log [msg <message>]] <matches>'''''<br> <iface> is the (outward facing) network interface that we want to masquerade on.<br> The MASQUERADE target is used basically the same as the SNAT target, but it does not require any ''--to-source'' option. The reason for this is that the MASQUERADE target was made to work with connections which get dynamic IP addresses when connecting to the network in question, for example dial-up connections, or DHCP connections. This means that you should only use the MASQUERADE target with dynamically assigned IP connections, which we don't know the actual IP address of in advance. If you have a static IP connection, you should instead use the SNAT target.<br> When you masquerade a connection, it means that we set the IP address used on a specific network ''interface'', instead of getting it from the ''--to-source option''. The necessary IP address is automatically grabbed from the information about the specific interface. Using the ''masquerade'' keyword also has the advantage that connections are forgotten when an interface goes down, which is extremely good if we, for example, kill a specific interface. If we would have used the SNAT target, we may have been left with a lot of old connection tracking data, which would be kept in connection tracking memory for days. forgetting about connections is, in general, the correct behavior when dealing with dial-up lines that are probably assigned a different IP every time they are brought up. In case we are assigned a different IP, the connection is lost anyways, and it is more or less idiotic to keep the entry around.<br> It is still possible to use the MASQUERADE target instead of SNAT even though you do have a static IP; however, it is not favorable since it will add extra overhead, and there may be inconsistencies in the future which will thwart your existing scripts and render them "unusable".<br> Note that the MASQUERADE target is only valid within the POSTROUTING chain in the nat table, just as the SNAT target. == Target keyword: redirect == '''''redirect [to <to-ports>] [log [msg <message>]] <matches>'''''<br> If a packet matches the <matches>, then it will be redirected to the local machine, by setting the destination IP to a fitting IP address of the local machine (i.e. 127.0.0.1, or the first-bound IP address of the interface over which it came in. Additionally, by specifying “to <to-ports>” you can have the destination ports redirected to a port or portrange. <to-ports> can either be a port number (e.g. 8080) or a port range (e.g. 6661-6669; the latter is inclusive). Example for a transparent HTTP proxy: context "OUTPUT" "nat" redirect to 8080 –p tcp --dport 80 Iceditch works this out to iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump REDIRECT –to-ports 8080 Should you want to log the packet, you could use redirect to 8080 log –p tcp --dport 80 Iceditch works this out to iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump LOG \ --log-prefix OUTPUT_REDIRECT_to_8080: iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump REDIRECT –-to-ports 8080 Because of how iptables handles the REDIRECT target, you can only use it in contexts where the table is "nat" and the chain is PREROUTING or OUTPUT. == Target keyword: reject == '''''reject [with <type>] [log [msg <message>]] <matches>'''''<br> In essence, this does the same as the "drop" target keyword, only it jumps to REJECT instead of DROP. This means the packet is discarded (just as with DROP), but the sender is notified using ICMP (by default, your machine will send an ICMP-packet of type "icmp-port-unreachable"). Because of how iptables handles the REJECT target, you can only use it in contexts where the table is "filter". Optionally, you can follow "reject" with the keyword "with", and then use one of the following rejection types: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Type !style="background:#ffdead;"|Description |- | icmp-host-prohibited | will send an ICMP-message "host prohibited" |- | icmp-host-unreachable | will send an ICMP-message "host unreachable" |- | icmp-net-prohibited | will send an ICMP-message "net prohibited" |- | icmp-net-unreachable | will send an ICMP-message "net unreachable" |- | icmp-port-unreachable | DEFAULT; will send an ICMP-message "port unreachable" |- | icmp-proto-unreachable | DEFAULT; will send an ICMP-message "protocol unreachable" |- | tcp-reset | will send a TCP reset, a packet with the RST flag set (as a response to a TCP packet only) |- | host-prohib | synonymous to icmp-host-prohibited |- | host-unreach | synonymous to icmp-host-unreachable |- | net-prohib | synonymous to icmp-net-prohibited |- | net-unreach | synonymous to icmp-net-unreachable |- | port-unreach | synonymous to icmp-port-unreachable |- | proto-unreach | synonymous to icmp-proto-unreachable |- |} If you don’t specify "with <type>", then netfilter will assume icmp-port-unreachable. Thus, should you want to reject a packet in context filter INPUT (and log it) with reason net-prohib, you’d use reject with net-prohib log –p tcp –i eth0 --dport 22 Iceditch works this out to iptables –t filter –A INPUT –p tcp –i eth0 –-dport 22 –-jump LOG \ --log-prefix INPUT_REJECT_with_net-prohib: iptables –t filter –A INPUT –p tcp –i eth0 –-dport 22 \ –-jump REJECT –-reject-with net-prohib –p tcp –i eth0 –-dport 22 ==Target keyword: route== '''''route {<iface>|<ifaceindex>} [log [msg <message>]] <matches>'''''<br> The ''route'' target lets you route a received packet through an interface or towards a host, even if the regular destination of the packet is the router itself. The ROUTE target is also able to change the incoming interface of a packet. Packets are directly put on the wire and do not traverse any other table.<br> ''route'' takes one mandatory option, which may be either the interface name over which to route the packet that matches the <matches>, or the index number of that interface (based on the order in /proc/net/dev). Iceditch is pretty lazy in how to interpret that option: if it's all numerals, Iceditch treats it as the interface index number, if it contains any other character, it is considered the interface name (e.g. ''eth0''); and no sanity check is performed on the specified <iface|ifaceindex>. == Target keyword: same== '''''same [to <a1[-a2]> [to <a3[-a4]>] ] [nodest] [log [msg <message>] ] <matches>'''''<br> ''same'' only works in the nat table, in the POSTROUTING chain. It is very closely related to ''snat'' (see below), because it does virtually the same thing. Basically, the ''same'' target will try to always use the same outgoing IP address for all connections initiated by a single host on your network. For example, say you have one "internal" /24 network (192.168.1.0) and 3 "external" IP addresses (10.5.6.11-13) on your firewall/router machine. Now, if internal machine 192.168.1.20 went out through the .11 address the first time, then the firewall will try to keep that machine always going out through that same IP address. So basically ''same'' might be a better fit than ''snat'' if you have multiple external IP addresses.<br> However, there is also functionality lacking in ''same'' that ''snat'' has, namely the specification of (TCP and UDP) ports or port ranges to use for the NATting operation. See ''snat'' for its port possibilities.<br> Furthermore, ''same'' has an extra option that ''snat'' does not have: under normal action, the ''same'' target is calculating the followup connections based on both destination and source IP addresses. Using the ''nodest'' option (which corresponds with --nodst in the actual IPtables command), it uses only the source IP address to find out which outgoing IP the NAT function should use for the specific connection. Without this argument, it uses a combination of the destination and source IP address. == Target keyword: snat== '''''snat [to <a1[-a2][:p1-p2]]> [to <a3[-a4][:p3-p4]]>] ] [log [msg <message>] ] <matches>'''''<br> This keyword is only valid in the chain POSTROUTING, table nat. And ofcourse, source NATting does you little good if you haven't enabled forwarding (e.g. use this machine as a router for other machines on your network).<br> Calling snat with the right parameters will create a Source NATting rule for you, whereby a packet matching the <matches> will be source NATted using the source IP address ''a1'' (or the range ''a1-a2''). Ofcourse, ''a1[-a2]'' should be valid IP address(es) of the firewalling machine.<br> Furthermore, if a port range ''p1-p2'' is specified, then you'll limit the range of ports that ''snat'' will use outbound (only valid for TCP or UDP packets).<br> Finally, it is possible to specify ''multiple'' IP address ranges and port ranges, using multiple ''to <a1[-a2][:p1-p2]]'' declarations in succession.<br> An example would be: context "POSTROUTING" "nat" snat to $inetIP -o $inetIF ! --src $inetIP If the variable ''$inetIP'' contains your public IP (e.g. 212.238.151.72), and ''$inetIF'' your interface connected to the Internet (e.g. ''eth0''), then this rule would expand to iptables -A POSTROUTING -t nat -o eth0 ! --src 212.238.151.72 -j SNAT --to-source 212.238.151.72 This would cause Iceditch to source NAT any outbound packet that is NOT sent by your firewall itself; in effect your server is now a nice fullblown NAT router for all machines on your private network. 37340f00986b67365c17c36c9b82aea9f2db27f3 1615 1614 2008-08-11T22:35:16Z Saruman! 2 /* Target keyword: log */ split between LOG and ULOG wikitext text/x-wiki == Parameter: log == ''target '''log [(msg|message) <message>]''' <matches>''<br> After most keywords, a "log" parameter can be added (see below). If the "log" parameter is followed by "msg" (or "message"), then the parameter following "msg" is read and used as log-prefix. The parameter is not allowed to have whitespace (that limitation is Iceditch-specific, not IPtables-related), and the maximum length of the log-prefix is determined by your version of netfilter/IPtables and your choice of IPtables logging utility (syslogemu or ulog); this limit is usually some 29 characters. Note that Iceditch does not perform any sanity checks on the message. Thus a packet matching the <matches> part of the rule will be logged with the default setting of the "log" target. If the "log" parameter is ''not'' followed by "msg", then the packet will be logged with a default log message, being "&lt;table&gt;_<chain>_<target>" and all the other default setting of the "log" target. Thus, should you want to log a packet with more control over the logging parameters, then you need an extra line, beginning with the ''target keyword'' "log", instead of just following the target keyword with parameter ''log''. For more information, see the [[Iceditch_Command_Reference#Target_keyword:_log | target keyword "log"]] below. == Context keyword: context == '''''context <chain> &lt;table&gt;'''''<br> Every IPtables rule is written to a chain in a table; with Iceditch, you don't have to specify the chain and table in every line. Just precede the lines with the ''context'' statement. Example: context POSTROUTING nat Notes: the order of chain and table does not matter; ''context nat POSTROUTING'' works just as well. Furthermore, <chain> and &lt;table&gt; have been made case-insensitive; whatever you specify as chain will be translated to uppercase, whatever you specify as table will be translated to lowercase. This gives you the possibility to write the context as you like to read it, e.g. ''context Postrouting Nat''; after processing this, Iceditch will have two variables $CHAIN="POSTROUTING" and $TABLE="nat" that it will use in every following command. For example: context "Input" "fIlTeR" accept -p tcp --dport 22 will result in the following IPtables call: iptables -A INPUT -t filter -p tcp --dport 22 --jump ACCEPT If you do NOT specify a [[Iceditch IPtables language | valid combination]] of chain and table, the execution of Iceditch will halt with a fatal error. It is allowed (but not recommended) to call ''context'' multiple times for the same combination of chain and table; the order in which the rules are added to that chain in that table, is the same in which they appear in your rulefile, top to bottom. This is not recommended, because we feel it decreases readability, and thus maintainability, of the rules file. But hey, it's going to be ''your'' rulefile anyway...<br> Note: you cannot create custom chains by the names of mangle, nat or filter, since Iceditch will always interpret these names as those of tables. == Context keyword: create_chain == '''''create_chain <chain> [&lt;table&gt;]'''''<br> This command creates a new chain named <chain>, in the specified table &lt;table&gt;. If no table is specified, then the ''filter'' table is assumed. Just as with the ''context'' command, the <chain> name you specify will be translated to all uppercase.<br> The name for your new chain must be unique, although just like the built-in chains, you can specify the same name in different tables. If you create "fun-filter" in table ''filter'', and then create a "fun-filter" in table ''nat'', then you actually have two different chains. But remember: since Iceditch translates every chain name to uppercase, you can't create "Fun-filter" AND "fun-FILTER" in the same table - they're the same chain.<br> NOTE: after you've run ''create_chain'', you still have to switch context to create rules in the new chain! example:<br> create_chain fun-filter context fun-filter filter accept -p tcp --dport 22 This will result in iptables -N FUN-FILTER -t filter iptables -A FUN-FILTER -t filter -p tcp --dport 22 --jump ACCEPT == Target keyword: accept == '''''accept [log [msg <message>]] <matches>'''''<br> If a network packet fits the <matches>, then it will be accepted (passed) through the table/chain defined in the context where you put the accept rule. Example: context Input Filter accept –p tcp --dport 22 Iceditch works this out to iptables –t filter –A INPUT –p tcp –-dport 22 –-jump ACCEPT Should you want to log the packet, you’d use context Input Filter accept log –p tcp --dport 22 Iceditch works this out to iptables –t filter –A INPUT –p tcp –-dport 22 \ –-jump LOG --log-prefix accept_INPUT_filter iptables –t filter –A INPUT –p tcp –-dport 22 –-jump ACCEPT Note: the ACCEPT target is valid in any user-manipulable table/chain combination == Target keyword: classify == '''''classify <classval> [log [msg <message>]] <matches>'''''<br> If a packet travelling through the mangle table in the POSTROUTING chain matches the <matches>, then it will be classified with the <classval> specified. An example: classify 2:11 –p tcp --dport 22 The script works this out to iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump CLASSIFY --setclass 2:11 Should you want to also log the packet, you’d use classify 2:11 log msg classified_2:11 –p tcp --dport 22 The script works this out to iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump LOG \ --log-prefix classified_2:11: iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump CLASSIFY \ --setclass 2:11 Should you not give a msg, then the log-prefix becomes classify_POSTROUTING_mangle. Because of how iptables handles the CLASSIFY target, you can only use it in contexts where the chain is "POSTROUTING" and the table is "mangle". == Target keyword: dnat == '''''dnat [to] <a1[-a2][:p1[-p2]]> [log [msg <message>]] <matches>'''''<br> In the above, a1 and a2 are used to specify a (range of) IP address(es); for TCP and UDP protocols, a destination port or port range can be provided. Note that the "to" in the command is optional, and serves only readability.<br> If a packet matches the qualifiers, then it will be destination-NATted to the provided IP address or address range. For example, if you want to DNAT port 81 on your external interface eth1 to an internal webserver on 10.0.0.1, you could use context "PREROUTING" "nat" dnat to 10.0.0.1:80 –p tcp –i eth1 –-dport 81 If you give a range of IP addresses, then the DNAT logic of IPtables will randomly pick an address and DNAT the packet there. However, note that a single stream will always use the same IP address from that range, and that each stream will randomly be given an IP address that it will always be destined for, within that stream.<br> Furthermore, note that the DNAT target is only available within the PREROUTING and OUTPUT chains in the nat table, and any of the chains called upon from any of those listed chains. Note that chains containing DNAT targets may not be used from any other chains, such as the POSTROUTING chain. However, the bad news is that Iceditch currently does not know how to check for the latter case, so the dnat keyword only works from contexts "PREROUTING" "nat" and "OUTPUT" "nat". == Target keyword: drop == '''''drop [log [msg <message>]] <matches> '''''<br> In essence, this does the same as the "accept" target keyword, only it jumps to DROP instead of ACCEPT. Thus any packet matching the <matches> gets discarded; it will not get sent on to its final destination (or next hop), it will not get processed by any other firewall rule, and the sender of the packet is unaware of your treatment of his packet. Should you want to also log the packet, you’d use context "FORWARD" "filter" drop log –p tcp -s 10.0.0.0/16 The script works this out to iptables –t filter –A FORWARD –p tcp -s 10.0.0.0/16 –-jump LOG \ --log-prefix drop_FORWARD_filter: iptables –t filter –A FORWARD –p tcp -s 10.0.0.0/16 –-jump DROP However, be advised that using DROP may leave dead sockets on either the sending or receiving host. If you do not wish that, you might be better of using REJECT. On the other hand, dropping packets is a nice way of appearing like a black hole, so it's the weapon of choice against port scanners and the likes.<br> The DROP target can be used in any chain in any table. == Target keyword: ipv4optsstrip == '''''ipv4optsstrip [log [msg <message>]] <matches>'''''<br> This target takes any packet that fits the <matches>, and then strips off all IPv4 options from its header. It can only be used in the ''mangle'' table. For example, the following rule strips the IPv4 options from any packet incoming on ''eth0'': context PREROUTING mangle ipv4optsstrip -i eth0 == Target keyword: tochain == '''''tochain <customchain> [log [msg <message>]] <matches>'''''<br> If you've created a custom chain within a certain table, then you can jump to this custom chain using ''tochain'', as long as the ''tochain'' invocation appears in a context with the same table. For example: create_chain FTPtraffic filter (...) context INPUT filter (...) tochain FTPtraffic -p tcp --dport 20 In this example, any TCP packet that appears in table filter, chain INPUT and is directed at port 20, is sent on through to the previously created chain FTPTRAFFIC (keep in mind that Iceditch will always translate any chain name to all uppercase). Rule matching and packet processing will continue in that chain, until an ACCEPT or DROP is encountered, or a RETURN, or all rules in the custom chain have been exhausted. After that, the implicit return policy on your custom chain will return the packet to whence it came (context INPUT filter, the line below the ''tochain'' invocation). == Target keyword: log == ''for LOG target: '''log [(msg|message) <message>] [ip-options|ipopt] [(lvl|level) <loglevel>] [tcp-options|tcpopt] [tcp-sequence|tcpseq] <matches>'''''<br> ''for ULOG target: '''log [(msg|message) <message>] [cprange <range>] [qtreshold|qtresh <treshold>] <matches>''''' Sometimes, the standard ''log'' parameter is just not enough. This can be the case when you want to log a packet to a log-level other than the default level, which for most systems is ''4'' (''warning''). Furthermore, maybe you want to log a certain type or class of packets, without performing an action on those packets just yet. For this reason, AND for flexibility and clarity, Iceditch has the dedicated target keyword ''log''.<br> Just as when you use the ''log'' parameter after another target keyword, Iceditch will call the log target specified in the Iceditch [[Iceditch file structure | config file]]. Standard this is LOG, but optionally you could specify ULOG in the config file. Note, however, that an explicit call on target keyword ''log'' gives one the option to specify extra parameter. Note also, that the choice of parameters to specify depends on your choice of logging daemon, as specified in the [[Iceditch file structure | config file]]. === the message to log === Now the message that gets logged is treated the same by Iceditch, no matter which logging daemon you use. Somewhere after the target keyword ''log'' (but before any of the <matches> you specify ''msg <message>'' (or ''message <message>). The ''<message>'' can be any string between 1 and some 29 characters max (letters, numbers and underscores; no spaces, not empty). If you do NOT specify a message, Iceditch will always create a default log message: ''<chain>_<table>_log''. This means that <pre>context INPUT filter log -p tcp --dport 22 </pre> will result in either one of the iptables lines shown below, depending on your choice of logging daemon: <pre>iptables -A INPUT -t filter -p tcp --dport 22 --jump LOG --log-prefix INPUT_filter_log --log-level 4 iptables -A INPUT -t filter -p tcp --dport 22 --jump ULOG --ulog-prefix INPUT_filter_log </pre> (note the default log level when using the ''syslog'' logging daemon). === log parameters when using the ''syslog'' logging daemon=== Besides a log message, there are four options that you can also specify. These are shown in the table below: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" ! colspan="3" style="background:#ffdead;"|LOG options |- !style="background:#ffdead;"|Iceditch option !style="background:#ffdead;"|IPtables option !style="background:#ffdead;"|Description |- |ip-options / ipopt | --log-ip-options |Makes Netfilter include the IP options in the log entry |- | lvl / level <loglevel> | --log-level | Makes Netfilter log with the specified level |- | tcp-options / tcpopt | --log-tcp-options |Makes Netfilter include the TCP options in the log entry |- | tcp-sequence / tcpseq | --log-tcp-sequence |Makes Netfilter include the TCP sequence number in the log entry |- |} On the log-level: when using the ''syslog'' daemon (IPtables target LOG), it is possible to specify a log level. The log level can be specified numerically or by name; Iceditch will translate it to its numerical value. However, if you do NOT specify a log level, Iceditch will include a default log level, being 4 (warn). For completeness, we here reproduce the list of logging levels that ''log'' understands: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Level !style="background:#ffdead;"|Description |- |0 |''emerg'' or ''panic'' |- |1 |''alert'' |- |2 |''crit'' |- |3 |''err'' |- |4 |''warn'' (default) |- |5 |''notice'' |- |6 |''info'' |- |7 |''debug'' |- |} === log parameters when using the ''ulog'' user space logging daemon=== {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" ! colspan="3" style="background:#ffdead;"|ULOG options |- !style="background:#ffdead;"|Iceditch option !style="background:#ffdead;"|IPtables option !style="background:#ffdead;"|Description |- | cprange <''size''> | --ulog-cprange <''size''> |log the first ''size'' bytes of each packet |- | qtreshold / qtresh <''value''> | --ulog-qthreshold <''value''> |Queue ''value'' packets before sending them to ''ulogd'' (default = 1, max = 50) |- |} <br> Now an example: context "INPUT" "filter" log lvl info msg SSH_incoming -p tcp --dport 22 -i $inetIF Iceditch works this out into iptables -A INPUT -t filter -p tcp --dport 22 -i $inetIF --jump ULOG --ulog-prefix "SSH_incoming" --log-level 6 == Target keyword: mark == '''''mark <markval> [log [msg <message>]] <matches>'''''<br> If a packet matches the <matches>, then it will be marked with the <markval> specified. An example from the context PREROUTING mangle: mark 2 –p tcp --dport 22 Iceditch works this out to iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump MARK --setmark 2 Should you want to also log the packet, you’d use mark 2 log –p tcp --dport 22 Iceditch works this out to iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump LOG \ --log-prefix mark_PREROUTING_mangle: iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump MARK --setmark 2 Because of how iptables handles the MARK target, you can only use it in contexts where the table is ''mangle''. == Target keyword: masquerade == '''''masquerade <iface> [to <p1[-p2]>] [log [msg <message>]] <matches>'''''<br> <iface> is the (outward facing) network interface that we want to masquerade on.<br> The MASQUERADE target is used basically the same as the SNAT target, but it does not require any ''--to-source'' option. The reason for this is that the MASQUERADE target was made to work with connections which get dynamic IP addresses when connecting to the network in question, for example dial-up connections, or DHCP connections. This means that you should only use the MASQUERADE target with dynamically assigned IP connections, which we don't know the actual IP address of in advance. If you have a static IP connection, you should instead use the SNAT target.<br> When you masquerade a connection, it means that we set the IP address used on a specific network ''interface'', instead of getting it from the ''--to-source option''. The necessary IP address is automatically grabbed from the information about the specific interface. Using the ''masquerade'' keyword also has the advantage that connections are forgotten when an interface goes down, which is extremely good if we, for example, kill a specific interface. If we would have used the SNAT target, we may have been left with a lot of old connection tracking data, which would be kept in connection tracking memory for days. forgetting about connections is, in general, the correct behavior when dealing with dial-up lines that are probably assigned a different IP every time they are brought up. In case we are assigned a different IP, the connection is lost anyways, and it is more or less idiotic to keep the entry around.<br> It is still possible to use the MASQUERADE target instead of SNAT even though you do have a static IP; however, it is not favorable since it will add extra overhead, and there may be inconsistencies in the future which will thwart your existing scripts and render them "unusable".<br> Note that the MASQUERADE target is only valid within the POSTROUTING chain in the nat table, just as the SNAT target. == Target keyword: redirect == '''''redirect [to <to-ports>] [log [msg <message>]] <matches>'''''<br> If a packet matches the <matches>, then it will be redirected to the local machine, by setting the destination IP to a fitting IP address of the local machine (i.e. 127.0.0.1, or the first-bound IP address of the interface over which it came in. Additionally, by specifying “to <to-ports>” you can have the destination ports redirected to a port or portrange. <to-ports> can either be a port number (e.g. 8080) or a port range (e.g. 6661-6669; the latter is inclusive). Example for a transparent HTTP proxy: context "OUTPUT" "nat" redirect to 8080 –p tcp --dport 80 Iceditch works this out to iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump REDIRECT –to-ports 8080 Should you want to log the packet, you could use redirect to 8080 log –p tcp --dport 80 Iceditch works this out to iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump LOG \ --log-prefix OUTPUT_REDIRECT_to_8080: iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump REDIRECT –-to-ports 8080 Because of how iptables handles the REDIRECT target, you can only use it in contexts where the table is "nat" and the chain is PREROUTING or OUTPUT. == Target keyword: reject == '''''reject [with <type>] [log [msg <message>]] <matches>'''''<br> In essence, this does the same as the "drop" target keyword, only it jumps to REJECT instead of DROP. This means the packet is discarded (just as with DROP), but the sender is notified using ICMP (by default, your machine will send an ICMP-packet of type "icmp-port-unreachable"). Because of how iptables handles the REJECT target, you can only use it in contexts where the table is "filter". Optionally, you can follow "reject" with the keyword "with", and then use one of the following rejection types: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Type !style="background:#ffdead;"|Description |- | icmp-host-prohibited | will send an ICMP-message "host prohibited" |- | icmp-host-unreachable | will send an ICMP-message "host unreachable" |- | icmp-net-prohibited | will send an ICMP-message "net prohibited" |- | icmp-net-unreachable | will send an ICMP-message "net unreachable" |- | icmp-port-unreachable | DEFAULT; will send an ICMP-message "port unreachable" |- | icmp-proto-unreachable | DEFAULT; will send an ICMP-message "protocol unreachable" |- | tcp-reset | will send a TCP reset, a packet with the RST flag set (as a response to a TCP packet only) |- | host-prohib | synonymous to icmp-host-prohibited |- | host-unreach | synonymous to icmp-host-unreachable |- | net-prohib | synonymous to icmp-net-prohibited |- | net-unreach | synonymous to icmp-net-unreachable |- | port-unreach | synonymous to icmp-port-unreachable |- | proto-unreach | synonymous to icmp-proto-unreachable |- |} If you don’t specify "with <type>", then netfilter will assume icmp-port-unreachable. Thus, should you want to reject a packet in context filter INPUT (and log it) with reason net-prohib, you’d use reject with net-prohib log –p tcp –i eth0 --dport 22 Iceditch works this out to iptables –t filter –A INPUT –p tcp –i eth0 –-dport 22 –-jump LOG \ --log-prefix INPUT_REJECT_with_net-prohib: iptables –t filter –A INPUT –p tcp –i eth0 –-dport 22 \ –-jump REJECT –-reject-with net-prohib –p tcp –i eth0 –-dport 22 ==Target keyword: route== '''''route {<iface>|<ifaceindex>} [log [msg <message>]] <matches>'''''<br> The ''route'' target lets you route a received packet through an interface or towards a host, even if the regular destination of the packet is the router itself. The ROUTE target is also able to change the incoming interface of a packet. Packets are directly put on the wire and do not traverse any other table.<br> ''route'' takes one mandatory option, which may be either the interface name over which to route the packet that matches the <matches>, or the index number of that interface (based on the order in /proc/net/dev). Iceditch is pretty lazy in how to interpret that option: if it's all numerals, Iceditch treats it as the interface index number, if it contains any other character, it is considered the interface name (e.g. ''eth0''); and no sanity check is performed on the specified <iface|ifaceindex>. == Target keyword: same== '''''same [to <a1[-a2]> [to <a3[-a4]>] ] [nodest] [log [msg <message>] ] <matches>'''''<br> ''same'' only works in the nat table, in the POSTROUTING chain. It is very closely related to ''snat'' (see below), because it does virtually the same thing. Basically, the ''same'' target will try to always use the same outgoing IP address for all connections initiated by a single host on your network. For example, say you have one "internal" /24 network (192.168.1.0) and 3 "external" IP addresses (10.5.6.11-13) on your firewall/router machine. Now, if internal machine 192.168.1.20 went out through the .11 address the first time, then the firewall will try to keep that machine always going out through that same IP address. So basically ''same'' might be a better fit than ''snat'' if you have multiple external IP addresses.<br> However, there is also functionality lacking in ''same'' that ''snat'' has, namely the specification of (TCP and UDP) ports or port ranges to use for the NATting operation. See ''snat'' for its port possibilities.<br> Furthermore, ''same'' has an extra option that ''snat'' does not have: under normal action, the ''same'' target is calculating the followup connections based on both destination and source IP addresses. Using the ''nodest'' option (which corresponds with --nodst in the actual IPtables command), it uses only the source IP address to find out which outgoing IP the NAT function should use for the specific connection. Without this argument, it uses a combination of the destination and source IP address. == Target keyword: snat== '''''snat [to <a1[-a2][:p1-p2]]> [to <a3[-a4][:p3-p4]]>] ] [log [msg <message>] ] <matches>'''''<br> This keyword is only valid in the chain POSTROUTING, table nat. And ofcourse, source NATting does you little good if you haven't enabled forwarding (e.g. use this machine as a router for other machines on your network).<br> Calling snat with the right parameters will create a Source NATting rule for you, whereby a packet matching the <matches> will be source NATted using the source IP address ''a1'' (or the range ''a1-a2''). Ofcourse, ''a1[-a2]'' should be valid IP address(es) of the firewalling machine.<br> Furthermore, if a port range ''p1-p2'' is specified, then you'll limit the range of ports that ''snat'' will use outbound (only valid for TCP or UDP packets).<br> Finally, it is possible to specify ''multiple'' IP address ranges and port ranges, using multiple ''to <a1[-a2][:p1-p2]]'' declarations in succession.<br> An example would be: context "POSTROUTING" "nat" snat to $inetIP -o $inetIF ! --src $inetIP If the variable ''$inetIP'' contains your public IP (e.g. 212.238.151.72), and ''$inetIF'' your interface connected to the Internet (e.g. ''eth0''), then this rule would expand to iptables -A POSTROUTING -t nat -o eth0 ! --src 212.238.151.72 -j SNAT --to-source 212.238.151.72 This would cause Iceditch to source NAT any outbound packet that is NOT sent by your firewall itself; in effect your server is now a nice fullblown NAT router for all machines on your private network. 2513e24a64cb2880115e70efa707fd84e7f681bb 1616 1615 2008-08-12T06:09:54Z Saruman! 2 /* log parameters when using the ''syslog'' logging daemon */ edited option table wikitext text/x-wiki == Parameter: log == ''target '''log [(msg|message) <message>]''' <matches>''<br> After most keywords, a "log" parameter can be added (see below). If the "log" parameter is followed by "msg" (or "message"), then the parameter following "msg" is read and used as log-prefix. The parameter is not allowed to have whitespace (that limitation is Iceditch-specific, not IPtables-related), and the maximum length of the log-prefix is determined by your version of netfilter/IPtables and your choice of IPtables logging utility (syslogemu or ulog); this limit is usually some 29 characters. Note that Iceditch does not perform any sanity checks on the message. Thus a packet matching the <matches> part of the rule will be logged with the default setting of the "log" target. If the "log" parameter is ''not'' followed by "msg", then the packet will be logged with a default log message, being "&lt;table&gt;_<chain>_<target>" and all the other default setting of the "log" target. Thus, should you want to log a packet with more control over the logging parameters, then you need an extra line, beginning with the ''target keyword'' "log", instead of just following the target keyword with parameter ''log''. For more information, see the [[Iceditch_Command_Reference#Target_keyword:_log | target keyword "log"]] below. == Context keyword: context == '''''context <chain> &lt;table&gt;'''''<br> Every IPtables rule is written to a chain in a table; with Iceditch, you don't have to specify the chain and table in every line. Just precede the lines with the ''context'' statement. Example: context POSTROUTING nat Notes: the order of chain and table does not matter; ''context nat POSTROUTING'' works just as well. Furthermore, <chain> and &lt;table&gt; have been made case-insensitive; whatever you specify as chain will be translated to uppercase, whatever you specify as table will be translated to lowercase. This gives you the possibility to write the context as you like to read it, e.g. ''context Postrouting Nat''; after processing this, Iceditch will have two variables $CHAIN="POSTROUTING" and $TABLE="nat" that it will use in every following command. For example: context "Input" "fIlTeR" accept -p tcp --dport 22 will result in the following IPtables call: iptables -A INPUT -t filter -p tcp --dport 22 --jump ACCEPT If you do NOT specify a [[Iceditch IPtables language | valid combination]] of chain and table, the execution of Iceditch will halt with a fatal error. It is allowed (but not recommended) to call ''context'' multiple times for the same combination of chain and table; the order in which the rules are added to that chain in that table, is the same in which they appear in your rulefile, top to bottom. This is not recommended, because we feel it decreases readability, and thus maintainability, of the rules file. But hey, it's going to be ''your'' rulefile anyway...<br> Note: you cannot create custom chains by the names of mangle, nat or filter, since Iceditch will always interpret these names as those of tables. == Context keyword: create_chain == '''''create_chain <chain> [&lt;table&gt;]'''''<br> This command creates a new chain named <chain>, in the specified table &lt;table&gt;. If no table is specified, then the ''filter'' table is assumed. Just as with the ''context'' command, the <chain> name you specify will be translated to all uppercase.<br> The name for your new chain must be unique, although just like the built-in chains, you can specify the same name in different tables. If you create "fun-filter" in table ''filter'', and then create a "fun-filter" in table ''nat'', then you actually have two different chains. But remember: since Iceditch translates every chain name to uppercase, you can't create "Fun-filter" AND "fun-FILTER" in the same table - they're the same chain.<br> NOTE: after you've run ''create_chain'', you still have to switch context to create rules in the new chain! example:<br> create_chain fun-filter context fun-filter filter accept -p tcp --dport 22 This will result in iptables -N FUN-FILTER -t filter iptables -A FUN-FILTER -t filter -p tcp --dport 22 --jump ACCEPT == Target keyword: accept == '''''accept [log [msg <message>]] <matches>'''''<br> If a network packet fits the <matches>, then it will be accepted (passed) through the table/chain defined in the context where you put the accept rule. Example: context Input Filter accept –p tcp --dport 22 Iceditch works this out to iptables –t filter –A INPUT –p tcp –-dport 22 –-jump ACCEPT Should you want to log the packet, you’d use context Input Filter accept log –p tcp --dport 22 Iceditch works this out to iptables –t filter –A INPUT –p tcp –-dport 22 \ –-jump LOG --log-prefix accept_INPUT_filter iptables –t filter –A INPUT –p tcp –-dport 22 –-jump ACCEPT Note: the ACCEPT target is valid in any user-manipulable table/chain combination == Target keyword: classify == '''''classify <classval> [log [msg <message>]] <matches>'''''<br> If a packet travelling through the mangle table in the POSTROUTING chain matches the <matches>, then it will be classified with the <classval> specified. An example: classify 2:11 –p tcp --dport 22 The script works this out to iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump CLASSIFY --setclass 2:11 Should you want to also log the packet, you’d use classify 2:11 log msg classified_2:11 –p tcp --dport 22 The script works this out to iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump LOG \ --log-prefix classified_2:11: iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump CLASSIFY \ --setclass 2:11 Should you not give a msg, then the log-prefix becomes classify_POSTROUTING_mangle. Because of how iptables handles the CLASSIFY target, you can only use it in contexts where the chain is "POSTROUTING" and the table is "mangle". == Target keyword: dnat == '''''dnat [to] <a1[-a2][:p1[-p2]]> [log [msg <message>]] <matches>'''''<br> In the above, a1 and a2 are used to specify a (range of) IP address(es); for TCP and UDP protocols, a destination port or port range can be provided. Note that the "to" in the command is optional, and serves only readability.<br> If a packet matches the qualifiers, then it will be destination-NATted to the provided IP address or address range. For example, if you want to DNAT port 81 on your external interface eth1 to an internal webserver on 10.0.0.1, you could use context "PREROUTING" "nat" dnat to 10.0.0.1:80 –p tcp –i eth1 –-dport 81 If you give a range of IP addresses, then the DNAT logic of IPtables will randomly pick an address and DNAT the packet there. However, note that a single stream will always use the same IP address from that range, and that each stream will randomly be given an IP address that it will always be destined for, within that stream.<br> Furthermore, note that the DNAT target is only available within the PREROUTING and OUTPUT chains in the nat table, and any of the chains called upon from any of those listed chains. Note that chains containing DNAT targets may not be used from any other chains, such as the POSTROUTING chain. However, the bad news is that Iceditch currently does not know how to check for the latter case, so the dnat keyword only works from contexts "PREROUTING" "nat" and "OUTPUT" "nat". == Target keyword: drop == '''''drop [log [msg <message>]] <matches> '''''<br> In essence, this does the same as the "accept" target keyword, only it jumps to DROP instead of ACCEPT. Thus any packet matching the <matches> gets discarded; it will not get sent on to its final destination (or next hop), it will not get processed by any other firewall rule, and the sender of the packet is unaware of your treatment of his packet. Should you want to also log the packet, you’d use context "FORWARD" "filter" drop log –p tcp -s 10.0.0.0/16 The script works this out to iptables –t filter –A FORWARD –p tcp -s 10.0.0.0/16 –-jump LOG \ --log-prefix drop_FORWARD_filter: iptables –t filter –A FORWARD –p tcp -s 10.0.0.0/16 –-jump DROP However, be advised that using DROP may leave dead sockets on either the sending or receiving host. If you do not wish that, you might be better of using REJECT. On the other hand, dropping packets is a nice way of appearing like a black hole, so it's the weapon of choice against port scanners and the likes.<br> The DROP target can be used in any chain in any table. == Target keyword: ipv4optsstrip == '''''ipv4optsstrip [log [msg <message>]] <matches>'''''<br> This target takes any packet that fits the <matches>, and then strips off all IPv4 options from its header. It can only be used in the ''mangle'' table. For example, the following rule strips the IPv4 options from any packet incoming on ''eth0'': context PREROUTING mangle ipv4optsstrip -i eth0 == Target keyword: tochain == '''''tochain <customchain> [log [msg <message>]] <matches>'''''<br> If you've created a custom chain within a certain table, then you can jump to this custom chain using ''tochain'', as long as the ''tochain'' invocation appears in a context with the same table. For example: create_chain FTPtraffic filter (...) context INPUT filter (...) tochain FTPtraffic -p tcp --dport 20 In this example, any TCP packet that appears in table filter, chain INPUT and is directed at port 20, is sent on through to the previously created chain FTPTRAFFIC (keep in mind that Iceditch will always translate any chain name to all uppercase). Rule matching and packet processing will continue in that chain, until an ACCEPT or DROP is encountered, or a RETURN, or all rules in the custom chain have been exhausted. After that, the implicit return policy on your custom chain will return the packet to whence it came (context INPUT filter, the line below the ''tochain'' invocation). == Target keyword: log == ''for LOG target: '''log [(msg|message) <message>] [ip-options|ipopt] [(lvl|level) <loglevel>] [tcp-options|tcpopt] [tcp-sequence|tcpseq] <matches>'''''<br> ''for ULOG target: '''log [(msg|message) <message>] [cprange <range>] [qtreshold|qtresh <treshold>] <matches>''''' Sometimes, the standard ''log'' parameter is just not enough. This can be the case when you want to log a packet to a log-level other than the default level, which for most systems is ''4'' (''warning''). Furthermore, maybe you want to log a certain type or class of packets, without performing an action on those packets just yet. For this reason, AND for flexibility and clarity, Iceditch has the dedicated target keyword ''log''.<br> Just as when you use the ''log'' parameter after another target keyword, Iceditch will call the log target specified in the Iceditch [[Iceditch file structure | config file]]. Standard this is LOG, but optionally you could specify ULOG in the config file. Note, however, that an explicit call on target keyword ''log'' gives one the option to specify extra parameter. Note also, that the choice of parameters to specify depends on your choice of logging daemon, as specified in the [[Iceditch file structure | config file]]. === the message to log === Now the message that gets logged is treated the same by Iceditch, no matter which logging daemon you use. Somewhere after the target keyword ''log'' (but before any of the <matches> you specify ''msg <message>'' (or ''message <message>). The ''<message>'' can be any string between 1 and some 29 characters max (letters, numbers and underscores; no spaces, not empty). If you do NOT specify a message, Iceditch will always create a default log message: ''<chain>_<table>_log''. This means that <pre>context INPUT filter log -p tcp --dport 22 </pre> will result in either one of the iptables lines shown below, depending on your choice of logging daemon: <pre>iptables -A INPUT -t filter -p tcp --dport 22 --jump LOG --log-prefix INPUT_filter_log --log-level 4 iptables -A INPUT -t filter -p tcp --dport 22 --jump ULOG --ulog-prefix INPUT_filter_log </pre> (note the default log level when using the ''syslog'' logging daemon). === log parameters when using the ''syslog'' logging daemon=== Besides a log message, there are four more options that you can also specify. All five options are shown in the table below: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" ! colspan="3" style="background:#ffdead;"|LOG options |- !style="background:#ffdead;"|Iceditch option !style="background:#ffdead;"|IPtables option !style="background:#ffdead;"|Description |- |ip-options / ipopt | --log-ip-options |Makes Netfilter include the IP options in the log entry |- | lvl / level <''loglevel''> | --log-level <''loglevel''> | Makes Netfilter log with the specified <''loglevel''> |- | msg / message <''logmessage''> | --log-prefix <''logmessage''> | Makes Netfilter prepend <''logmessage''> to the log entry |- | tcp-options / tcpopt | --log-tcp-options |Makes Netfilter include the TCP options in the log entry |- | tcp-sequence / tcpseq | --log-tcp-sequence |Makes Netfilter include the TCP sequence number in the log entry |- |} On the log-level: when using the ''syslog'' daemon (IPtables target LOG), it is possible to specify a log level. The log level can be specified numerically or by name; Iceditch will translate it to its numerical value. However, if you do NOT specify a log level, Iceditch will include a default log level, being 4 (warn). For completeness, we here reproduce the list of logging levels that ''log'' understands: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Level !style="background:#ffdead;"|Description |- |0 |''emerg'' or ''panic'' |- |1 |''alert'' |- |2 |''crit'' |- |3 |''err'' |- |4 |''warn'' (default) |- |5 |''notice'' |- |6 |''info'' |- |7 |''debug'' |- |} === log parameters when using the ''ulog'' user space logging daemon=== {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" ! colspan="3" style="background:#ffdead;"|ULOG options |- !style="background:#ffdead;"|Iceditch option !style="background:#ffdead;"|IPtables option !style="background:#ffdead;"|Description |- | cprange <''size''> | --ulog-cprange <''size''> |log the first ''size'' bytes of each packet |- | qtreshold / qtresh <''value''> | --ulog-qthreshold <''value''> |Queue ''value'' packets before sending them to ''ulogd'' (default = 1, max = 50) |- |} <br> Now an example: context "INPUT" "filter" log lvl info msg SSH_incoming -p tcp --dport 22 -i $inetIF Iceditch works this out into iptables -A INPUT -t filter -p tcp --dport 22 -i $inetIF --jump ULOG --ulog-prefix "SSH_incoming" --log-level 6 == Target keyword: mark == '''''mark <markval> [log [msg <message>]] <matches>'''''<br> If a packet matches the <matches>, then it will be marked with the <markval> specified. An example from the context PREROUTING mangle: mark 2 –p tcp --dport 22 Iceditch works this out to iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump MARK --setmark 2 Should you want to also log the packet, you’d use mark 2 log –p tcp --dport 22 Iceditch works this out to iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump LOG \ --log-prefix mark_PREROUTING_mangle: iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump MARK --setmark 2 Because of how iptables handles the MARK target, you can only use it in contexts where the table is ''mangle''. == Target keyword: masquerade == '''''masquerade <iface> [to <p1[-p2]>] [log [msg <message>]] <matches>'''''<br> <iface> is the (outward facing) network interface that we want to masquerade on.<br> The MASQUERADE target is used basically the same as the SNAT target, but it does not require any ''--to-source'' option. The reason for this is that the MASQUERADE target was made to work with connections which get dynamic IP addresses when connecting to the network in question, for example dial-up connections, or DHCP connections. This means that you should only use the MASQUERADE target with dynamically assigned IP connections, which we don't know the actual IP address of in advance. If you have a static IP connection, you should instead use the SNAT target.<br> When you masquerade a connection, it means that we set the IP address used on a specific network ''interface'', instead of getting it from the ''--to-source option''. The necessary IP address is automatically grabbed from the information about the specific interface. Using the ''masquerade'' keyword also has the advantage that connections are forgotten when an interface goes down, which is extremely good if we, for example, kill a specific interface. If we would have used the SNAT target, we may have been left with a lot of old connection tracking data, which would be kept in connection tracking memory for days. forgetting about connections is, in general, the correct behavior when dealing with dial-up lines that are probably assigned a different IP every time they are brought up. In case we are assigned a different IP, the connection is lost anyways, and it is more or less idiotic to keep the entry around.<br> It is still possible to use the MASQUERADE target instead of SNAT even though you do have a static IP; however, it is not favorable since it will add extra overhead, and there may be inconsistencies in the future which will thwart your existing scripts and render them "unusable".<br> Note that the MASQUERADE target is only valid within the POSTROUTING chain in the nat table, just as the SNAT target. == Target keyword: redirect == '''''redirect [to <to-ports>] [log [msg <message>]] <matches>'''''<br> If a packet matches the <matches>, then it will be redirected to the local machine, by setting the destination IP to a fitting IP address of the local machine (i.e. 127.0.0.1, or the first-bound IP address of the interface over which it came in. Additionally, by specifying “to <to-ports>” you can have the destination ports redirected to a port or portrange. <to-ports> can either be a port number (e.g. 8080) or a port range (e.g. 6661-6669; the latter is inclusive). Example for a transparent HTTP proxy: context "OUTPUT" "nat" redirect to 8080 –p tcp --dport 80 Iceditch works this out to iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump REDIRECT –to-ports 8080 Should you want to log the packet, you could use redirect to 8080 log –p tcp --dport 80 Iceditch works this out to iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump LOG \ --log-prefix OUTPUT_REDIRECT_to_8080: iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump REDIRECT –-to-ports 8080 Because of how iptables handles the REDIRECT target, you can only use it in contexts where the table is "nat" and the chain is PREROUTING or OUTPUT. == Target keyword: reject == '''''reject [with <type>] [log [msg <message>]] <matches>'''''<br> In essence, this does the same as the "drop" target keyword, only it jumps to REJECT instead of DROP. This means the packet is discarded (just as with DROP), but the sender is notified using ICMP (by default, your machine will send an ICMP-packet of type "icmp-port-unreachable"). Because of how iptables handles the REJECT target, you can only use it in contexts where the table is "filter". Optionally, you can follow "reject" with the keyword "with", and then use one of the following rejection types: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Type !style="background:#ffdead;"|Description |- | icmp-host-prohibited | will send an ICMP-message "host prohibited" |- | icmp-host-unreachable | will send an ICMP-message "host unreachable" |- | icmp-net-prohibited | will send an ICMP-message "net prohibited" |- | icmp-net-unreachable | will send an ICMP-message "net unreachable" |- | icmp-port-unreachable | DEFAULT; will send an ICMP-message "port unreachable" |- | icmp-proto-unreachable | DEFAULT; will send an ICMP-message "protocol unreachable" |- | tcp-reset | will send a TCP reset, a packet with the RST flag set (as a response to a TCP packet only) |- | host-prohib | synonymous to icmp-host-prohibited |- | host-unreach | synonymous to icmp-host-unreachable |- | net-prohib | synonymous to icmp-net-prohibited |- | net-unreach | synonymous to icmp-net-unreachable |- | port-unreach | synonymous to icmp-port-unreachable |- | proto-unreach | synonymous to icmp-proto-unreachable |- |} If you don’t specify "with <type>", then netfilter will assume icmp-port-unreachable. Thus, should you want to reject a packet in context filter INPUT (and log it) with reason net-prohib, you’d use reject with net-prohib log –p tcp –i eth0 --dport 22 Iceditch works this out to iptables –t filter –A INPUT –p tcp –i eth0 –-dport 22 –-jump LOG \ --log-prefix INPUT_REJECT_with_net-prohib: iptables –t filter –A INPUT –p tcp –i eth0 –-dport 22 \ –-jump REJECT –-reject-with net-prohib –p tcp –i eth0 –-dport 22 ==Target keyword: route== '''''route {<iface>|<ifaceindex>} [log [msg <message>]] <matches>'''''<br> The ''route'' target lets you route a received packet through an interface or towards a host, even if the regular destination of the packet is the router itself. The ROUTE target is also able to change the incoming interface of a packet. Packets are directly put on the wire and do not traverse any other table.<br> ''route'' takes one mandatory option, which may be either the interface name over which to route the packet that matches the <matches>, or the index number of that interface (based on the order in /proc/net/dev). Iceditch is pretty lazy in how to interpret that option: if it's all numerals, Iceditch treats it as the interface index number, if it contains any other character, it is considered the interface name (e.g. ''eth0''); and no sanity check is performed on the specified <iface|ifaceindex>. == Target keyword: same== '''''same [to <a1[-a2]> [to <a3[-a4]>] ] [nodest] [log [msg <message>] ] <matches>'''''<br> ''same'' only works in the nat table, in the POSTROUTING chain. It is very closely related to ''snat'' (see below), because it does virtually the same thing. Basically, the ''same'' target will try to always use the same outgoing IP address for all connections initiated by a single host on your network. For example, say you have one "internal" /24 network (192.168.1.0) and 3 "external" IP addresses (10.5.6.11-13) on your firewall/router machine. Now, if internal machine 192.168.1.20 went out through the .11 address the first time, then the firewall will try to keep that machine always going out through that same IP address. So basically ''same'' might be a better fit than ''snat'' if you have multiple external IP addresses.<br> However, there is also functionality lacking in ''same'' that ''snat'' has, namely the specification of (TCP and UDP) ports or port ranges to use for the NATting operation. See ''snat'' for its port possibilities.<br> Furthermore, ''same'' has an extra option that ''snat'' does not have: under normal action, the ''same'' target is calculating the followup connections based on both destination and source IP addresses. Using the ''nodest'' option (which corresponds with --nodst in the actual IPtables command), it uses only the source IP address to find out which outgoing IP the NAT function should use for the specific connection. Without this argument, it uses a combination of the destination and source IP address. == Target keyword: snat== '''''snat [to <a1[-a2][:p1-p2]]> [to <a3[-a4][:p3-p4]]>] ] [log [msg <message>] ] <matches>'''''<br> This keyword is only valid in the chain POSTROUTING, table nat. And ofcourse, source NATting does you little good if you haven't enabled forwarding (e.g. use this machine as a router for other machines on your network).<br> Calling snat with the right parameters will create a Source NATting rule for you, whereby a packet matching the <matches> will be source NATted using the source IP address ''a1'' (or the range ''a1-a2''). Ofcourse, ''a1[-a2]'' should be valid IP address(es) of the firewalling machine.<br> Furthermore, if a port range ''p1-p2'' is specified, then you'll limit the range of ports that ''snat'' will use outbound (only valid for TCP or UDP packets).<br> Finally, it is possible to specify ''multiple'' IP address ranges and port ranges, using multiple ''to <a1[-a2][:p1-p2]]'' declarations in succession.<br> An example would be: context "POSTROUTING" "nat" snat to $inetIP -o $inetIF ! --src $inetIP If the variable ''$inetIP'' contains your public IP (e.g. 212.238.151.72), and ''$inetIF'' your interface connected to the Internet (e.g. ''eth0''), then this rule would expand to iptables -A POSTROUTING -t nat -o eth0 ! --src 212.238.151.72 -j SNAT --to-source 212.238.151.72 This would cause Iceditch to source NAT any outbound packet that is NOT sent by your firewall itself; in effect your server is now a nice fullblown NAT router for all machines on your private network. d6dc108e35346fa83f95e3efe1f73629548ac10e 1617 1616 2008-08-12T06:23:54Z Saruman! 2 /* Target keyword: log */ clarified difference log/ulog wikitext text/x-wiki == Parameter: log == ''target '''log [(msg|message) <message>]''' <matches>''<br> After most keywords, a "log" parameter can be added (see below). If the "log" parameter is followed by "msg" (or "message"), then the parameter following "msg" is read and used as log-prefix. The parameter is not allowed to have whitespace (that limitation is Iceditch-specific, not IPtables-related), and the maximum length of the log-prefix is determined by your version of netfilter/IPtables and your choice of IPtables logging utility (syslogemu or ulog); this limit is usually some 29 characters. Note that Iceditch does not perform any sanity checks on the message. Thus a packet matching the <matches> part of the rule will be logged with the default setting of the "log" target. If the "log" parameter is ''not'' followed by "msg", then the packet will be logged with a default log message, being "&lt;table&gt;_<chain>_<target>" and all the other default setting of the "log" target. Thus, should you want to log a packet with more control over the logging parameters, then you need an extra line, beginning with the ''target keyword'' "log", instead of just following the target keyword with parameter ''log''. For more information, see the [[Iceditch_Command_Reference#Target_keyword:_log | target keyword "log"]] below. == Context keyword: context == '''''context <chain> &lt;table&gt;'''''<br> Every IPtables rule is written to a chain in a table; with Iceditch, you don't have to specify the chain and table in every line. Just precede the lines with the ''context'' statement. Example: context POSTROUTING nat Notes: the order of chain and table does not matter; ''context nat POSTROUTING'' works just as well. Furthermore, <chain> and &lt;table&gt; have been made case-insensitive; whatever you specify as chain will be translated to uppercase, whatever you specify as table will be translated to lowercase. This gives you the possibility to write the context as you like to read it, e.g. ''context Postrouting Nat''; after processing this, Iceditch will have two variables $CHAIN="POSTROUTING" and $TABLE="nat" that it will use in every following command. For example: context "Input" "fIlTeR" accept -p tcp --dport 22 will result in the following IPtables call: iptables -A INPUT -t filter -p tcp --dport 22 --jump ACCEPT If you do NOT specify a [[Iceditch IPtables language | valid combination]] of chain and table, the execution of Iceditch will halt with a fatal error. It is allowed (but not recommended) to call ''context'' multiple times for the same combination of chain and table; the order in which the rules are added to that chain in that table, is the same in which they appear in your rulefile, top to bottom. This is not recommended, because we feel it decreases readability, and thus maintainability, of the rules file. But hey, it's going to be ''your'' rulefile anyway...<br> Note: you cannot create custom chains by the names of mangle, nat or filter, since Iceditch will always interpret these names as those of tables. == Context keyword: create_chain == '''''create_chain <chain> [&lt;table&gt;]'''''<br> This command creates a new chain named <chain>, in the specified table &lt;table&gt;. If no table is specified, then the ''filter'' table is assumed. Just as with the ''context'' command, the <chain> name you specify will be translated to all uppercase.<br> The name for your new chain must be unique, although just like the built-in chains, you can specify the same name in different tables. If you create "fun-filter" in table ''filter'', and then create a "fun-filter" in table ''nat'', then you actually have two different chains. But remember: since Iceditch translates every chain name to uppercase, you can't create "Fun-filter" AND "fun-FILTER" in the same table - they're the same chain.<br> NOTE: after you've run ''create_chain'', you still have to switch context to create rules in the new chain! example:<br> create_chain fun-filter context fun-filter filter accept -p tcp --dport 22 This will result in iptables -N FUN-FILTER -t filter iptables -A FUN-FILTER -t filter -p tcp --dport 22 --jump ACCEPT == Target keyword: accept == '''''accept [log [msg <message>]] <matches>'''''<br> If a network packet fits the <matches>, then it will be accepted (passed) through the table/chain defined in the context where you put the accept rule. Example: context Input Filter accept –p tcp --dport 22 Iceditch works this out to iptables –t filter –A INPUT –p tcp –-dport 22 –-jump ACCEPT Should you want to log the packet, you’d use context Input Filter accept log –p tcp --dport 22 Iceditch works this out to iptables –t filter –A INPUT –p tcp –-dport 22 \ –-jump LOG --log-prefix accept_INPUT_filter iptables –t filter –A INPUT –p tcp –-dport 22 –-jump ACCEPT Note: the ACCEPT target is valid in any user-manipulable table/chain combination == Target keyword: classify == '''''classify <classval> [log [msg <message>]] <matches>'''''<br> If a packet travelling through the mangle table in the POSTROUTING chain matches the <matches>, then it will be classified with the <classval> specified. An example: classify 2:11 –p tcp --dport 22 The script works this out to iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump CLASSIFY --setclass 2:11 Should you want to also log the packet, you’d use classify 2:11 log msg classified_2:11 –p tcp --dport 22 The script works this out to iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump LOG \ --log-prefix classified_2:11: iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump CLASSIFY \ --setclass 2:11 Should you not give a msg, then the log-prefix becomes classify_POSTROUTING_mangle. Because of how iptables handles the CLASSIFY target, you can only use it in contexts where the chain is "POSTROUTING" and the table is "mangle". == Target keyword: dnat == '''''dnat [to] <a1[-a2][:p1[-p2]]> [log [msg <message>]] <matches>'''''<br> In the above, a1 and a2 are used to specify a (range of) IP address(es); for TCP and UDP protocols, a destination port or port range can be provided. Note that the "to" in the command is optional, and serves only readability.<br> If a packet matches the qualifiers, then it will be destination-NATted to the provided IP address or address range. For example, if you want to DNAT port 81 on your external interface eth1 to an internal webserver on 10.0.0.1, you could use context "PREROUTING" "nat" dnat to 10.0.0.1:80 –p tcp –i eth1 –-dport 81 If you give a range of IP addresses, then the DNAT logic of IPtables will randomly pick an address and DNAT the packet there. However, note that a single stream will always use the same IP address from that range, and that each stream will randomly be given an IP address that it will always be destined for, within that stream.<br> Furthermore, note that the DNAT target is only available within the PREROUTING and OUTPUT chains in the nat table, and any of the chains called upon from any of those listed chains. Note that chains containing DNAT targets may not be used from any other chains, such as the POSTROUTING chain. However, the bad news is that Iceditch currently does not know how to check for the latter case, so the dnat keyword only works from contexts "PREROUTING" "nat" and "OUTPUT" "nat". == Target keyword: drop == '''''drop [log [msg <message>]] <matches> '''''<br> In essence, this does the same as the "accept" target keyword, only it jumps to DROP instead of ACCEPT. Thus any packet matching the <matches> gets discarded; it will not get sent on to its final destination (or next hop), it will not get processed by any other firewall rule, and the sender of the packet is unaware of your treatment of his packet. Should you want to also log the packet, you’d use context "FORWARD" "filter" drop log –p tcp -s 10.0.0.0/16 The script works this out to iptables –t filter –A FORWARD –p tcp -s 10.0.0.0/16 –-jump LOG \ --log-prefix drop_FORWARD_filter: iptables –t filter –A FORWARD –p tcp -s 10.0.0.0/16 –-jump DROP However, be advised that using DROP may leave dead sockets on either the sending or receiving host. If you do not wish that, you might be better of using REJECT. On the other hand, dropping packets is a nice way of appearing like a black hole, so it's the weapon of choice against port scanners and the likes.<br> The DROP target can be used in any chain in any table. == Target keyword: ipv4optsstrip == '''''ipv4optsstrip [log [msg <message>]] <matches>'''''<br> This target takes any packet that fits the <matches>, and then strips off all IPv4 options from its header. It can only be used in the ''mangle'' table. For example, the following rule strips the IPv4 options from any packet incoming on ''eth0'': context PREROUTING mangle ipv4optsstrip -i eth0 == Target keyword: tochain == '''''tochain <customchain> [log [msg <message>]] <matches>'''''<br> If you've created a custom chain within a certain table, then you can jump to this custom chain using ''tochain'', as long as the ''tochain'' invocation appears in a context with the same table. For example: create_chain FTPtraffic filter (...) context INPUT filter (...) tochain FTPtraffic -p tcp --dport 20 In this example, any TCP packet that appears in table filter, chain INPUT and is directed at port 20, is sent on through to the previously created chain FTPTRAFFIC (keep in mind that Iceditch will always translate any chain name to all uppercase). Rule matching and packet processing will continue in that chain, until an ACCEPT or DROP is encountered, or a RETURN, or all rules in the custom chain have been exhausted. After that, the implicit return policy on your custom chain will return the packet to whence it came (context INPUT filter, the line below the ''tochain'' invocation). == Target keyword: log == ''for LOG target: '''log [(msg|message) <message>] [ip-options|ipopt] [(lvl|level) <loglevel>] [tcp-options|tcpopt] [tcp-sequence|tcpseq] <matches>'''''<br> ''for ULOG target: '''log [(msg|message) <message>] [cprange <range>] [qtreshold|qtresh <treshold>] <matches>''''' Sometimes, the standard ''log'' parameter is just not enough. This can be the case when you want to log a packet with one or more of the extra options beside ''--log-prefix''. Or maybe you want to just log a certain type or class of packets, without performing an action on those packets just yet, so that you can't use ''log'' as a parameter to one of the other Iceditch keywords.<br> For this reason, AND for flexibility and clarity, Iceditch has the dedicated target keyword ''log''.<br> Just as when you use the ''log'' '''parameter''' after another target keyword, the use of the log '''target''' will make Iceditch call upon the logging daemon specified in the Iceditch [[Iceditch file structure | config file]]. Standard this is LOG, but optionally you could specify ULOG in the config file. Note that an explicit call on target keyword ''log'' gives one the option to specify extra parameters, but also note that the choice of which parameters you can use depends on your configured choice of logging daemon. === The message to log === Now the message that gets logged is treated the same by Iceditch, no matter which logging daemon you use. Somewhere after the target keyword ''log'' (but before any of the <''matches''>) you specify ''msg <message>'' (or ''message <message>''). The ''<message>'' can be any string between 1 and some 29 characters max (letters, numbers and underscores; no spaces, not empty). If you do NOT specify a message, Iceditch will always create a default log message: ''<chain>_&lt;table&gt;_log''. This means that <pre>context INPUT filter log -p tcp --dport 22 </pre> will result in either one of the iptables lines shown below, depending on your choice of logging daemon: <pre>iptables -A INPUT -t filter -p tcp --dport 22 --jump LOG --log-prefix INPUT_filter_log --log-level 4 iptables -A INPUT -t filter -p tcp --dport 22 --jump ULOG --ulog-prefix INPUT_filter_log </pre> (note the default log level when using the ''syslog'' logging daemon). === Log parameters when using the ''syslog'' logging daemon=== Besides a log message, there are four more options that you can also specify. All five options are shown in the table below: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" ! colspan="3" style="background:#ffdead;"|LOG options |- !style="background:#ffdead;"|Iceditch option !style="background:#ffdead;"|IPtables option !style="background:#ffdead;"|Description |- |ip-options / ipopt | --log-ip-options |Makes Netfilter include the IP options in the log entry |- | lvl / level <''loglevel''> | --log-level <''loglevel''> | Makes Netfilter log with the specified <''loglevel''> |- | msg / message <''logmessage''> | --log-prefix <''logmessage''> | Makes Netfilter prepend <''logmessage''> to the log entry |- | tcp-options / tcpopt | --log-tcp-options |Makes Netfilter include the TCP options in the log entry |- | tcp-sequence / tcpseq | --log-tcp-sequence |Makes Netfilter include the TCP sequence number in the log entry |- |} On the log-level: when using the ''syslog'' daemon (IPtables target LOG), it is possible to specify a log level. The log level can be specified numerically or by name; Iceditch will translate it to its numerical value. However, if you do NOT specify a log level, Iceditch will include a default log level, being 4 (warn). For completeness, we here reproduce the list of logging levels that ''log'' understands: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Level !style="background:#ffdead;"|Description |- |0 |''emerg'' or ''panic'' |- |1 |''alert'' |- |2 |''crit'' |- |3 |''err'' |- |4 |''warn'' (default) |- |5 |''notice'' |- |6 |''info'' |- |7 |''debug'' |- |} === Log parameters when using the ''ulog'' user space logging daemon=== {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" ! colspan="3" style="background:#ffdead;"|ULOG options |- !style="background:#ffdead;"|Iceditch option !style="background:#ffdead;"|IPtables option !style="background:#ffdead;"|Description |- | cprange <''size''> | --ulog-cprange <''size''> |log the first ''size'' bytes of each packet |- | msg / message <''logmessage''> | --log-prefix <''logmessage''> | Makes Netfilter prepend <''logmessage''> to the log entry |- | qtreshold / qtresh <''value''> | --ulog-qthreshold <''value''> |Queue ''value'' packets before sending them to ''ulogd'' (default = 1, max = 50) |- |} <br> Now an example: context "INPUT" "filter" log lvl info msg SSH_incoming -p tcp --dport 22 -i $inetIF Iceditch works this out into iptables -A INPUT -t filter -p tcp --dport 22 -i $inetIF --jump ULOG --ulog-prefix "SSH_incoming" --log-level 6 == Target keyword: mark == '''''mark <markval> [log [msg <message>]] <matches>'''''<br> If a packet matches the <matches>, then it will be marked with the <markval> specified. An example from the context PREROUTING mangle: mark 2 –p tcp --dport 22 Iceditch works this out to iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump MARK --setmark 2 Should you want to also log the packet, you’d use mark 2 log –p tcp --dport 22 Iceditch works this out to iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump LOG \ --log-prefix mark_PREROUTING_mangle: iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump MARK --setmark 2 Because of how iptables handles the MARK target, you can only use it in contexts where the table is ''mangle''. == Target keyword: masquerade == '''''masquerade <iface> [to <p1[-p2]>] [log [msg <message>]] <matches>'''''<br> <iface> is the (outward facing) network interface that we want to masquerade on.<br> The MASQUERADE target is used basically the same as the SNAT target, but it does not require any ''--to-source'' option. The reason for this is that the MASQUERADE target was made to work with connections which get dynamic IP addresses when connecting to the network in question, for example dial-up connections, or DHCP connections. This means that you should only use the MASQUERADE target with dynamically assigned IP connections, which we don't know the actual IP address of in advance. If you have a static IP connection, you should instead use the SNAT target.<br> When you masquerade a connection, it means that we set the IP address used on a specific network ''interface'', instead of getting it from the ''--to-source option''. The necessary IP address is automatically grabbed from the information about the specific interface. Using the ''masquerade'' keyword also has the advantage that connections are forgotten when an interface goes down, which is extremely good if we, for example, kill a specific interface. If we would have used the SNAT target, we may have been left with a lot of old connection tracking data, which would be kept in connection tracking memory for days. forgetting about connections is, in general, the correct behavior when dealing with dial-up lines that are probably assigned a different IP every time they are brought up. In case we are assigned a different IP, the connection is lost anyways, and it is more or less idiotic to keep the entry around.<br> It is still possible to use the MASQUERADE target instead of SNAT even though you do have a static IP; however, it is not favorable since it will add extra overhead, and there may be inconsistencies in the future which will thwart your existing scripts and render them "unusable".<br> Note that the MASQUERADE target is only valid within the POSTROUTING chain in the nat table, just as the SNAT target. == Target keyword: redirect == '''''redirect [to <to-ports>] [log [msg <message>]] <matches>'''''<br> If a packet matches the <matches>, then it will be redirected to the local machine, by setting the destination IP to a fitting IP address of the local machine (i.e. 127.0.0.1, or the first-bound IP address of the interface over which it came in. Additionally, by specifying “to <to-ports>” you can have the destination ports redirected to a port or portrange. <to-ports> can either be a port number (e.g. 8080) or a port range (e.g. 6661-6669; the latter is inclusive). Example for a transparent HTTP proxy: context "OUTPUT" "nat" redirect to 8080 –p tcp --dport 80 Iceditch works this out to iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump REDIRECT –to-ports 8080 Should you want to log the packet, you could use redirect to 8080 log –p tcp --dport 80 Iceditch works this out to iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump LOG \ --log-prefix OUTPUT_REDIRECT_to_8080: iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump REDIRECT –-to-ports 8080 Because of how iptables handles the REDIRECT target, you can only use it in contexts where the table is "nat" and the chain is PREROUTING or OUTPUT. == Target keyword: reject == '''''reject [with <type>] [log [msg <message>]] <matches>'''''<br> In essence, this does the same as the "drop" target keyword, only it jumps to REJECT instead of DROP. This means the packet is discarded (just as with DROP), but the sender is notified using ICMP (by default, your machine will send an ICMP-packet of type "icmp-port-unreachable"). Because of how iptables handles the REJECT target, you can only use it in contexts where the table is "filter". Optionally, you can follow "reject" with the keyword "with", and then use one of the following rejection types: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Type !style="background:#ffdead;"|Description |- | icmp-host-prohibited | will send an ICMP-message "host prohibited" |- | icmp-host-unreachable | will send an ICMP-message "host unreachable" |- | icmp-net-prohibited | will send an ICMP-message "net prohibited" |- | icmp-net-unreachable | will send an ICMP-message "net unreachable" |- | icmp-port-unreachable | DEFAULT; will send an ICMP-message "port unreachable" |- | icmp-proto-unreachable | DEFAULT; will send an ICMP-message "protocol unreachable" |- | tcp-reset | will send a TCP reset, a packet with the RST flag set (as a response to a TCP packet only) |- | host-prohib | synonymous to icmp-host-prohibited |- | host-unreach | synonymous to icmp-host-unreachable |- | net-prohib | synonymous to icmp-net-prohibited |- | net-unreach | synonymous to icmp-net-unreachable |- | port-unreach | synonymous to icmp-port-unreachable |- | proto-unreach | synonymous to icmp-proto-unreachable |- |} If you don’t specify "with <type>", then netfilter will assume icmp-port-unreachable. Thus, should you want to reject a packet in context filter INPUT (and log it) with reason net-prohib, you’d use reject with net-prohib log –p tcp –i eth0 --dport 22 Iceditch works this out to iptables –t filter –A INPUT –p tcp –i eth0 –-dport 22 –-jump LOG \ --log-prefix INPUT_REJECT_with_net-prohib: iptables –t filter –A INPUT –p tcp –i eth0 –-dport 22 \ –-jump REJECT –-reject-with net-prohib –p tcp –i eth0 –-dport 22 ==Target keyword: route== '''''route {<iface>|<ifaceindex>} [log [msg <message>]] <matches>'''''<br> The ''route'' target lets you route a received packet through an interface or towards a host, even if the regular destination of the packet is the router itself. The ROUTE target is also able to change the incoming interface of a packet. Packets are directly put on the wire and do not traverse any other table.<br> ''route'' takes one mandatory option, which may be either the interface name over which to route the packet that matches the <matches>, or the index number of that interface (based on the order in /proc/net/dev). Iceditch is pretty lazy in how to interpret that option: if it's all numerals, Iceditch treats it as the interface index number, if it contains any other character, it is considered the interface name (e.g. ''eth0''); and no sanity check is performed on the specified <iface|ifaceindex>. == Target keyword: same== '''''same [to <a1[-a2]> [to <a3[-a4]>] ] [nodest] [log [msg <message>] ] <matches>'''''<br> ''same'' only works in the nat table, in the POSTROUTING chain. It is very closely related to ''snat'' (see below), because it does virtually the same thing. Basically, the ''same'' target will try to always use the same outgoing IP address for all connections initiated by a single host on your network. For example, say you have one "internal" /24 network (192.168.1.0) and 3 "external" IP addresses (10.5.6.11-13) on your firewall/router machine. Now, if internal machine 192.168.1.20 went out through the .11 address the first time, then the firewall will try to keep that machine always going out through that same IP address. So basically ''same'' might be a better fit than ''snat'' if you have multiple external IP addresses.<br> However, there is also functionality lacking in ''same'' that ''snat'' has, namely the specification of (TCP and UDP) ports or port ranges to use for the NATting operation. See ''snat'' for its port possibilities.<br> Furthermore, ''same'' has an extra option that ''snat'' does not have: under normal action, the ''same'' target is calculating the followup connections based on both destination and source IP addresses. Using the ''nodest'' option (which corresponds with --nodst in the actual IPtables command), it uses only the source IP address to find out which outgoing IP the NAT function should use for the specific connection. Without this argument, it uses a combination of the destination and source IP address. == Target keyword: snat== '''''snat [to <a1[-a2][:p1-p2]]> [to <a3[-a4][:p3-p4]]>] ] [log [msg <message>] ] <matches>'''''<br> This keyword is only valid in the chain POSTROUTING, table nat. And ofcourse, source NATting does you little good if you haven't enabled forwarding (e.g. use this machine as a router for other machines on your network).<br> Calling snat with the right parameters will create a Source NATting rule for you, whereby a packet matching the <matches> will be source NATted using the source IP address ''a1'' (or the range ''a1-a2''). Ofcourse, ''a1[-a2]'' should be valid IP address(es) of the firewalling machine.<br> Furthermore, if a port range ''p1-p2'' is specified, then you'll limit the range of ports that ''snat'' will use outbound (only valid for TCP or UDP packets).<br> Finally, it is possible to specify ''multiple'' IP address ranges and port ranges, using multiple ''to <a1[-a2][:p1-p2]]'' declarations in succession.<br> An example would be: context "POSTROUTING" "nat" snat to $inetIP -o $inetIF ! --src $inetIP If the variable ''$inetIP'' contains your public IP (e.g. 212.238.151.72), and ''$inetIF'' your interface connected to the Internet (e.g. ''eth0''), then this rule would expand to iptables -A POSTROUTING -t nat -o eth0 ! --src 212.238.151.72 -j SNAT --to-source 212.238.151.72 This would cause Iceditch to source NAT any outbound packet that is NOT sent by your firewall itself; in effect your server is now a nice fullblown NAT router for all machines on your private network. 2a5ddbbce12e80f7052b1f330d0a3663bc1db2df 1619 1617 2008-08-14T17:23:15Z Saruman! 2 /* Target keyword: nojump */ started wikitext text/x-wiki == Parameter: log == ''target '''log [(msg|message) <message>]''' <matches>''<br> After most keywords, a "log" parameter can be added (see below). If the "log" parameter is followed by "msg" (or "message"), then the parameter following "msg" is read and used as log-prefix. The parameter is not allowed to have whitespace (that limitation is Iceditch-specific, not IPtables-related), and the maximum length of the log-prefix is determined by your version of netfilter/IPtables and your choice of IPtables logging utility (syslogemu or ulog); this limit is usually some 29 characters. Note that Iceditch does not perform any sanity checks on the message. Thus a packet matching the <matches> part of the rule will be logged with the default setting of the "log" target. If the "log" parameter is ''not'' followed by "msg", then the packet will be logged with a default log message, being "&lt;table&gt;_<chain>_<target>" and all the other default setting of the "log" target. Thus, should you want to log a packet with more control over the logging parameters, then you need an extra line, beginning with the ''target keyword'' "log", instead of just following the target keyword with parameter ''log''. For more information, see the [[Iceditch_Command_Reference#Target_keyword:_log | target keyword "log"]] below. == Context keyword: context == '''''context <chain> &lt;table&gt;'''''<br> Every IPtables rule is written to a chain in a table; with Iceditch, you don't have to specify the chain and table in every line. Just precede the lines with the ''context'' statement. Example: context POSTROUTING nat Notes: the order of chain and table does not matter; ''context nat POSTROUTING'' works just as well. Furthermore, <chain> and &lt;table&gt; have been made case-insensitive; whatever you specify as chain will be translated to uppercase, whatever you specify as table will be translated to lowercase. This gives you the possibility to write the context as you like to read it, e.g. ''context Postrouting Nat''; after processing this, Iceditch will have two variables $CHAIN="POSTROUTING" and $TABLE="nat" that it will use in every following command. For example: context "Input" "fIlTeR" accept -p tcp --dport 22 will result in the following IPtables call: iptables -A INPUT -t filter -p tcp --dport 22 --jump ACCEPT If you do NOT specify a [[Iceditch IPtables language | valid combination]] of chain and table, the execution of Iceditch will halt with a fatal error. It is allowed (but not recommended) to call ''context'' multiple times for the same combination of chain and table; the order in which the rules are added to that chain in that table, is the same in which they appear in your rulefile, top to bottom. This is not recommended, because we feel it decreases readability, and thus maintainability, of the rules file. But hey, it's going to be ''your'' rulefile anyway...<br> Note: you cannot create custom chains by the names of mangle, nat or filter, since Iceditch will always interpret these names as those of tables. == Context keyword: create_chain == '''''create_chain <chain> [&lt;table&gt;]'''''<br> This command creates a new chain named <chain>, in the specified table &lt;table&gt;. If no table is specified, then the ''filter'' table is assumed. Just as with the ''context'' command, the <chain> name you specify will be translated to all uppercase.<br> The name for your new chain must be unique, although just like the built-in chains, you can specify the same name in different tables. If you create "fun-filter" in table ''filter'', and then create a "fun-filter" in table ''nat'', then you actually have two different chains. But remember: since Iceditch translates every chain name to uppercase, you can't create "Fun-filter" AND "fun-FILTER" in the same table - they're the same chain.<br> NOTE: after you've run ''create_chain'', you still have to switch context to create rules in the new chain! example:<br> create_chain fun-filter context fun-filter filter accept -p tcp --dport 22 This will result in iptables -N FUN-FILTER -t filter iptables -A FUN-FILTER -t filter -p tcp --dport 22 --jump ACCEPT == Target keyword: accept == '''''accept [log [msg <message>]] <matches>'''''<br> If a network packet fits the <matches>, then it will be accepted (passed) through the table/chain defined in the context where you put the accept rule. Example: context Input Filter accept –p tcp --dport 22 Iceditch works this out to iptables –t filter –A INPUT –p tcp –-dport 22 –-jump ACCEPT Should you want to log the packet, you’d use context Input Filter accept log –p tcp --dport 22 Iceditch works this out to iptables –t filter –A INPUT –p tcp –-dport 22 \ –-jump LOG --log-prefix accept_INPUT_filter iptables –t filter –A INPUT –p tcp –-dport 22 –-jump ACCEPT Note: the ACCEPT target is valid in any user-manipulable table/chain combination == Target keyword: classify == '''''classify <classval> [log [msg <message>]] <matches>'''''<br> If a packet travelling through the mangle table in the POSTROUTING chain matches the <matches>, then it will be classified with the <classval> specified. An example: classify 2:11 –p tcp --dport 22 The script works this out to iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump CLASSIFY --setclass 2:11 Should you want to also log the packet, you’d use classify 2:11 log msg classified_2:11 –p tcp --dport 22 The script works this out to iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump LOG \ --log-prefix classified_2:11: iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump CLASSIFY \ --setclass 2:11 Should you not give a msg, then the log-prefix becomes classify_POSTROUTING_mangle. Because of how iptables handles the CLASSIFY target, you can only use it in contexts where the chain is "POSTROUTING" and the table is "mangle". == Target keyword: dnat == '''''dnat [to] <a1[-a2][:p1[-p2]]> [log [msg <message>]] <matches>'''''<br> In the above, a1 and a2 are used to specify a (range of) IP address(es); for TCP and UDP protocols, a destination port or port range can be provided. Note that the "to" in the command is optional, and serves only readability.<br> If a packet matches the qualifiers, then it will be destination-NATted to the provided IP address or address range. For example, if you want to DNAT port 81 on your external interface eth1 to an internal webserver on 10.0.0.1, you could use context "PREROUTING" "nat" dnat to 10.0.0.1:80 –p tcp –i eth1 –-dport 81 If you give a range of IP addresses, then the DNAT logic of IPtables will randomly pick an address and DNAT the packet there. However, note that a single stream will always use the same IP address from that range, and that each stream will randomly be given an IP address that it will always be destined for, within that stream.<br> Furthermore, note that the DNAT target is only available within the PREROUTING and OUTPUT chains in the nat table, and any of the chains called upon from any of those listed chains. Note that chains containing DNAT targets may not be used from any other chains, such as the POSTROUTING chain. However, the bad news is that Iceditch currently does not know how to check for the latter case, so the dnat keyword only works from contexts "PREROUTING" "nat" and "OUTPUT" "nat". == Target keyword: drop == '''''drop [log [msg <message>]] <matches> '''''<br> In essence, this does the same as the "accept" target keyword, only it jumps to DROP instead of ACCEPT. Thus any packet matching the <matches> gets discarded; it will not get sent on to its final destination (or next hop), it will not get processed by any other firewall rule, and the sender of the packet is unaware of your treatment of his packet. Should you want to also log the packet, you’d use context "FORWARD" "filter" drop log –p tcp -s 10.0.0.0/16 The script works this out to iptables –t filter –A FORWARD –p tcp -s 10.0.0.0/16 –-jump LOG \ --log-prefix drop_FORWARD_filter: iptables –t filter –A FORWARD –p tcp -s 10.0.0.0/16 –-jump DROP However, be advised that using DROP may leave dead sockets on either the sending or receiving host. If you do not wish that, you might be better of using REJECT. On the other hand, dropping packets is a nice way of appearing like a black hole, so it's the weapon of choice against port scanners and the likes.<br> The DROP target can be used in any chain in any table. == Target keyword: ipv4optsstrip == '''''ipv4optsstrip [log [msg <message>]] <matches>'''''<br> This target takes any packet that fits the <matches>, and then strips off all IPv4 options from its header. It can only be used in the ''mangle'' table. For example, the following rule strips the IPv4 options from any packet incoming on ''eth0'': context PREROUTING mangle ipv4optsstrip -i eth0 == Target keyword: tochain == '''''tochain <customchain> [log [msg <message>]] <matches>'''''<br> If you've created a custom chain within a certain table, then you can jump to this custom chain using ''tochain'', as long as the ''tochain'' invocation appears in a context with the same table. For example: create_chain FTPtraffic filter (...) context INPUT filter (...) tochain FTPtraffic -p tcp --dport 20 In this example, any TCP packet that appears in table filter, chain INPUT and is directed at port 20, is sent on through to the previously created chain FTPTRAFFIC (keep in mind that Iceditch will always translate any chain name to all uppercase). Rule matching and packet processing will continue in that chain, until an ACCEPT or DROP is encountered, or a RETURN, or all rules in the custom chain have been exhausted. After that, the implicit return policy on your custom chain will return the packet to whence it came (context INPUT filter, the line below the ''tochain'' invocation). == Target keyword: log == ''for LOG target: '''log [(msg|message) <message>] [ip-options|ipopt] [(lvl|level) <loglevel>] [tcp-options|tcpopt] [tcp-sequence|tcpseq] <matches>'''''<br> ''for ULOG target: '''log [(msg|message) <message>] [cprange <range>] [qtreshold|qtresh <treshold>] <matches>''''' Sometimes, the standard ''log'' parameter is just not enough. This can be the case when you want to log a packet with one or more of the extra options beside ''--log-prefix''. Or maybe you want to just log a certain type or class of packets, without performing an action on those packets just yet, so that you can't use ''log'' as a parameter to one of the other Iceditch keywords.<br> For this reason, AND for flexibility and clarity, Iceditch has the dedicated target keyword ''log''.<br> Just as when you use the ''log'' '''parameter''' after another target keyword, the use of the log '''target''' will make Iceditch call upon the logging daemon specified in the Iceditch [[Iceditch file structure | config file]]. Standard this is LOG, but optionally you could specify ULOG in the config file. Note that an explicit call on target keyword ''log'' gives one the option to specify extra parameters, but also note that the choice of which parameters you can use depends on your configured choice of logging daemon. === The message to log === Now the message that gets logged is treated the same by Iceditch, no matter which logging daemon you use. Somewhere after the target keyword ''log'' (but before any of the <''matches''>) you specify ''msg <message>'' (or ''message <message>''). The ''<message>'' can be any string between 1 and some 29 characters max (letters, numbers and underscores; no spaces, not empty). If you do NOT specify a message, Iceditch will always create a default log message: ''<chain>_&lt;table&gt;_log''. This means that <pre>context INPUT filter log -p tcp --dport 22 </pre> will result in either one of the iptables lines shown below, depending on your choice of logging daemon: <pre>iptables -A INPUT -t filter -p tcp --dport 22 --jump LOG --log-prefix INPUT_filter_log --log-level 4 iptables -A INPUT -t filter -p tcp --dport 22 --jump ULOG --ulog-prefix INPUT_filter_log </pre> (note the default log level when using the ''syslog'' logging daemon). === Log parameters when using the ''syslog'' logging daemon=== Besides a log message, there are four more options that you can also specify. All five options are shown in the table below: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" ! colspan="3" style="background:#ffdead;"|LOG options |- !style="background:#ffdead;"|Iceditch option !style="background:#ffdead;"|IPtables option !style="background:#ffdead;"|Description |- |ip-options / ipopt | --log-ip-options |Makes Netfilter include the IP options in the log entry |- | lvl / level <''loglevel''> | --log-level <''loglevel''> | Makes Netfilter log with the specified <''loglevel''> |- | msg / message <''logmessage''> | --log-prefix <''logmessage''> | Makes Netfilter prepend <''logmessage''> to the log entry |- | tcp-options / tcpopt | --log-tcp-options |Makes Netfilter include the TCP options in the log entry |- | tcp-sequence / tcpseq | --log-tcp-sequence |Makes Netfilter include the TCP sequence number in the log entry |- |} On the log-level: when using the ''syslog'' daemon (IPtables target LOG), it is possible to specify a log level. The log level can be specified numerically or by name; Iceditch will translate it to its numerical value. However, if you do NOT specify a log level, Iceditch will include a default log level, being 4 (warn). For completeness, we here reproduce the list of logging levels that ''log'' understands: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Level !style="background:#ffdead;"|Description |- |0 |''emerg'' or ''panic'' |- |1 |''alert'' |- |2 |''crit'' |- |3 |''err'' |- |4 |''warn'' (default) |- |5 |''notice'' |- |6 |''info'' |- |7 |''debug'' |- |} === Log parameters when using the ''ulog'' user space logging daemon=== {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" ! colspan="3" style="background:#ffdead;"|ULOG options |- !style="background:#ffdead;"|Iceditch option !style="background:#ffdead;"|IPtables option !style="background:#ffdead;"|Description |- | cprange <''size''> | --ulog-cprange <''size''> |log the first ''size'' bytes of each packet |- | msg / message <''logmessage''> | --log-prefix <''logmessage''> | Makes Netfilter prepend <''logmessage''> to the log entry |- | qtreshold / qtresh <''value''> | --ulog-qthreshold <''value''> |Queue ''value'' packets before sending them to ''ulogd'' (default = 1, max = 50) |- |} <br> Now an example: context "INPUT" "filter" log lvl info msg SSH_incoming -p tcp --dport 22 -i $inetIF Iceditch works this out into iptables -A INPUT -t filter -p tcp --dport 22 -i $inetIF --jump ULOG --ulog-prefix "SSH_incoming" --log-level 6 == Target keyword: mark == '''''mark <markval> [log [msg <message>]] <matches>'''''<br> If a packet matches the <matches>, then it will be marked with the <markval> specified. An example from the context PREROUTING mangle: mark 2 –p tcp --dport 22 Iceditch works this out to iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump MARK --setmark 2 Should you want to also log the packet, you’d use mark 2 log –p tcp --dport 22 Iceditch works this out to iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump LOG \ --log-prefix mark_PREROUTING_mangle: iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump MARK --setmark 2 Because of how iptables handles the MARK target, you can only use it in contexts where the table is ''mangle''. == Target keyword: masquerade == '''''masquerade <iface> [to <p1[-p2]>] [log [msg <message>]] <matches>'''''<br> <iface> is the (outward facing) network interface that we want to masquerade on.<br> The MASQUERADE target is used basically the same as the SNAT target, but it does not require any ''--to-source'' option. The reason for this is that the MASQUERADE target was made to work with connections which get dynamic IP addresses when connecting to the network in question, for example dial-up connections, or DHCP connections. This means that you should only use the MASQUERADE target with dynamically assigned IP connections, which we don't know the actual IP address of in advance. If you have a static IP connection, you should instead use the SNAT target.<br> When you masquerade a connection, it means that we set the IP address used on a specific network ''interface'', instead of getting it from the ''--to-source option''. The necessary IP address is automatically grabbed from the information about the specific interface. Using the ''masquerade'' keyword also has the advantage that connections are forgotten when an interface goes down, which is extremely good if we, for example, kill a specific interface. If we would have used the SNAT target, we may have been left with a lot of old connection tracking data, which would be kept in connection tracking memory for days. forgetting about connections is, in general, the correct behavior when dealing with dial-up lines that are probably assigned a different IP every time they are brought up. In case we are assigned a different IP, the connection is lost anyways, and it is more or less idiotic to keep the entry around.<br> It is still possible to use the MASQUERADE target instead of SNAT even though you do have a static IP; however, it is not favorable since it will add extra overhead, and there may be inconsistencies in the future which will thwart your existing scripts and render them "unusable".<br> Note that the MASQUERADE target is only valid within the POSTROUTING chain in the nat table, just as the SNAT target. == Target keyword: nojump == '''''nojump [log [msg <message>]] <matches>'''''<br> ''nojump'' creates an iptables rule with an empty jump target. This means that the match is made, but no action is undertaken on the match. OK, so why do we even ''need'' a "nojump" target if it doesn't create an IPtables jump? As far as we know, two valid reasons might be:<br> === using nojump for auditing === A ''nojump'' rule can be used for '''auditing'''. Say you want to know how often you are pinged from IP 1.2.3.4 - without logging each and every ping request to the firewall logfile. You could write context INPUT filter nojump -p icmp --icmp-type 8 -s 1.2.3.4</pre> This rule could be checked in IPtables with ''iptables -n -L'' as <pre> Chain INPUT (policy DROP 1713K packets, 119M bytes) pkts bytes target prot opt in out source destination 0 0 icmp -- * * 1.2.3.4 0.0.0.0/0 icmp type 8</pre> Good to know you haven't been pinged by 1.2.3.4 yet, eh?!<br> === using nojump to apply matches without using targets === A ''nojump'' rule can be used to '''apply matches''' like ''recent'', that may just happily act on their own. Say you want to block spurious SSH login attempts; if "spurious" to you means "more than two connection attempts per minute", then you could try: context INPUT filter nojump -p tcp --dport 22 -i $inetIF -m state --state NEW -m recent --name SSHers --set drop -p tcp --dport 22 -i $inetIF -m state --state NEW -m recent --name SSHers --update --seconds 60 --hitcount 3 This causes Iceditch to add the IP of every connection attempt to your SSH port to a list named "SSHers", and consecutively, that every packet that fits this description AND has seen two more hits from the same source address in the last 60 seconds gets dropped. Essentially, this limits brute-force attackers on your SSH to trying 2 logins per minute at most. But you see that the nojump rule gets translated to iptables -A INPUT -t filter -p tcp --dport 22 -i $inetIF -m state --state NEW -m recent --name SSHers --set No ''--jump'' in that line - hence the name of the Iceditch target: ''nojump''. == Target keyword: redirect == '''''redirect [to <to-ports>] [log [msg <message>]] <matches>'''''<br> If a packet matches the <matches>, then it will be redirected to the local machine, by setting the destination IP to a fitting IP address of the local machine (i.e. 127.0.0.1, or the first-bound IP address of the interface over which it came in. Additionally, by specifying “to <to-ports>” you can have the destination ports redirected to a port or portrange. <to-ports> can either be a port number (e.g. 8080) or a port range (e.g. 6661-6669; the latter is inclusive). Example for a transparent HTTP proxy: context "OUTPUT" "nat" redirect to 8080 –p tcp --dport 80 Iceditch works this out to iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump REDIRECT –to-ports 8080 Should you want to log the packet, you could use redirect to 8080 log –p tcp --dport 80 Iceditch works this out to iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump LOG \ --log-prefix OUTPUT_REDIRECT_to_8080: iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump REDIRECT –-to-ports 8080 Because of how iptables handles the REDIRECT target, you can only use it in contexts where the table is "nat" and the chain is PREROUTING or OUTPUT. == Target keyword: reject == '''''reject [with <type>] [log [msg <message>]] <matches>'''''<br> In essence, this does the same as the "drop" target keyword, only it jumps to REJECT instead of DROP. This means the packet is discarded (just as with DROP), but the sender is notified using ICMP (by default, your machine will send an ICMP-packet of type "icmp-port-unreachable"). Because of how iptables handles the REJECT target, you can only use it in contexts where the table is "filter". Optionally, you can follow "reject" with the keyword "with", and then use one of the following rejection types: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Type !style="background:#ffdead;"|Description |- | icmp-host-prohibited | will send an ICMP-message "host prohibited" |- | icmp-host-unreachable | will send an ICMP-message "host unreachable" |- | icmp-net-prohibited | will send an ICMP-message "net prohibited" |- | icmp-net-unreachable | will send an ICMP-message "net unreachable" |- | icmp-port-unreachable | DEFAULT; will send an ICMP-message "port unreachable" |- | icmp-proto-unreachable | DEFAULT; will send an ICMP-message "protocol unreachable" |- | tcp-reset | will send a TCP reset, a packet with the RST flag set (as a response to a TCP packet only) |- | host-prohib | synonymous to icmp-host-prohibited |- | host-unreach | synonymous to icmp-host-unreachable |- | net-prohib | synonymous to icmp-net-prohibited |- | net-unreach | synonymous to icmp-net-unreachable |- | port-unreach | synonymous to icmp-port-unreachable |- | proto-unreach | synonymous to icmp-proto-unreachable |- |} If you don’t specify "with <type>", then netfilter will assume icmp-port-unreachable. Thus, should you want to reject a packet in context filter INPUT (and log it) with reason net-prohib, you’d use reject with net-prohib log –p tcp –i eth0 --dport 22 Iceditch works this out to iptables –t filter –A INPUT –p tcp –i eth0 –-dport 22 –-jump LOG \ --log-prefix INPUT_REJECT_with_net-prohib: iptables –t filter –A INPUT –p tcp –i eth0 –-dport 22 \ –-jump REJECT –-reject-with net-prohib –p tcp –i eth0 –-dport 22 ==Target keyword: route== '''''route {<iface>|<ifaceindex>} [log [msg <message>]] <matches>'''''<br> The ''route'' target lets you route a received packet through an interface or towards a host, even if the regular destination of the packet is the router itself. The ROUTE target is also able to change the incoming interface of a packet. Packets are directly put on the wire and do not traverse any other table.<br> ''route'' takes one mandatory option, which may be either the interface name over which to route the packet that matches the <matches>, or the index number of that interface (based on the order in /proc/net/dev). Iceditch is pretty lazy in how to interpret that option: if it's all numerals, Iceditch treats it as the interface index number, if it contains any other character, it is considered the interface name (e.g. ''eth0''); and no sanity check is performed on the specified <iface|ifaceindex>. == Target keyword: same== '''''same [to <a1[-a2]> [to <a3[-a4]>] ] [nodest] [log [msg <message>] ] <matches>'''''<br> ''same'' only works in the nat table, in the POSTROUTING chain. It is very closely related to ''snat'' (see below), because it does virtually the same thing. Basically, the ''same'' target will try to always use the same outgoing IP address for all connections initiated by a single host on your network. For example, say you have one "internal" /24 network (192.168.1.0) and 3 "external" IP addresses (10.5.6.11-13) on your firewall/router machine. Now, if internal machine 192.168.1.20 went out through the .11 address the first time, then the firewall will try to keep that machine always going out through that same IP address. So basically ''same'' might be a better fit than ''snat'' if you have multiple external IP addresses.<br> However, there is also functionality lacking in ''same'' that ''snat'' has, namely the specification of (TCP and UDP) ports or port ranges to use for the NATting operation. See ''snat'' for its port possibilities.<br> Furthermore, ''same'' has an extra option that ''snat'' does not have: under normal action, the ''same'' target is calculating the followup connections based on both destination and source IP addresses. Using the ''nodest'' option (which corresponds with --nodst in the actual IPtables command), it uses only the source IP address to find out which outgoing IP the NAT function should use for the specific connection. Without this argument, it uses a combination of the destination and source IP address. == Target keyword: snat== '''''snat [to <a1[-a2][:p1-p2]]> [to <a3[-a4][:p3-p4]]>] ] [log [msg <message>] ] <matches>'''''<br> This keyword is only valid in the chain POSTROUTING, table nat. And ofcourse, source NATting does you little good if you haven't enabled forwarding (e.g. use this machine as a router for other machines on your network).<br> Calling snat with the right parameters will create a Source NATting rule for you, whereby a packet matching the <matches> will be source NATted using the source IP address ''a1'' (or the range ''a1-a2''). Ofcourse, ''a1[-a2]'' should be valid IP address(es) of the firewalling machine.<br> Furthermore, if a port range ''p1-p2'' is specified, then you'll limit the range of ports that ''snat'' will use outbound (only valid for TCP or UDP packets).<br> Finally, it is possible to specify ''multiple'' IP address ranges and port ranges, using multiple ''to <a1[-a2][:p1-p2]]'' declarations in succession.<br> An example would be: context "POSTROUTING" "nat" snat to $inetIP -o $inetIF ! --src $inetIP If the variable ''$inetIP'' contains your public IP (e.g. 212.238.151.72), and ''$inetIF'' your interface connected to the Internet (e.g. ''eth0''), then this rule would expand to iptables -A POSTROUTING -t nat -o eth0 ! --src 212.238.151.72 -j SNAT --to-source 212.238.151.72 This would cause Iceditch to source NAT any outbound packet that is NOT sent by your firewall itself; in effect your server is now a nice fullblown NAT router for all machines on your private network. 9b44ebc34b800a8d16bcdc53c29163420196de94 1620 1619 2008-08-15T05:53:25Z Saruman! 2 /* Target keyword: reject */ added RFC behaviour wikitext text/x-wiki == Parameter: log == ''target '''log [(msg|message) <message>]''' <matches>''<br> After most keywords, a "log" parameter can be added (see below). If the "log" parameter is followed by "msg" (or "message"), then the parameter following "msg" is read and used as log-prefix. The parameter is not allowed to have whitespace (that limitation is Iceditch-specific, not IPtables-related), and the maximum length of the log-prefix is determined by your version of netfilter/IPtables and your choice of IPtables logging utility (syslogemu or ulog); this limit is usually some 29 characters. Note that Iceditch does not perform any sanity checks on the message. Thus a packet matching the <matches> part of the rule will be logged with the default setting of the "log" target. If the "log" parameter is ''not'' followed by "msg", then the packet will be logged with a default log message, being "&lt;table&gt;_<chain>_<target>" and all the other default setting of the "log" target. Thus, should you want to log a packet with more control over the logging parameters, then you need an extra line, beginning with the ''target keyword'' "log", instead of just following the target keyword with parameter ''log''. For more information, see the [[Iceditch_Command_Reference#Target_keyword:_log | target keyword "log"]] below. == Context keyword: context == '''''context <chain> &lt;table&gt;'''''<br> Every IPtables rule is written to a chain in a table; with Iceditch, you don't have to specify the chain and table in every line. Just precede the lines with the ''context'' statement. Example: context POSTROUTING nat Notes: the order of chain and table does not matter; ''context nat POSTROUTING'' works just as well. Furthermore, <chain> and &lt;table&gt; have been made case-insensitive; whatever you specify as chain will be translated to uppercase, whatever you specify as table will be translated to lowercase. This gives you the possibility to write the context as you like to read it, e.g. ''context Postrouting Nat''; after processing this, Iceditch will have two variables $CHAIN="POSTROUTING" and $TABLE="nat" that it will use in every following command. For example: context "Input" "fIlTeR" accept -p tcp --dport 22 will result in the following IPtables call: iptables -A INPUT -t filter -p tcp --dport 22 --jump ACCEPT If you do NOT specify a [[Iceditch IPtables language | valid combination]] of chain and table, the execution of Iceditch will halt with a fatal error. It is allowed (but not recommended) to call ''context'' multiple times for the same combination of chain and table; the order in which the rules are added to that chain in that table, is the same in which they appear in your rulefile, top to bottom. This is not recommended, because we feel it decreases readability, and thus maintainability, of the rules file. But hey, it's going to be ''your'' rulefile anyway...<br> Note: you cannot create custom chains by the names of mangle, nat or filter, since Iceditch will always interpret these names as those of tables. == Context keyword: create_chain == '''''create_chain <chain> [&lt;table&gt;]'''''<br> This command creates a new chain named <chain>, in the specified table &lt;table&gt;. If no table is specified, then the ''filter'' table is assumed. Just as with the ''context'' command, the <chain> name you specify will be translated to all uppercase.<br> The name for your new chain must be unique, although just like the built-in chains, you can specify the same name in different tables. If you create "fun-filter" in table ''filter'', and then create a "fun-filter" in table ''nat'', then you actually have two different chains. But remember: since Iceditch translates every chain name to uppercase, you can't create "Fun-filter" AND "fun-FILTER" in the same table - they're the same chain.<br> NOTE: after you've run ''create_chain'', you still have to switch context to create rules in the new chain! example:<br> create_chain fun-filter context fun-filter filter accept -p tcp --dport 22 This will result in iptables -N FUN-FILTER -t filter iptables -A FUN-FILTER -t filter -p tcp --dport 22 --jump ACCEPT == Target keyword: accept == '''''accept [log [msg <message>]] <matches>'''''<br> If a network packet fits the <matches>, then it will be accepted (passed) through the table/chain defined in the context where you put the accept rule. Example: context Input Filter accept –p tcp --dport 22 Iceditch works this out to iptables –t filter –A INPUT –p tcp –-dport 22 –-jump ACCEPT Should you want to log the packet, you’d use context Input Filter accept log –p tcp --dport 22 Iceditch works this out to iptables –t filter –A INPUT –p tcp –-dport 22 \ –-jump LOG --log-prefix accept_INPUT_filter iptables –t filter –A INPUT –p tcp –-dport 22 –-jump ACCEPT Note: the ACCEPT target is valid in any user-manipulable table/chain combination == Target keyword: classify == '''''classify <classval> [log [msg <message>]] <matches>'''''<br> If a packet travelling through the mangle table in the POSTROUTING chain matches the <matches>, then it will be classified with the <classval> specified. An example: classify 2:11 –p tcp --dport 22 The script works this out to iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump CLASSIFY --setclass 2:11 Should you want to also log the packet, you’d use classify 2:11 log msg classified_2:11 –p tcp --dport 22 The script works this out to iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump LOG \ --log-prefix classified_2:11: iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump CLASSIFY \ --setclass 2:11 Should you not give a msg, then the log-prefix becomes classify_POSTROUTING_mangle. Because of how iptables handles the CLASSIFY target, you can only use it in contexts where the chain is "POSTROUTING" and the table is "mangle". == Target keyword: dnat == '''''dnat [to] <a1[-a2][:p1[-p2]]> [log [msg <message>]] <matches>'''''<br> In the above, a1 and a2 are used to specify a (range of) IP address(es); for TCP and UDP protocols, a destination port or port range can be provided. Note that the "to" in the command is optional, and serves only readability.<br> If a packet matches the qualifiers, then it will be destination-NATted to the provided IP address or address range. For example, if you want to DNAT port 81 on your external interface eth1 to an internal webserver on 10.0.0.1, you could use context "PREROUTING" "nat" dnat to 10.0.0.1:80 –p tcp –i eth1 –-dport 81 If you give a range of IP addresses, then the DNAT logic of IPtables will randomly pick an address and DNAT the packet there. However, note that a single stream will always use the same IP address from that range, and that each stream will randomly be given an IP address that it will always be destined for, within that stream.<br> Furthermore, note that the DNAT target is only available within the PREROUTING and OUTPUT chains in the nat table, and any of the chains called upon from any of those listed chains. Note that chains containing DNAT targets may not be used from any other chains, such as the POSTROUTING chain. However, the bad news is that Iceditch currently does not know how to check for the latter case, so the dnat keyword only works from contexts "PREROUTING" "nat" and "OUTPUT" "nat". == Target keyword: drop == '''''drop [log [msg <message>]] <matches> '''''<br> In essence, this does the same as the "accept" target keyword, only it jumps to DROP instead of ACCEPT. Thus any packet matching the <matches> gets discarded; it will not get sent on to its final destination (or next hop), it will not get processed by any other firewall rule, and the sender of the packet is unaware of your treatment of his packet. Should you want to also log the packet, you’d use context "FORWARD" "filter" drop log –p tcp -s 10.0.0.0/16 The script works this out to iptables –t filter –A FORWARD –p tcp -s 10.0.0.0/16 –-jump LOG \ --log-prefix drop_FORWARD_filter: iptables –t filter –A FORWARD –p tcp -s 10.0.0.0/16 –-jump DROP However, be advised that using DROP may leave dead sockets on either the sending or receiving host. If you do not wish that, you might be better of using REJECT. On the other hand, dropping packets is a nice way of appearing like a black hole, so it's the weapon of choice against port scanners and the likes.<br> The DROP target can be used in any chain in any table. == Target keyword: ipv4optsstrip == '''''ipv4optsstrip [log [msg <message>]] <matches>'''''<br> This target takes any packet that fits the <matches>, and then strips off all IPv4 options from its header. It can only be used in the ''mangle'' table. For example, the following rule strips the IPv4 options from any packet incoming on ''eth0'': context PREROUTING mangle ipv4optsstrip -i eth0 == Target keyword: tochain == '''''tochain <customchain> [log [msg <message>]] <matches>'''''<br> If you've created a custom chain within a certain table, then you can jump to this custom chain using ''tochain'', as long as the ''tochain'' invocation appears in a context with the same table. For example: create_chain FTPtraffic filter (...) context INPUT filter (...) tochain FTPtraffic -p tcp --dport 20 In this example, any TCP packet that appears in table filter, chain INPUT and is directed at port 20, is sent on through to the previously created chain FTPTRAFFIC (keep in mind that Iceditch will always translate any chain name to all uppercase). Rule matching and packet processing will continue in that chain, until an ACCEPT or DROP is encountered, or a RETURN, or all rules in the custom chain have been exhausted. After that, the implicit return policy on your custom chain will return the packet to whence it came (context INPUT filter, the line below the ''tochain'' invocation). == Target keyword: log == ''for LOG target: '''log [(msg|message) <message>] [ip-options|ipopt] [(lvl|level) <loglevel>] [tcp-options|tcpopt] [tcp-sequence|tcpseq] <matches>'''''<br> ''for ULOG target: '''log [(msg|message) <message>] [cprange <range>] [qtreshold|qtresh <treshold>] <matches>''''' Sometimes, the standard ''log'' parameter is just not enough. This can be the case when you want to log a packet with one or more of the extra options beside ''--log-prefix''. Or maybe you want to just log a certain type or class of packets, without performing an action on those packets just yet, so that you can't use ''log'' as a parameter to one of the other Iceditch keywords.<br> For this reason, AND for flexibility and clarity, Iceditch has the dedicated target keyword ''log''.<br> Just as when you use the ''log'' '''parameter''' after another target keyword, the use of the log '''target''' will make Iceditch call upon the logging daemon specified in the Iceditch [[Iceditch file structure | config file]]. Standard this is LOG, but optionally you could specify ULOG in the config file. Note that an explicit call on target keyword ''log'' gives one the option to specify extra parameters, but also note that the choice of which parameters you can use depends on your configured choice of logging daemon. === The message to log === Now the message that gets logged is treated the same by Iceditch, no matter which logging daemon you use. Somewhere after the target keyword ''log'' (but before any of the <''matches''>) you specify ''msg <message>'' (or ''message <message>''). The ''<message>'' can be any string between 1 and some 29 characters max (letters, numbers and underscores; no spaces, not empty). If you do NOT specify a message, Iceditch will always create a default log message: ''<chain>_&lt;table&gt;_log''. This means that <pre>context INPUT filter log -p tcp --dport 22 </pre> will result in either one of the iptables lines shown below, depending on your choice of logging daemon: <pre>iptables -A INPUT -t filter -p tcp --dport 22 --jump LOG --log-prefix INPUT_filter_log --log-level 4 iptables -A INPUT -t filter -p tcp --dport 22 --jump ULOG --ulog-prefix INPUT_filter_log </pre> (note the default log level when using the ''syslog'' logging daemon). === Log parameters when using the ''syslog'' logging daemon=== Besides a log message, there are four more options that you can also specify. All five options are shown in the table below: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" ! colspan="3" style="background:#ffdead;"|LOG options |- !style="background:#ffdead;"|Iceditch option !style="background:#ffdead;"|IPtables option !style="background:#ffdead;"|Description |- |ip-options / ipopt | --log-ip-options |Makes Netfilter include the IP options in the log entry |- | lvl / level <''loglevel''> | --log-level <''loglevel''> | Makes Netfilter log with the specified <''loglevel''> |- | msg / message <''logmessage''> | --log-prefix <''logmessage''> | Makes Netfilter prepend <''logmessage''> to the log entry |- | tcp-options / tcpopt | --log-tcp-options |Makes Netfilter include the TCP options in the log entry |- | tcp-sequence / tcpseq | --log-tcp-sequence |Makes Netfilter include the TCP sequence number in the log entry |- |} On the log-level: when using the ''syslog'' daemon (IPtables target LOG), it is possible to specify a log level. The log level can be specified numerically or by name; Iceditch will translate it to its numerical value. However, if you do NOT specify a log level, Iceditch will include a default log level, being 4 (warn). For completeness, we here reproduce the list of logging levels that ''log'' understands: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Level !style="background:#ffdead;"|Description |- |0 |''emerg'' or ''panic'' |- |1 |''alert'' |- |2 |''crit'' |- |3 |''err'' |- |4 |''warn'' (default) |- |5 |''notice'' |- |6 |''info'' |- |7 |''debug'' |- |} === Log parameters when using the ''ulog'' user space logging daemon=== {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" ! colspan="3" style="background:#ffdead;"|ULOG options |- !style="background:#ffdead;"|Iceditch option !style="background:#ffdead;"|IPtables option !style="background:#ffdead;"|Description |- | cprange <''size''> | --ulog-cprange <''size''> |log the first ''size'' bytes of each packet |- | msg / message <''logmessage''> | --log-prefix <''logmessage''> | Makes Netfilter prepend <''logmessage''> to the log entry |- | qtreshold / qtresh <''value''> | --ulog-qthreshold <''value''> |Queue ''value'' packets before sending them to ''ulogd'' (default = 1, max = 50) |- |} <br> Now an example: context "INPUT" "filter" log lvl info msg SSH_incoming -p tcp --dport 22 -i $inetIF Iceditch works this out into iptables -A INPUT -t filter -p tcp --dport 22 -i $inetIF --jump ULOG --ulog-prefix "SSH_incoming" --log-level 6 == Target keyword: mark == '''''mark <markval> [log [msg <message>]] <matches>'''''<br> If a packet matches the <matches>, then it will be marked with the <markval> specified. An example from the context PREROUTING mangle: mark 2 –p tcp --dport 22 Iceditch works this out to iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump MARK --setmark 2 Should you want to also log the packet, you’d use mark 2 log –p tcp --dport 22 Iceditch works this out to iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump LOG \ --log-prefix mark_PREROUTING_mangle: iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump MARK --setmark 2 Because of how iptables handles the MARK target, you can only use it in contexts where the table is ''mangle''. == Target keyword: masquerade == '''''masquerade <iface> [to <p1[-p2]>] [log [msg <message>]] <matches>'''''<br> <iface> is the (outward facing) network interface that we want to masquerade on.<br> The MASQUERADE target is used basically the same as the SNAT target, but it does not require any ''--to-source'' option. The reason for this is that the MASQUERADE target was made to work with connections which get dynamic IP addresses when connecting to the network in question, for example dial-up connections, or DHCP connections. This means that you should only use the MASQUERADE target with dynamically assigned IP connections, which we don't know the actual IP address of in advance. If you have a static IP connection, you should instead use the SNAT target.<br> When you masquerade a connection, it means that we set the IP address used on a specific network ''interface'', instead of getting it from the ''--to-source option''. The necessary IP address is automatically grabbed from the information about the specific interface. Using the ''masquerade'' keyword also has the advantage that connections are forgotten when an interface goes down, which is extremely good if we, for example, kill a specific interface. If we would have used the SNAT target, we may have been left with a lot of old connection tracking data, which would be kept in connection tracking memory for days. forgetting about connections is, in general, the correct behavior when dealing with dial-up lines that are probably assigned a different IP every time they are brought up. In case we are assigned a different IP, the connection is lost anyways, and it is more or less idiotic to keep the entry around.<br> It is still possible to use the MASQUERADE target instead of SNAT even though you do have a static IP; however, it is not favorable since it will add extra overhead, and there may be inconsistencies in the future which will thwart your existing scripts and render them "unusable".<br> Note that the MASQUERADE target is only valid within the POSTROUTING chain in the nat table, just as the SNAT target. == Target keyword: nojump == '''''nojump [log [msg <message>]] <matches>'''''<br> ''nojump'' creates an iptables rule with an empty jump target. This means that the match is made, but no action is undertaken on the match. OK, so why do we even ''need'' a "nojump" target if it doesn't create an IPtables jump? As far as we know, two valid reasons might be:<br> === using nojump for auditing === A ''nojump'' rule can be used for '''auditing'''. Say you want to know how often you are pinged from IP 1.2.3.4 - without logging each and every ping request to the firewall logfile. You could write context INPUT filter nojump -p icmp --icmp-type 8 -s 1.2.3.4</pre> This rule could be checked in IPtables with ''iptables -n -L'' as <pre> Chain INPUT (policy DROP 1713K packets, 119M bytes) pkts bytes target prot opt in out source destination 0 0 icmp -- * * 1.2.3.4 0.0.0.0/0 icmp type 8</pre> Good to know you haven't been pinged by 1.2.3.4 yet, eh?!<br> === using nojump to apply matches without using targets === A ''nojump'' rule can be used to '''apply matches''' like ''recent'', that may just happily act on their own. Say you want to block spurious SSH login attempts; if "spurious" to you means "more than two connection attempts per minute", then you could try: context INPUT filter nojump -p tcp --dport 22 -i $inetIF -m state --state NEW -m recent --name SSHers --set drop -p tcp --dport 22 -i $inetIF -m state --state NEW -m recent --name SSHers --update --seconds 60 --hitcount 3 This causes Iceditch to add the IP of every connection attempt to your SSH port to a list named "SSHers", and consecutively, that every packet that fits this description AND has seen two more hits from the same source address in the last 60 seconds gets dropped. Essentially, this limits brute-force attackers on your SSH to trying 2 logins per minute at most. But you see that the nojump rule gets translated to iptables -A INPUT -t filter -p tcp --dport 22 -i $inetIF -m state --state NEW -m recent --name SSHers --set No ''--jump'' in that line - hence the name of the Iceditch target: ''nojump''. == Target keyword: redirect == '''''redirect [to <to-ports>] [log [msg <message>]] <matches>'''''<br> If a packet matches the <matches>, then it will be redirected to the local machine, by setting the destination IP to a fitting IP address of the local machine (i.e. 127.0.0.1, or the first-bound IP address of the interface over which it came in. Additionally, by specifying “to <to-ports>” you can have the destination ports redirected to a port or portrange. <to-ports> can either be a port number (e.g. 8080) or a port range (e.g. 6661-6669; the latter is inclusive). Example for a transparent HTTP proxy: context "OUTPUT" "nat" redirect to 8080 –p tcp --dport 80 Iceditch works this out to iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump REDIRECT –to-ports 8080 Should you want to log the packet, you could use redirect to 8080 log –p tcp --dport 80 Iceditch works this out to iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump LOG \ --log-prefix OUTPUT_REDIRECT_to_8080: iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump REDIRECT –-to-ports 8080 Because of how iptables handles the REDIRECT target, you can only use it in contexts where the table is "nat" and the chain is PREROUTING or OUTPUT. == Target keyword: reject == '''''reject [with <type>] [log [msg <message>]] <matches>'''''<br> In essence, this does the same as the "drop" target keyword, only it jumps to REJECT instead of DROP. This means the packet is discarded (just as with DROP), but the sender is notified using ICMP (by default, your machine will send an ICMP-packet of type "icmp-port-unreachable"). Because of how iptables handles the REJECT target, you can only use it in contexts where the table is "filter". Optionally, you can follow "reject" with the keyword "with", and then use one of the following rejection types: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Type !style="background:#ffdead;"|Description |- | icmp-host-prohibited | will send an ICMP-message "host prohibited" |- | icmp-host-unreachable | will send an ICMP-message "host unreachable" |- | icmp-net-prohibited | will send an ICMP-message "net prohibited" |- | icmp-net-unreachable | will send an ICMP-message "net unreachable" |- | icmp-port-unreachable | DEFAULT; will send an ICMP-message "port unreachable" |- | icmp-proto-unreachable | DEFAULT; will send an ICMP-message "protocol unreachable" |- | tcp-reset | will send a TCP reset, a packet with the RST flag set (as a response to a TCP packet only) |- | host-prohib | synonymous to icmp-host-prohibited |- | host-unreach | synonymous to icmp-host-unreachable |- | net-prohib | synonymous to icmp-net-prohibited |- | net-unreach | synonymous to icmp-net-unreachable |- | port-unreach | synonymous to icmp-port-unreachable |- | proto-unreach | synonymous to icmp-proto-unreachable |- |} If you don’t specify "with <type>", then netfilter will assume icmp-port-unreachable. Thus, should you want to reject a packet in context filter INPUT (and log it) with reason net-prohib, you’d use reject with net-prohib log –p tcp –i eth0 --dport 22 Iceditch works this out to iptables –t filter –A INPUT –p tcp –i eth0 –-dport 22 –-jump LOG \ --log-prefix INPUT_REJECT_with_net-prohib: iptables –t filter –A INPUT –p tcp –i eth0 –-dport 22 \ –-jump REJECT –-reject-with net-prohib –p tcp –i eth0 –-dport 22 Note: RFC behavior is that unbound TCP ports return resets on connections, and unbound UDP ports return ICMP port unreachable. If you want to make your firewall less obtrusive, then do that. Your filtered ports will then be (at least in that respect) indistinguishable from unfiltered, unbound ports. ==Target keyword: route== '''''route {<iface>|<ifaceindex>} [log [msg <message>]] <matches>'''''<br> The ''route'' target lets you route a received packet through an interface or towards a host, even if the regular destination of the packet is the router itself. The ROUTE target is also able to change the incoming interface of a packet. Packets are directly put on the wire and do not traverse any other table.<br> ''route'' takes one mandatory option, which may be either the interface name over which to route the packet that matches the <matches>, or the index number of that interface (based on the order in /proc/net/dev). Iceditch is pretty lazy in how to interpret that option: if it's all numerals, Iceditch treats it as the interface index number, if it contains any other character, it is considered the interface name (e.g. ''eth0''); and no sanity check is performed on the specified <iface|ifaceindex>. == Target keyword: same== '''''same [to <a1[-a2]> [to <a3[-a4]>] ] [nodest] [log [msg <message>] ] <matches>'''''<br> ''same'' only works in the nat table, in the POSTROUTING chain. It is very closely related to ''snat'' (see below), because it does virtually the same thing. Basically, the ''same'' target will try to always use the same outgoing IP address for all connections initiated by a single host on your network. For example, say you have one "internal" /24 network (192.168.1.0) and 3 "external" IP addresses (10.5.6.11-13) on your firewall/router machine. Now, if internal machine 192.168.1.20 went out through the .11 address the first time, then the firewall will try to keep that machine always going out through that same IP address. So basically ''same'' might be a better fit than ''snat'' if you have multiple external IP addresses.<br> However, there is also functionality lacking in ''same'' that ''snat'' has, namely the specification of (TCP and UDP) ports or port ranges to use for the NATting operation. See ''snat'' for its port possibilities.<br> Furthermore, ''same'' has an extra option that ''snat'' does not have: under normal action, the ''same'' target is calculating the followup connections based on both destination and source IP addresses. Using the ''nodest'' option (which corresponds with --nodst in the actual IPtables command), it uses only the source IP address to find out which outgoing IP the NAT function should use for the specific connection. Without this argument, it uses a combination of the destination and source IP address. == Target keyword: snat== '''''snat [to <a1[-a2][:p1-p2]]> [to <a3[-a4][:p3-p4]]>] ] [log [msg <message>] ] <matches>'''''<br> This keyword is only valid in the chain POSTROUTING, table nat. And ofcourse, source NATting does you little good if you haven't enabled forwarding (e.g. use this machine as a router for other machines on your network).<br> Calling snat with the right parameters will create a Source NATting rule for you, whereby a packet matching the <matches> will be source NATted using the source IP address ''a1'' (or the range ''a1-a2''). Ofcourse, ''a1[-a2]'' should be valid IP address(es) of the firewalling machine.<br> Furthermore, if a port range ''p1-p2'' is specified, then you'll limit the range of ports that ''snat'' will use outbound (only valid for TCP or UDP packets).<br> Finally, it is possible to specify ''multiple'' IP address ranges and port ranges, using multiple ''to <a1[-a2][:p1-p2]]'' declarations in succession.<br> An example would be: context "POSTROUTING" "nat" snat to $inetIP -o $inetIF ! --src $inetIP If the variable ''$inetIP'' contains your public IP (e.g. 212.238.151.72), and ''$inetIF'' your interface connected to the Internet (e.g. ''eth0''), then this rule would expand to iptables -A POSTROUTING -t nat -o eth0 ! --src 212.238.151.72 -j SNAT --to-source 212.238.151.72 This would cause Iceditch to source NAT any outbound packet that is NOT sent by your firewall itself; in effect your server is now a nice fullblown NAT router for all machines on your private network. b97cf7fec3b4564f82b9c8c04e8f746636b188f3 0 1443 1608 1539 2008-08-10T14:07:34Z Saruman! 2 updated targets and custom chains wikitext text/x-wiki ==The Iceditch control language== If you know and understand [http://iptables-tutorial.frozentux.net/iptables-tutorial.html IPtables commands], then the syntax of the Iceditch control language seems very simple to you. When you realise that it's only goal is to simplify standard IPtables commands ''without'' taking away their incredible power or flexibility, you'll also realise that this is actually inevitable. But let's not linger here: dip in! === The ''Context'' header=== Just about every IPtables command that ''creates'' a firewall rule, acts on some firewall table, and some firewall chain. These are found in the IPtables invocation, and are specified by options -A (add to chain) and -t (use table). Thus, the rule iptables -A INPUT -t filter -d 10.0.0.1 -j DROP works in chain ''INPUT'' and table ''filter''. There is a number of default chains: * PREROUTING * FORWARD * INPUT * OUTPUT * POSTROUTING Iceditch understands these built-in chains, and can also help you create custom chains. There is also a number of default tables: * conntrack * mangle * nat * filter The "conntrack" table is not user manipulable, so Iceditch won't (cannot) allow you to do anything in/with it. Now please have a peek at the following [[nfk-traversal-picture | magnificent picture]]. You can see that there are only 11 combinations of default chains and tables that can accept IPtables rules. Fear not: '''Iceditch will check every rule for valid combination of table and chain''', and yield an error message for any invalid combination. The valid combinations thus are: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" | !style="background:#ffdead;"|conntrack !style="background:#ffdead;"|mangle !style="background:#ffdead;"|nat !style="background:#ffdead;"|filter |- | style="background:lightgrey" | '''PREROUTING''' | X | V | V | |- | style="background:lightgrey" | '''FORWARD''' | | V | | V |- | style="background:lightgrey" | '''INPUT''' | | V | | V |- | style="background:lightgrey" | '''OUTPUT''' | X | V | V | V |- | style="background:lightgrey" | '''POSTROUTING''' | | V | V | |- | style="background:lightgrey" | '''(custom)''' | | V | V | V |- |} As you can see from the last line, you can create custom chains in the three tables ''filter'', ''mangle'' and ''nat''. After creating a custom chain (e.g. "FTPTRAFFIC" in table "filter") you can create rules in it by setting the context to your custom chain: context FTPTRAFFIC filter The way to tell Iceditch which table and chain to use, is by grouping all commands for a certain combination of table and chain in one stanza of the configuration file: this is called the ''context'' of the rules. A context is specified in the configuration file with the following header: <pre> context &lt;chain&gt; &lt;table&gt; </pre> Every line that follows is assumed to belong to this particular context, so that in these lines the target chain and table do not need to appear. Currently, every context is allowed to appear multiple times in the configuration file. This means Iceditch allows multiple stanzas per unique context. However, they will be processed in the order in which they appear in the configuration file, so one must be careful that the stanzas are ordered correctly; we'd advise to use each context only once, for maintainability over legibility. ===The target specification=== (Almost) every IPtables rule has a target. Iceditch takes keywords that signify the standard IPtables targets, and lets every line begin with this keyword. Thus, the keyword ''accept'' at the beginning of a line signifies that you're talking about an IPtables command that normally would end with ''--jump ACCEPT''. The keywords Iceditch currently "understands" are: * accept * classify * dnat * drop * ipv4optsstrip * log * mark * masquerade * reject * return * route * same * snat ===The rule syntax=== For every IPtables rule you want to specify in Iceditch, the syntax is based on the underlying IPtables rule. However, Iceditch rules are structured differently: the context is specified at the beginning of the stanza, the target forms the opening keyword, and there are several optional addition to the target. Therefor, forming a firewall rule in Iceditch requires you to follow both Iceditch syntax rules and IPtables syntax rules. Don't worry, it's actually quite simple. What we've done is create a page called the [[Iceditch Command Reference]], where for every target all options are described. However, this reference presupposes intimate knowledge of IPtables. Currently this wiki does not offer a comprehensive course in IPtables; to obtain this knowledge one might start off at sites like [http://iptables-tutorial.frozentux.net/chunkyhtml/index.html this] and [http://security.maruhn.com/ this one]. ==The functionality== Iceditch helps you create an IPtables based firewall. But ''what'' exactly can it do to help you? You can find out by reading the page on [[Iceditch functionality]], where we list both current functionality, as well as future features. ==The program structure== Iceditch consists of a number of files, each of which is located in a logical place - at least we think so. For clarity, we've created a comprehensive listing of all the files that comprise the Iceditch package, along with their location and function. It can be found on the [[Iceditch file structure]] page. 81beb7a2dd2f7c36ed82d3daa62624ed7e416c9a 0 1463 1612 2008-08-11T19:37:21Z Saruman! 2 Created an empty blocked page to prevent spamming wikitext text/x-wiki Blocked page - don't need spammers c0cd9ea0a7b3902c7928c7dede3f9130d0656cf7 1613 1612 2008-08-11T19:37:43Z Saruman! 2 Protected "[[Wiki/index.php]]": No spam wanted on this page [edit=sysop:move=sysop] wikitext text/x-wiki Blocked page - don't need spammers c0cd9ea0a7b3902c7928c7dede3f9130d0656cf7 0 1446 1621 1620 2008-08-15T20:28:53Z Saruman! 2 /* Target keyword: connmark */ started wikitext text/x-wiki == Parameter: log == ''target '''log [(msg|message) <message>]''' <matches>''<br> After most keywords, a "log" parameter can be added (see below). If the "log" parameter is followed by "msg" (or "message"), then the parameter following "msg" is read and used as log-prefix. The parameter is not allowed to have whitespace (that limitation is Iceditch-specific, not IPtables-related), and the maximum length of the log-prefix is determined by your version of netfilter/IPtables and your choice of IPtables logging utility (syslogemu or ulog); this limit is usually some 29 characters. Note that Iceditch does not perform any sanity checks on the message. Thus a packet matching the <matches> part of the rule will be logged with the default setting of the "log" target. If the "log" parameter is ''not'' followed by "msg", then the packet will be logged with a default log message, being "&lt;table&gt;_<chain>_<target>" and all the other default setting of the "log" target. Thus, should you want to log a packet with more control over the logging parameters, then you need an extra line, beginning with the ''target keyword'' "log", instead of just following the target keyword with parameter ''log''. For more information, see the [[Iceditch_Command_Reference#Target_keyword:_log | target keyword "log"]] below. == Context keyword: context == '''''context <chain> &lt;table&gt;'''''<br> Every IPtables rule is written to a chain in a table; with Iceditch, you don't have to specify the chain and table in every line. Just precede the lines with the ''context'' statement. Example: context POSTROUTING nat Notes: the order of chain and table does not matter; ''context nat POSTROUTING'' works just as well. Furthermore, <chain> and &lt;table&gt; have been made case-insensitive; whatever you specify as chain will be translated to uppercase, whatever you specify as table will be translated to lowercase. This gives you the possibility to write the context as you like to read it, e.g. ''context Postrouting Nat''; after processing this, Iceditch will have two variables $CHAIN="POSTROUTING" and $TABLE="nat" that it will use in every following command. For example: context "Input" "fIlTeR" accept -p tcp --dport 22 will result in the following IPtables call: iptables -A INPUT -t filter -p tcp --dport 22 --jump ACCEPT If you do NOT specify a [[Iceditch IPtables language | valid combination]] of chain and table, the execution of Iceditch will halt with a fatal error. It is allowed (but not recommended) to call ''context'' multiple times for the same combination of chain and table; the order in which the rules are added to that chain in that table, is the same in which they appear in your rulefile, top to bottom. This is not recommended, because we feel it decreases readability, and thus maintainability, of the rules file. But hey, it's going to be ''your'' rulefile anyway...<br> Note: you cannot create custom chains by the names of mangle, nat or filter, since Iceditch will always interpret these names as those of tables. == Context keyword: create_chain == '''''create_chain <chain> [&lt;table&gt;]'''''<br> This command creates a new chain named <chain>, in the specified table &lt;table&gt;. If no table is specified, then the ''filter'' table is assumed. Just as with the ''context'' command, the <chain> name you specify will be translated to all uppercase.<br> The name for your new chain must be unique, although just like the built-in chains, you can specify the same name in different tables. If you create "fun-filter" in table ''filter'', and then create a "fun-filter" in table ''nat'', then you actually have two different chains. But remember: since Iceditch translates every chain name to uppercase, you can't create "Fun-filter" AND "fun-FILTER" in the same table - they're the same chain.<br> NOTE: after you've run ''create_chain'', you still have to switch context to create rules in the new chain! example:<br> create_chain fun-filter context fun-filter filter accept -p tcp --dport 22 This will result in iptables -N FUN-FILTER -t filter iptables -A FUN-FILTER -t filter -p tcp --dport 22 --jump ACCEPT == Target keyword: accept == '''''accept [log [msg <message>]] <matches>'''''<br> If a network packet fits the <matches>, then it will be accepted (passed) through the table/chain defined in the context where you put the accept rule. Example: context Input Filter accept –p tcp --dport 22 Iceditch works this out to iptables –t filter –A INPUT –p tcp –-dport 22 –-jump ACCEPT Should you want to log the packet, you’d use context Input Filter accept log –p tcp --dport 22 Iceditch works this out to iptables –t filter –A INPUT –p tcp –-dport 22 \ –-jump LOG --log-prefix accept_INPUT_filter iptables –t filter –A INPUT –p tcp –-dport 22 –-jump ACCEPT Note: the ACCEPT target is valid in any user-manipulable table/chain combination == Target keyword: connmark == '''''connmark { set <val>[/<mask>] | save [mask <mask>] | restore [mask <mask>] } [log [msg <message>]] <matches>'''''<br> This target sets a mark on a connection when you use ''connmark set <value>''; the mark for your connection is the specified <value>, or <value> ANDed with <mask>. The resulting mark value is an integer between 0 and 4294967295l, so you can set plenty of matches :-). The marks you set can be matched in different rules with the "connmark match", so this is a bit like a bookmark.<br> Now sometimes you have already marked a packet with the MARK target; you can subsequently push this MARK-value through to the connection using ''conmark save'', although you can slightly alter the connection mark value using the ''mask <mask>'' option, which provides a binary "and", so that only the masked bits are set.<br> This process also works the other way around: you can "restore" the mark on the connection to an individual packet using ''restore'', if need be again logically ANDed with a <mask> value. However, this last action works '''only''' in the ''mangle'' table (naturally, since it mangles the packet).<br> As an example: two lines in Iceditch language context INPUT mangle connmark set 127/192 -p tcp --dport 22 connmark restore mask 126 -p tcp --dport 22 These two commands get translated to iptables –t mangle –A INPUT –p tcp –-dport 22 \ –-jump CONNMARK --set-mark 127/192 iptables –t mangle –A INPUT –p tcp –-dport 22 \ –-jump CONNMARK --restore-mark --mask 126 The effect of the first line is that if a packet is aimed at port 22 (SSH), then its connection gets marked with value 64 (127 AND 192). The second line looks at any SSH packet, and if it finds one, it takes the mark from the connection (if any is present), and marks the packet itself with that value, ANDed with mask 128. So if the packet belongs to the connection that the ''first'' line had marked with value 64, then the packet gets marked with 64 (64 AND 126 = 64); but if the packet had belonged to a connection marked 251, then it would've gotten marked 122 (251 AND 126). == Target keyword: classify == '''''classify <classval> [log [msg <message>]] <matches>'''''<br> If a packet travelling through the mangle table in the POSTROUTING chain matches the <matches>, then it will be classified with the <classval> specified. An example: classify 2:11 –p tcp --dport 22 The script works this out to iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump CLASSIFY --setclass 2:11 Should you want to also log the packet, you’d use classify 2:11 log msg classified_2:11 –p tcp --dport 22 The script works this out to iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump LOG \ --log-prefix classified_2:11: iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump CLASSIFY \ --setclass 2:11 Should you not give a msg, then the log-prefix becomes classify_POSTROUTING_mangle. Because of how iptables handles the CLASSIFY target, you can only use it in contexts where the chain is "POSTROUTING" and the table is "mangle". == Target keyword: dnat == '''''dnat [to] <a1[-a2][:p1[-p2]]> [log [msg <message>]] <matches>'''''<br> In the above, a1 and a2 are used to specify a (range of) IP address(es); for TCP and UDP protocols, a destination port or port range can be provided. Note that the "to" in the command is optional, and serves only readability.<br> If a packet matches the qualifiers, then it will be destination-NATted to the provided IP address or address range. For example, if you want to DNAT port 81 on your external interface eth1 to an internal webserver on 10.0.0.1, you could use context "PREROUTING" "nat" dnat to 10.0.0.1:80 –p tcp –i eth1 –-dport 81 If you give a range of IP addresses, then the DNAT logic of IPtables will randomly pick an address and DNAT the packet there. However, note that a single stream will always use the same IP address from that range, and that each stream will randomly be given an IP address that it will always be destined for, within that stream.<br> Furthermore, note that the DNAT target is only available within the PREROUTING and OUTPUT chains in the nat table, and any of the chains called upon from any of those listed chains. Note that chains containing DNAT targets may not be used from any other chains, such as the POSTROUTING chain. However, the bad news is that Iceditch currently does not know how to check for the latter case, so the dnat keyword only works from contexts "PREROUTING" "nat" and "OUTPUT" "nat". == Target keyword: drop == '''''drop [log [msg <message>]] <matches> '''''<br> In essence, this does the same as the "accept" target keyword, only it jumps to DROP instead of ACCEPT. Thus any packet matching the <matches> gets discarded; it will not get sent on to its final destination (or next hop), it will not get processed by any other firewall rule, and the sender of the packet is unaware of your treatment of his packet. Should you want to also log the packet, you’d use context "FORWARD" "filter" drop log –p tcp -s 10.0.0.0/16 The script works this out to iptables –t filter –A FORWARD –p tcp -s 10.0.0.0/16 –-jump LOG \ --log-prefix drop_FORWARD_filter: iptables –t filter –A FORWARD –p tcp -s 10.0.0.0/16 –-jump DROP However, be advised that using DROP may leave dead sockets on either the sending or receiving host. If you do not wish that, you might be better of using REJECT. On the other hand, dropping packets is a nice way of appearing like a black hole, so it's the weapon of choice against port scanners and the likes.<br> The DROP target can be used in any chain in any table. == Target keyword: ipv4optsstrip == '''''ipv4optsstrip [log [msg <message>]] <matches>'''''<br> This target takes any packet that fits the <matches>, and then strips off all IPv4 options from its header. It can only be used in the ''mangle'' table. For example, the following rule strips the IPv4 options from any packet incoming on ''eth0'': context PREROUTING mangle ipv4optsstrip -i eth0 == Target keyword: tochain == '''''tochain <customchain> [log [msg <message>]] <matches>'''''<br> If you've created a custom chain within a certain table, then you can jump to this custom chain using ''tochain'', as long as the ''tochain'' invocation appears in a context with the same table. For example: create_chain FTPtraffic filter (...) context INPUT filter (...) tochain FTPtraffic -p tcp --dport 20 In this example, any TCP packet that appears in table filter, chain INPUT and is directed at port 20, is sent on through to the previously created chain FTPTRAFFIC (keep in mind that Iceditch will always translate any chain name to all uppercase). Rule matching and packet processing will continue in that chain, until an ACCEPT or DROP is encountered, or a RETURN, or all rules in the custom chain have been exhausted. After that, the implicit return policy on your custom chain will return the packet to whence it came (context INPUT filter, the line below the ''tochain'' invocation). == Target keyword: log == ''for LOG target: '''log [(msg|message) <message>] [ip-options|ipopt] [(lvl|level) <loglevel>] [tcp-options|tcpopt] [tcp-sequence|tcpseq] <matches>'''''<br> ''for ULOG target: '''log [(msg|message) <message>] [cprange <range>] [qtreshold|qtresh <treshold>] <matches>''''' Sometimes, the standard ''log'' parameter is just not enough. This can be the case when you want to log a packet with one or more of the extra options beside ''--log-prefix''. Or maybe you want to just log a certain type or class of packets, without performing an action on those packets just yet, so that you can't use ''log'' as a parameter to one of the other Iceditch keywords.<br> For this reason, AND for flexibility and clarity, Iceditch has the dedicated target keyword ''log''.<br> Just as when you use the ''log'' '''parameter''' after another target keyword, the use of the log '''target''' will make Iceditch call upon the logging daemon specified in the Iceditch [[Iceditch file structure | config file]]. Standard this is LOG, but optionally you could specify ULOG in the config file. Note that an explicit call on target keyword ''log'' gives one the option to specify extra parameters, but also note that the choice of which parameters you can use depends on your configured choice of logging daemon. === The message to log === Now the message that gets logged is treated the same by Iceditch, no matter which logging daemon you use. Somewhere after the target keyword ''log'' (but before any of the <''matches''>) you specify ''msg <message>'' (or ''message <message>''). The ''<message>'' can be any string between 1 and some 29 characters max (letters, numbers and underscores; no spaces, not empty). If you do NOT specify a message, Iceditch will always create a default log message: ''<chain>_&lt;table&gt;_log''. This means that <pre>context INPUT filter log -p tcp --dport 22 </pre> will result in either one of the iptables lines shown below, depending on your choice of logging daemon: <pre>iptables -A INPUT -t filter -p tcp --dport 22 --jump LOG --log-prefix INPUT_filter_log --log-level 4 iptables -A INPUT -t filter -p tcp --dport 22 --jump ULOG --ulog-prefix INPUT_filter_log </pre> (note the default log level when using the ''syslog'' logging daemon). === Log parameters when using the ''syslog'' logging daemon=== Besides a log message, there are four more options that you can also specify. All five options are shown in the table below: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" ! colspan="3" style="background:#ffdead;"|LOG options |- !style="background:#ffdead;"|Iceditch option !style="background:#ffdead;"|IPtables option !style="background:#ffdead;"|Description |- |ip-options / ipopt | --log-ip-options |Makes Netfilter include the IP options in the log entry |- | lvl / level <''loglevel''> | --log-level <''loglevel''> | Makes Netfilter log with the specified <''loglevel''> |- | msg / message <''logmessage''> | --log-prefix <''logmessage''> | Makes Netfilter prepend <''logmessage''> to the log entry |- | tcp-options / tcpopt | --log-tcp-options |Makes Netfilter include the TCP options in the log entry |- | tcp-sequence / tcpseq | --log-tcp-sequence |Makes Netfilter include the TCP sequence number in the log entry |- |} On the log-level: when using the ''syslog'' daemon (IPtables target LOG), it is possible to specify a log level. The log level can be specified numerically or by name; Iceditch will translate it to its numerical value. However, if you do NOT specify a log level, Iceditch will include a default log level, being 4 (warn). For completeness, we here reproduce the list of logging levels that ''log'' understands: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Level !style="background:#ffdead;"|Description |- |0 |''emerg'' or ''panic'' |- |1 |''alert'' |- |2 |''crit'' |- |3 |''err'' |- |4 |''warn'' (default) |- |5 |''notice'' |- |6 |''info'' |- |7 |''debug'' |- |} === Log parameters when using the ''ulog'' user space logging daemon=== {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" ! colspan="3" style="background:#ffdead;"|ULOG options |- !style="background:#ffdead;"|Iceditch option !style="background:#ffdead;"|IPtables option !style="background:#ffdead;"|Description |- | cprange <''size''> | --ulog-cprange <''size''> |log the first ''size'' bytes of each packet |- | msg / message <''logmessage''> | --log-prefix <''logmessage''> | Makes Netfilter prepend <''logmessage''> to the log entry |- | qtreshold / qtresh <''value''> | --ulog-qthreshold <''value''> |Queue ''value'' packets before sending them to ''ulogd'' (default = 1, max = 50) |- |} <br> Now an example: context "INPUT" "filter" log lvl info msg SSH_incoming -p tcp --dport 22 -i $inetIF Iceditch works this out into iptables -A INPUT -t filter -p tcp --dport 22 -i $inetIF --jump ULOG --ulog-prefix "SSH_incoming" --log-level 6 == Target keyword: mark == '''''mark <markval> [log [msg <message>]] <matches>'''''<br> If a packet matches the <matches>, then it will be marked with the <markval> specified. An example from the context PREROUTING mangle: mark 2 –p tcp --dport 22 Iceditch works this out to iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump MARK --setmark 2 Should you want to also log the packet, you’d use mark 2 log –p tcp --dport 22 Iceditch works this out to iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump LOG \ --log-prefix mark_PREROUTING_mangle: iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump MARK --setmark 2 Because of how iptables handles the MARK target, you can only use it in contexts where the table is ''mangle''. == Target keyword: masquerade == '''''masquerade <iface> [to <p1[-p2]>] [log [msg <message>]] <matches>'''''<br> <iface> is the (outward facing) network interface that we want to masquerade on.<br> The MASQUERADE target is used basically the same as the SNAT target, but it does not require any ''--to-source'' option. The reason for this is that the MASQUERADE target was made to work with connections which get dynamic IP addresses when connecting to the network in question, for example dial-up connections, or DHCP connections. This means that you should only use the MASQUERADE target with dynamically assigned IP connections, which we don't know the actual IP address of in advance. If you have a static IP connection, you should instead use the SNAT target.<br> When you masquerade a connection, it means that we set the IP address used on a specific network ''interface'', instead of getting it from the ''--to-source option''. The necessary IP address is automatically grabbed from the information about the specific interface. Using the ''masquerade'' keyword also has the advantage that connections are forgotten when an interface goes down, which is extremely good if we, for example, kill a specific interface. If we would have used the SNAT target, we may have been left with a lot of old connection tracking data, which would be kept in connection tracking memory for days. forgetting about connections is, in general, the correct behavior when dealing with dial-up lines that are probably assigned a different IP every time they are brought up. In case we are assigned a different IP, the connection is lost anyways, and it is more or less idiotic to keep the entry around.<br> It is still possible to use the MASQUERADE target instead of SNAT even though you do have a static IP; however, it is not favorable since it will add extra overhead, and there may be inconsistencies in the future which will thwart your existing scripts and render them "unusable".<br> Note that the MASQUERADE target is only valid within the POSTROUTING chain in the nat table, just as the SNAT target. == Target keyword: nojump == '''''nojump [log [msg <message>]] <matches>'''''<br> ''nojump'' creates an iptables rule with an empty jump target. This means that the match is made, but no action is undertaken on the match. OK, so why do we even ''need'' a "nojump" target if it doesn't create an IPtables jump? As far as we know, two valid reasons might be:<br> === using nojump for auditing === A ''nojump'' rule can be used for '''auditing'''. Say you want to know how often you are pinged from IP 1.2.3.4 - without logging each and every ping request to the firewall logfile. You could write context INPUT filter nojump -p icmp --icmp-type 8 -s 1.2.3.4</pre> This rule could be checked in IPtables with ''iptables -n -L'' as <pre> Chain INPUT (policy DROP 1713K packets, 119M bytes) pkts bytes target prot opt in out source destination 0 0 icmp -- * * 1.2.3.4 0.0.0.0/0 icmp type 8</pre> Good to know you haven't been pinged by 1.2.3.4 yet, eh?!<br> === using nojump to apply matches without using targets === A ''nojump'' rule can be used to '''apply matches''' like ''recent'', that may just happily act on their own. Say you want to block spurious SSH login attempts; if "spurious" to you means "more than two connection attempts per minute", then you could try: context INPUT filter nojump -p tcp --dport 22 -i $inetIF -m state --state NEW -m recent --name SSHers --set drop -p tcp --dport 22 -i $inetIF -m state --state NEW -m recent --name SSHers --update --seconds 60 --hitcount 3 This causes Iceditch to add the IP of every connection attempt to your SSH port to a list named "SSHers", and consecutively, that every packet that fits this description AND has seen two more hits from the same source address in the last 60 seconds gets dropped. Essentially, this limits brute-force attackers on your SSH to trying 2 logins per minute at most. But you see that the nojump rule gets translated to iptables -A INPUT -t filter -p tcp --dport 22 -i $inetIF -m state --state NEW -m recent --name SSHers --set No ''--jump'' in that line - hence the name of the Iceditch target: ''nojump''. == Target keyword: redirect == '''''redirect [to <to-ports>] [log [msg <message>]] <matches>'''''<br> If a packet matches the <matches>, then it will be redirected to the local machine, by setting the destination IP to a fitting IP address of the local machine (i.e. 127.0.0.1, or the first-bound IP address of the interface over which it came in. Additionally, by specifying “to <to-ports>” you can have the destination ports redirected to a port or portrange. <to-ports> can either be a port number (e.g. 8080) or a port range (e.g. 6661-6669; the latter is inclusive). Example for a transparent HTTP proxy: context "OUTPUT" "nat" redirect to 8080 –p tcp --dport 80 Iceditch works this out to iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump REDIRECT –to-ports 8080 Should you want to log the packet, you could use redirect to 8080 log –p tcp --dport 80 Iceditch works this out to iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump LOG \ --log-prefix OUTPUT_REDIRECT_to_8080: iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump REDIRECT –-to-ports 8080 Because of how iptables handles the REDIRECT target, you can only use it in contexts where the table is "nat" and the chain is PREROUTING or OUTPUT. == Target keyword: reject == '''''reject [with <type>] [log [msg <message>]] <matches>'''''<br> In essence, this does the same as the "drop" target keyword, only it jumps to REJECT instead of DROP. This means the packet is discarded (just as with DROP), but the sender is notified using ICMP (by default, your machine will send an ICMP-packet of type "icmp-port-unreachable"). Because of how iptables handles the REJECT target, you can only use it in contexts where the table is "filter". Optionally, you can follow "reject" with the keyword "with", and then use one of the following rejection types: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Type !style="background:#ffdead;"|Description |- | icmp-host-prohibited | will send an ICMP-message "host prohibited" |- | icmp-host-unreachable | will send an ICMP-message "host unreachable" |- | icmp-net-prohibited | will send an ICMP-message "net prohibited" |- | icmp-net-unreachable | will send an ICMP-message "net unreachable" |- | icmp-port-unreachable | DEFAULT; will send an ICMP-message "port unreachable" |- | icmp-proto-unreachable | DEFAULT; will send an ICMP-message "protocol unreachable" |- | tcp-reset | will send a TCP reset, a packet with the RST flag set (as a response to a TCP packet only) |- | host-prohib | synonymous to icmp-host-prohibited |- | host-unreach | synonymous to icmp-host-unreachable |- | net-prohib | synonymous to icmp-net-prohibited |- | net-unreach | synonymous to icmp-net-unreachable |- | port-unreach | synonymous to icmp-port-unreachable |- | proto-unreach | synonymous to icmp-proto-unreachable |- |} If you don’t specify "with <type>", then netfilter will assume icmp-port-unreachable. Thus, should you want to reject a packet in context filter INPUT (and log it) with reason net-prohib, you’d use reject with net-prohib log –p tcp –i eth0 --dport 22 Iceditch works this out to iptables –t filter –A INPUT –p tcp –i eth0 –-dport 22 –-jump LOG \ --log-prefix INPUT_REJECT_with_net-prohib: iptables –t filter –A INPUT –p tcp –i eth0 –-dport 22 \ –-jump REJECT –-reject-with net-prohib –p tcp –i eth0 –-dport 22 Note: RFC behavior is that unbound TCP ports return resets on connections, and unbound UDP ports return ICMP port unreachable. If you want to make your firewall less obtrusive, then do that. Your filtered ports will then be (at least in that respect) indistinguishable from unfiltered, unbound ports. ==Target keyword: route== '''''route {<iface>|<ifaceindex>} [log [msg <message>]] <matches>'''''<br> The ''route'' target lets you route a received packet through an interface or towards a host, even if the regular destination of the packet is the router itself. The ROUTE target is also able to change the incoming interface of a packet. Packets are directly put on the wire and do not traverse any other table.<br> ''route'' takes one mandatory option, which may be either the interface name over which to route the packet that matches the <matches>, or the index number of that interface (based on the order in /proc/net/dev). Iceditch is pretty lazy in how to interpret that option: if it's all numerals, Iceditch treats it as the interface index number, if it contains any other character, it is considered the interface name (e.g. ''eth0''); and no sanity check is performed on the specified <iface|ifaceindex>. == Target keyword: same== '''''same [to <a1[-a2]> [to <a3[-a4]>] ] [nodest] [log [msg <message>] ] <matches>'''''<br> ''same'' only works in the nat table, in the POSTROUTING chain. It is very closely related to ''snat'' (see below), because it does virtually the same thing. Basically, the ''same'' target will try to always use the same outgoing IP address for all connections initiated by a single host on your network. For example, say you have one "internal" /24 network (192.168.1.0) and 3 "external" IP addresses (10.5.6.11-13) on your firewall/router machine. Now, if internal machine 192.168.1.20 went out through the .11 address the first time, then the firewall will try to keep that machine always going out through that same IP address. So basically ''same'' might be a better fit than ''snat'' if you have multiple external IP addresses.<br> However, there is also functionality lacking in ''same'' that ''snat'' has, namely the specification of (TCP and UDP) ports or port ranges to use for the NATting operation. See ''snat'' for its port possibilities.<br> Furthermore, ''same'' has an extra option that ''snat'' does not have: under normal action, the ''same'' target is calculating the followup connections based on both destination and source IP addresses. Using the ''nodest'' option (which corresponds with --nodst in the actual IPtables command), it uses only the source IP address to find out which outgoing IP the NAT function should use for the specific connection. Without this argument, it uses a combination of the destination and source IP address. == Target keyword: snat== '''''snat [to <a1[-a2][:p1-p2]]> [to <a3[-a4][:p3-p4]]>] ] [log [msg <message>] ] <matches>'''''<br> This keyword is only valid in the chain POSTROUTING, table nat. And ofcourse, source NATting does you little good if you haven't enabled forwarding (e.g. use this machine as a router for other machines on your network).<br> Calling snat with the right parameters will create a Source NATting rule for you, whereby a packet matching the <matches> will be source NATted using the source IP address ''a1'' (or the range ''a1-a2''). Ofcourse, ''a1[-a2]'' should be valid IP address(es) of the firewalling machine.<br> Furthermore, if a port range ''p1-p2'' is specified, then you'll limit the range of ports that ''snat'' will use outbound (only valid for TCP or UDP packets).<br> Finally, it is possible to specify ''multiple'' IP address ranges and port ranges, using multiple ''to <a1[-a2][:p1-p2]]'' declarations in succession.<br> An example would be: context "POSTROUTING" "nat" snat to $inetIP -o $inetIF ! --src $inetIP If the variable ''$inetIP'' contains your public IP (e.g. 212.238.151.72), and ''$inetIF'' your interface connected to the Internet (e.g. ''eth0''), then this rule would expand to iptables -A POSTROUTING -t nat -o eth0 ! --src 212.238.151.72 -j SNAT --to-source 212.238.151.72 This would cause Iceditch to source NAT any outbound packet that is NOT sent by your firewall itself; in effect your server is now a nice fullblown NAT router for all machines on your private network. 9e08da80142092212815d92d87d4bf5bb9d8c49a 1622 1621 2008-08-15T20:53:52Z Saruman! 2 /* Target keyword: connmark */ corrected max mark value wikitext text/x-wiki == Parameter: log == ''target '''log [(msg|message) <message>]''' <matches>''<br> After most keywords, a "log" parameter can be added (see below). If the "log" parameter is followed by "msg" (or "message"), then the parameter following "msg" is read and used as log-prefix. The parameter is not allowed to have whitespace (that limitation is Iceditch-specific, not IPtables-related), and the maximum length of the log-prefix is determined by your version of netfilter/IPtables and your choice of IPtables logging utility (syslogemu or ulog); this limit is usually some 29 characters. Note that Iceditch does not perform any sanity checks on the message. Thus a packet matching the <matches> part of the rule will be logged with the default setting of the "log" target. If the "log" parameter is ''not'' followed by "msg", then the packet will be logged with a default log message, being "&lt;table&gt;_<chain>_<target>" and all the other default setting of the "log" target. Thus, should you want to log a packet with more control over the logging parameters, then you need an extra line, beginning with the ''target keyword'' "log", instead of just following the target keyword with parameter ''log''. For more information, see the [[Iceditch_Command_Reference#Target_keyword:_log | target keyword "log"]] below. == Context keyword: context == '''''context <chain> &lt;table&gt;'''''<br> Every IPtables rule is written to a chain in a table; with Iceditch, you don't have to specify the chain and table in every line. Just precede the lines with the ''context'' statement. Example: context POSTROUTING nat Notes: the order of chain and table does not matter; ''context nat POSTROUTING'' works just as well. Furthermore, <chain> and &lt;table&gt; have been made case-insensitive; whatever you specify as chain will be translated to uppercase, whatever you specify as table will be translated to lowercase. This gives you the possibility to write the context as you like to read it, e.g. ''context Postrouting Nat''; after processing this, Iceditch will have two variables $CHAIN="POSTROUTING" and $TABLE="nat" that it will use in every following command. For example: context "Input" "fIlTeR" accept -p tcp --dport 22 will result in the following IPtables call: iptables -A INPUT -t filter -p tcp --dport 22 --jump ACCEPT If you do NOT specify a [[Iceditch IPtables language | valid combination]] of chain and table, the execution of Iceditch will halt with a fatal error. It is allowed (but not recommended) to call ''context'' multiple times for the same combination of chain and table; the order in which the rules are added to that chain in that table, is the same in which they appear in your rulefile, top to bottom. This is not recommended, because we feel it decreases readability, and thus maintainability, of the rules file. But hey, it's going to be ''your'' rulefile anyway...<br> Note: you cannot create custom chains by the names of mangle, nat or filter, since Iceditch will always interpret these names as those of tables. == Context keyword: create_chain == '''''create_chain <chain> [&lt;table&gt;]'''''<br> This command creates a new chain named <chain>, in the specified table &lt;table&gt;. If no table is specified, then the ''filter'' table is assumed. Just as with the ''context'' command, the <chain> name you specify will be translated to all uppercase.<br> The name for your new chain must be unique, although just like the built-in chains, you can specify the same name in different tables. If you create "fun-filter" in table ''filter'', and then create a "fun-filter" in table ''nat'', then you actually have two different chains. But remember: since Iceditch translates every chain name to uppercase, you can't create "Fun-filter" AND "fun-FILTER" in the same table - they're the same chain.<br> NOTE: after you've run ''create_chain'', you still have to switch context to create rules in the new chain! example:<br> create_chain fun-filter context fun-filter filter accept -p tcp --dport 22 This will result in iptables -N FUN-FILTER -t filter iptables -A FUN-FILTER -t filter -p tcp --dport 22 --jump ACCEPT == Target keyword: accept == '''''accept [log [msg <message>]] <matches>'''''<br> If a network packet fits the <matches>, then it will be accepted (passed) through the table/chain defined in the context where you put the accept rule. Example: context Input Filter accept –p tcp --dport 22 Iceditch works this out to iptables –t filter –A INPUT –p tcp –-dport 22 –-jump ACCEPT Should you want to log the packet, you’d use context Input Filter accept log –p tcp --dport 22 Iceditch works this out to iptables –t filter –A INPUT –p tcp –-dport 22 \ –-jump LOG --log-prefix accept_INPUT_filter iptables –t filter –A INPUT –p tcp –-dport 22 –-jump ACCEPT Note: the ACCEPT target is valid in any user-manipulable table/chain combination == Target keyword: connmark == '''''connmark { set <val>[/<mask>] | save [mask <mask>] | restore [mask <mask>] } [log [msg <message>]] <matches>'''''<br> This target sets a mark on a connection when you use ''connmark set <value>''; the mark for your connection is the specified <value>, or <value> ANDed with <mask>. The resulting mark value is an integer between 0 and 4,294,967,295, so you can set plenty of matches :-). The marks you set can be matched in different rules with the "connmark match", so this is a bit like a bookmark.<br> Now sometimes you have already marked a packet with the MARK target; you can subsequently push this MARK-value through to the connection using ''conmark save'', although you can slightly alter the connection mark value using the ''mask <mask>'' option, which provides a binary "and", so that only the masked bits are set.<br> This process also works the other way around: you can "restore" the mark on the connection to an individual packet using ''restore'', if need be again logically ANDed with a <mask> value. However, this last action works '''only''' in the ''mangle'' table (naturally, since it mangles the packet).<br> As an example: two lines in Iceditch language context INPUT mangle connmark set 127/192 -p tcp --dport 22 connmark restore mask 126 -p tcp --dport 22 These two commands get translated to iptables –t mangle –A INPUT –p tcp –-dport 22 \ –-jump CONNMARK --set-mark 127/192 iptables –t mangle –A INPUT –p tcp –-dport 22 \ –-jump CONNMARK --restore-mark --mask 126 The effect of the first line is that if a packet is aimed at port 22 (SSH), then its connection gets marked with value 64 (127 AND 192). The second line looks at any SSH packet, and if it finds one, it takes the mark from the connection (if any is present), and marks the packet itself with that value, ANDed with mask 128. So if the packet belongs to the connection that the ''first'' line had marked with value 64, then the packet gets marked with 64 (64 AND 126 = 64); but if the packet had belonged to a connection marked 251, then it would've gotten marked 122 (251 AND 126). == Target keyword: classify == '''''classify <classval> [log [msg <message>]] <matches>'''''<br> If a packet travelling through the mangle table in the POSTROUTING chain matches the <matches>, then it will be classified with the <classval> specified. An example: classify 2:11 –p tcp --dport 22 The script works this out to iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump CLASSIFY --setclass 2:11 Should you want to also log the packet, you’d use classify 2:11 log msg classified_2:11 –p tcp --dport 22 The script works this out to iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump LOG \ --log-prefix classified_2:11: iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump CLASSIFY \ --setclass 2:11 Should you not give a msg, then the log-prefix becomes classify_POSTROUTING_mangle. Because of how iptables handles the CLASSIFY target, you can only use it in contexts where the chain is "POSTROUTING" and the table is "mangle". == Target keyword: dnat == '''''dnat [to] <a1[-a2][:p1[-p2]]> [log [msg <message>]] <matches>'''''<br> In the above, a1 and a2 are used to specify a (range of) IP address(es); for TCP and UDP protocols, a destination port or port range can be provided. Note that the "to" in the command is optional, and serves only readability.<br> If a packet matches the qualifiers, then it will be destination-NATted to the provided IP address or address range. For example, if you want to DNAT port 81 on your external interface eth1 to an internal webserver on 10.0.0.1, you could use context "PREROUTING" "nat" dnat to 10.0.0.1:80 –p tcp –i eth1 –-dport 81 If you give a range of IP addresses, then the DNAT logic of IPtables will randomly pick an address and DNAT the packet there. However, note that a single stream will always use the same IP address from that range, and that each stream will randomly be given an IP address that it will always be destined for, within that stream.<br> Furthermore, note that the DNAT target is only available within the PREROUTING and OUTPUT chains in the nat table, and any of the chains called upon from any of those listed chains. Note that chains containing DNAT targets may not be used from any other chains, such as the POSTROUTING chain. However, the bad news is that Iceditch currently does not know how to check for the latter case, so the dnat keyword only works from contexts "PREROUTING" "nat" and "OUTPUT" "nat". == Target keyword: drop == '''''drop [log [msg <message>]] <matches> '''''<br> In essence, this does the same as the "accept" target keyword, only it jumps to DROP instead of ACCEPT. Thus any packet matching the <matches> gets discarded; it will not get sent on to its final destination (or next hop), it will not get processed by any other firewall rule, and the sender of the packet is unaware of your treatment of his packet. Should you want to also log the packet, you’d use context "FORWARD" "filter" drop log –p tcp -s 10.0.0.0/16 The script works this out to iptables –t filter –A FORWARD –p tcp -s 10.0.0.0/16 –-jump LOG \ --log-prefix drop_FORWARD_filter: iptables –t filter –A FORWARD –p tcp -s 10.0.0.0/16 –-jump DROP However, be advised that using DROP may leave dead sockets on either the sending or receiving host. If you do not wish that, you might be better of using REJECT. On the other hand, dropping packets is a nice way of appearing like a black hole, so it's the weapon of choice against port scanners and the likes.<br> The DROP target can be used in any chain in any table. == Target keyword: ipv4optsstrip == '''''ipv4optsstrip [log [msg <message>]] <matches>'''''<br> This target takes any packet that fits the <matches>, and then strips off all IPv4 options from its header. It can only be used in the ''mangle'' table. For example, the following rule strips the IPv4 options from any packet incoming on ''eth0'': context PREROUTING mangle ipv4optsstrip -i eth0 == Target keyword: tochain == '''''tochain <customchain> [log [msg <message>]] <matches>'''''<br> If you've created a custom chain within a certain table, then you can jump to this custom chain using ''tochain'', as long as the ''tochain'' invocation appears in a context with the same table. For example: create_chain FTPtraffic filter (...) context INPUT filter (...) tochain FTPtraffic -p tcp --dport 20 In this example, any TCP packet that appears in table filter, chain INPUT and is directed at port 20, is sent on through to the previously created chain FTPTRAFFIC (keep in mind that Iceditch will always translate any chain name to all uppercase). Rule matching and packet processing will continue in that chain, until an ACCEPT or DROP is encountered, or a RETURN, or all rules in the custom chain have been exhausted. After that, the implicit return policy on your custom chain will return the packet to whence it came (context INPUT filter, the line below the ''tochain'' invocation). == Target keyword: log == ''for LOG target: '''log [(msg|message) <message>] [ip-options|ipopt] [(lvl|level) <loglevel>] [tcp-options|tcpopt] [tcp-sequence|tcpseq] <matches>'''''<br> ''for ULOG target: '''log [(msg|message) <message>] [cprange <range>] [qtreshold|qtresh <treshold>] <matches>''''' Sometimes, the standard ''log'' parameter is just not enough. This can be the case when you want to log a packet with one or more of the extra options beside ''--log-prefix''. Or maybe you want to just log a certain type or class of packets, without performing an action on those packets just yet, so that you can't use ''log'' as a parameter to one of the other Iceditch keywords.<br> For this reason, AND for flexibility and clarity, Iceditch has the dedicated target keyword ''log''.<br> Just as when you use the ''log'' '''parameter''' after another target keyword, the use of the log '''target''' will make Iceditch call upon the logging daemon specified in the Iceditch [[Iceditch file structure | config file]]. Standard this is LOG, but optionally you could specify ULOG in the config file. Note that an explicit call on target keyword ''log'' gives one the option to specify extra parameters, but also note that the choice of which parameters you can use depends on your configured choice of logging daemon. === The message to log === Now the message that gets logged is treated the same by Iceditch, no matter which logging daemon you use. Somewhere after the target keyword ''log'' (but before any of the <''matches''>) you specify ''msg <message>'' (or ''message <message>''). The ''<message>'' can be any string between 1 and some 29 characters max (letters, numbers and underscores; no spaces, not empty). If you do NOT specify a message, Iceditch will always create a default log message: ''<chain>_&lt;table&gt;_log''. This means that <pre>context INPUT filter log -p tcp --dport 22 </pre> will result in either one of the iptables lines shown below, depending on your choice of logging daemon: <pre>iptables -A INPUT -t filter -p tcp --dport 22 --jump LOG --log-prefix INPUT_filter_log --log-level 4 iptables -A INPUT -t filter -p tcp --dport 22 --jump ULOG --ulog-prefix INPUT_filter_log </pre> (note the default log level when using the ''syslog'' logging daemon). === Log parameters when using the ''syslog'' logging daemon=== Besides a log message, there are four more options that you can also specify. All five options are shown in the table below: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" ! colspan="3" style="background:#ffdead;"|LOG options |- !style="background:#ffdead;"|Iceditch option !style="background:#ffdead;"|IPtables option !style="background:#ffdead;"|Description |- |ip-options / ipopt | --log-ip-options |Makes Netfilter include the IP options in the log entry |- | lvl / level <''loglevel''> | --log-level <''loglevel''> | Makes Netfilter log with the specified <''loglevel''> |- | msg / message <''logmessage''> | --log-prefix <''logmessage''> | Makes Netfilter prepend <''logmessage''> to the log entry |- | tcp-options / tcpopt | --log-tcp-options |Makes Netfilter include the TCP options in the log entry |- | tcp-sequence / tcpseq | --log-tcp-sequence |Makes Netfilter include the TCP sequence number in the log entry |- |} On the log-level: when using the ''syslog'' daemon (IPtables target LOG), it is possible to specify a log level. The log level can be specified numerically or by name; Iceditch will translate it to its numerical value. However, if you do NOT specify a log level, Iceditch will include a default log level, being 4 (warn). For completeness, we here reproduce the list of logging levels that ''log'' understands: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Level !style="background:#ffdead;"|Description |- |0 |''emerg'' or ''panic'' |- |1 |''alert'' |- |2 |''crit'' |- |3 |''err'' |- |4 |''warn'' (default) |- |5 |''notice'' |- |6 |''info'' |- |7 |''debug'' |- |} === Log parameters when using the ''ulog'' user space logging daemon=== {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" ! colspan="3" style="background:#ffdead;"|ULOG options |- !style="background:#ffdead;"|Iceditch option !style="background:#ffdead;"|IPtables option !style="background:#ffdead;"|Description |- | cprange <''size''> | --ulog-cprange <''size''> |log the first ''size'' bytes of each packet |- | msg / message <''logmessage''> | --log-prefix <''logmessage''> | Makes Netfilter prepend <''logmessage''> to the log entry |- | qtreshold / qtresh <''value''> | --ulog-qthreshold <''value''> |Queue ''value'' packets before sending them to ''ulogd'' (default = 1, max = 50) |- |} <br> Now an example: context "INPUT" "filter" log lvl info msg SSH_incoming -p tcp --dport 22 -i $inetIF Iceditch works this out into iptables -A INPUT -t filter -p tcp --dport 22 -i $inetIF --jump ULOG --ulog-prefix "SSH_incoming" --log-level 6 == Target keyword: mark == '''''mark <markval> [log [msg <message>]] <matches>'''''<br> If a packet matches the <matches>, then it will be marked with the <markval> specified. An example from the context PREROUTING mangle: mark 2 –p tcp --dport 22 Iceditch works this out to iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump MARK --setmark 2 Should you want to also log the packet, you’d use mark 2 log –p tcp --dport 22 Iceditch works this out to iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump LOG \ --log-prefix mark_PREROUTING_mangle: iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump MARK --setmark 2 Because of how iptables handles the MARK target, you can only use it in contexts where the table is ''mangle''. == Target keyword: masquerade == '''''masquerade <iface> [to <p1[-p2]>] [log [msg <message>]] <matches>'''''<br> <iface> is the (outward facing) network interface that we want to masquerade on.<br> The MASQUERADE target is used basically the same as the SNAT target, but it does not require any ''--to-source'' option. The reason for this is that the MASQUERADE target was made to work with connections which get dynamic IP addresses when connecting to the network in question, for example dial-up connections, or DHCP connections. This means that you should only use the MASQUERADE target with dynamically assigned IP connections, which we don't know the actual IP address of in advance. If you have a static IP connection, you should instead use the SNAT target.<br> When you masquerade a connection, it means that we set the IP address used on a specific network ''interface'', instead of getting it from the ''--to-source option''. The necessary IP address is automatically grabbed from the information about the specific interface. Using the ''masquerade'' keyword also has the advantage that connections are forgotten when an interface goes down, which is extremely good if we, for example, kill a specific interface. If we would have used the SNAT target, we may have been left with a lot of old connection tracking data, which would be kept in connection tracking memory for days. forgetting about connections is, in general, the correct behavior when dealing with dial-up lines that are probably assigned a different IP every time they are brought up. In case we are assigned a different IP, the connection is lost anyways, and it is more or less idiotic to keep the entry around.<br> It is still possible to use the MASQUERADE target instead of SNAT even though you do have a static IP; however, it is not favorable since it will add extra overhead, and there may be inconsistencies in the future which will thwart your existing scripts and render them "unusable".<br> Note that the MASQUERADE target is only valid within the POSTROUTING chain in the nat table, just as the SNAT target. == Target keyword: nojump == '''''nojump [log [msg <message>]] <matches>'''''<br> ''nojump'' creates an iptables rule with an empty jump target. This means that the match is made, but no action is undertaken on the match. OK, so why do we even ''need'' a "nojump" target if it doesn't create an IPtables jump? As far as we know, two valid reasons might be:<br> === using nojump for auditing === A ''nojump'' rule can be used for '''auditing'''. Say you want to know how often you are pinged from IP 1.2.3.4 - without logging each and every ping request to the firewall logfile. You could write context INPUT filter nojump -p icmp --icmp-type 8 -s 1.2.3.4</pre> This rule could be checked in IPtables with ''iptables -n -L'' as <pre> Chain INPUT (policy DROP 1713K packets, 119M bytes) pkts bytes target prot opt in out source destination 0 0 icmp -- * * 1.2.3.4 0.0.0.0/0 icmp type 8</pre> Good to know you haven't been pinged by 1.2.3.4 yet, eh?!<br> === using nojump to apply matches without using targets === A ''nojump'' rule can be used to '''apply matches''' like ''recent'', that may just happily act on their own. Say you want to block spurious SSH login attempts; if "spurious" to you means "more than two connection attempts per minute", then you could try: context INPUT filter nojump -p tcp --dport 22 -i $inetIF -m state --state NEW -m recent --name SSHers --set drop -p tcp --dport 22 -i $inetIF -m state --state NEW -m recent --name SSHers --update --seconds 60 --hitcount 3 This causes Iceditch to add the IP of every connection attempt to your SSH port to a list named "SSHers", and consecutively, that every packet that fits this description AND has seen two more hits from the same source address in the last 60 seconds gets dropped. Essentially, this limits brute-force attackers on your SSH to trying 2 logins per minute at most. But you see that the nojump rule gets translated to iptables -A INPUT -t filter -p tcp --dport 22 -i $inetIF -m state --state NEW -m recent --name SSHers --set No ''--jump'' in that line - hence the name of the Iceditch target: ''nojump''. == Target keyword: redirect == '''''redirect [to <to-ports>] [log [msg <message>]] <matches>'''''<br> If a packet matches the <matches>, then it will be redirected to the local machine, by setting the destination IP to a fitting IP address of the local machine (i.e. 127.0.0.1, or the first-bound IP address of the interface over which it came in. Additionally, by specifying “to <to-ports>” you can have the destination ports redirected to a port or portrange. <to-ports> can either be a port number (e.g. 8080) or a port range (e.g. 6661-6669; the latter is inclusive). Example for a transparent HTTP proxy: context "OUTPUT" "nat" redirect to 8080 –p tcp --dport 80 Iceditch works this out to iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump REDIRECT –to-ports 8080 Should you want to log the packet, you could use redirect to 8080 log –p tcp --dport 80 Iceditch works this out to iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump LOG \ --log-prefix OUTPUT_REDIRECT_to_8080: iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump REDIRECT –-to-ports 8080 Because of how iptables handles the REDIRECT target, you can only use it in contexts where the table is "nat" and the chain is PREROUTING or OUTPUT. == Target keyword: reject == '''''reject [with <type>] [log [msg <message>]] <matches>'''''<br> In essence, this does the same as the "drop" target keyword, only it jumps to REJECT instead of DROP. This means the packet is discarded (just as with DROP), but the sender is notified using ICMP (by default, your machine will send an ICMP-packet of type "icmp-port-unreachable"). Because of how iptables handles the REJECT target, you can only use it in contexts where the table is "filter". Optionally, you can follow "reject" with the keyword "with", and then use one of the following rejection types: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Type !style="background:#ffdead;"|Description |- | icmp-host-prohibited | will send an ICMP-message "host prohibited" |- | icmp-host-unreachable | will send an ICMP-message "host unreachable" |- | icmp-net-prohibited | will send an ICMP-message "net prohibited" |- | icmp-net-unreachable | will send an ICMP-message "net unreachable" |- | icmp-port-unreachable | DEFAULT; will send an ICMP-message "port unreachable" |- | icmp-proto-unreachable | DEFAULT; will send an ICMP-message "protocol unreachable" |- | tcp-reset | will send a TCP reset, a packet with the RST flag set (as a response to a TCP packet only) |- | host-prohib | synonymous to icmp-host-prohibited |- | host-unreach | synonymous to icmp-host-unreachable |- | net-prohib | synonymous to icmp-net-prohibited |- | net-unreach | synonymous to icmp-net-unreachable |- | port-unreach | synonymous to icmp-port-unreachable |- | proto-unreach | synonymous to icmp-proto-unreachable |- |} If you don’t specify "with <type>", then netfilter will assume icmp-port-unreachable. Thus, should you want to reject a packet in context filter INPUT (and log it) with reason net-prohib, you’d use reject with net-prohib log –p tcp –i eth0 --dport 22 Iceditch works this out to iptables –t filter –A INPUT –p tcp –i eth0 –-dport 22 –-jump LOG \ --log-prefix INPUT_REJECT_with_net-prohib: iptables –t filter –A INPUT –p tcp –i eth0 –-dport 22 \ –-jump REJECT –-reject-with net-prohib –p tcp –i eth0 –-dport 22 Note: RFC behavior is that unbound TCP ports return resets on connections, and unbound UDP ports return ICMP port unreachable. If you want to make your firewall less obtrusive, then do that. Your filtered ports will then be (at least in that respect) indistinguishable from unfiltered, unbound ports. ==Target keyword: route== '''''route {<iface>|<ifaceindex>} [log [msg <message>]] <matches>'''''<br> The ''route'' target lets you route a received packet through an interface or towards a host, even if the regular destination of the packet is the router itself. The ROUTE target is also able to change the incoming interface of a packet. Packets are directly put on the wire and do not traverse any other table.<br> ''route'' takes one mandatory option, which may be either the interface name over which to route the packet that matches the <matches>, or the index number of that interface (based on the order in /proc/net/dev). Iceditch is pretty lazy in how to interpret that option: if it's all numerals, Iceditch treats it as the interface index number, if it contains any other character, it is considered the interface name (e.g. ''eth0''); and no sanity check is performed on the specified <iface|ifaceindex>. == Target keyword: same== '''''same [to <a1[-a2]> [to <a3[-a4]>] ] [nodest] [log [msg <message>] ] <matches>'''''<br> ''same'' only works in the nat table, in the POSTROUTING chain. It is very closely related to ''snat'' (see below), because it does virtually the same thing. Basically, the ''same'' target will try to always use the same outgoing IP address for all connections initiated by a single host on your network. For example, say you have one "internal" /24 network (192.168.1.0) and 3 "external" IP addresses (10.5.6.11-13) on your firewall/router machine. Now, if internal machine 192.168.1.20 went out through the .11 address the first time, then the firewall will try to keep that machine always going out through that same IP address. So basically ''same'' might be a better fit than ''snat'' if you have multiple external IP addresses.<br> However, there is also functionality lacking in ''same'' that ''snat'' has, namely the specification of (TCP and UDP) ports or port ranges to use for the NATting operation. See ''snat'' for its port possibilities.<br> Furthermore, ''same'' has an extra option that ''snat'' does not have: under normal action, the ''same'' target is calculating the followup connections based on both destination and source IP addresses. Using the ''nodest'' option (which corresponds with --nodst in the actual IPtables command), it uses only the source IP address to find out which outgoing IP the NAT function should use for the specific connection. Without this argument, it uses a combination of the destination and source IP address. == Target keyword: snat== '''''snat [to <a1[-a2][:p1-p2]]> [to <a3[-a4][:p3-p4]]>] ] [log [msg <message>] ] <matches>'''''<br> This keyword is only valid in the chain POSTROUTING, table nat. And ofcourse, source NATting does you little good if you haven't enabled forwarding (e.g. use this machine as a router for other machines on your network).<br> Calling snat with the right parameters will create a Source NATting rule for you, whereby a packet matching the <matches> will be source NATted using the source IP address ''a1'' (or the range ''a1-a2''). Ofcourse, ''a1[-a2]'' should be valid IP address(es) of the firewalling machine.<br> Furthermore, if a port range ''p1-p2'' is specified, then you'll limit the range of ports that ''snat'' will use outbound (only valid for TCP or UDP packets).<br> Finally, it is possible to specify ''multiple'' IP address ranges and port ranges, using multiple ''to <a1[-a2][:p1-p2]]'' declarations in succession.<br> An example would be: context "POSTROUTING" "nat" snat to $inetIP -o $inetIF ! --src $inetIP If the variable ''$inetIP'' contains your public IP (e.g. 212.238.151.72), and ''$inetIF'' your interface connected to the Internet (e.g. ''eth0''), then this rule would expand to iptables -A POSTROUTING -t nat -o eth0 ! --src 212.238.151.72 -j SNAT --to-source 212.238.151.72 This would cause Iceditch to source NAT any outbound packet that is NOT sent by your firewall itself; in effect your server is now a nice fullblown NAT router for all machines on your private network. 0ec4eade8485e09e1e362eef367458c065e8ed54 0 1441 1624 1522 2008-08-23T09:09:04Z 93.174.93.224 0 0 wikitext text/x-wiki 6mo1zv <a href="http://gsunrflilast.com/">gsunrflilast</a>, [url=http://mywflokewgoi.com/]mywflokewgoi[/url], [link=http://opeskwriobcx.com/]opeskwriobcx[/link], http://ontphwmryveb.com/ 353e326bcb123dba0633ec9d5290c7cadb400bb3 1625 1624 2008-08-23T11:25:47Z Saruman! 2 Reverted edits by [[Special:Contributions/93.174.93.224|93.174.93.224]] ([[User_talk:93.174.93.224|Talk]]); changed back to last version by [[User:Saruman!|Saruman!]] wikitext text/x-wiki ==Routes under Debian== When you need to add a networking route, there generally are two ways to do it: # manually adding a route at the command prompt: this means that the machine will "understand" the route for as long as it is running. However, when you reboot the machine, it will have "forgotten" the route. This is called a non-persistent route. # adding a route to the networking configuration files, so that it will be in place regardless of reboots or network restarts. This is called a persistent route. ===Manipulating non-persistent routes=== From the days of yore, the venerable ''route'' command enables us to view, add, change and delete routes. Its most known use is for printing the current routing table: #route -n Kernel IP routing table Destination Gateway Genmask Flags Metric Ref Use Iface 192.168.70.0 212.214.172.50 255.255.255.0 UG 0 0 0 eth1 192.168.67.0 * 255.255.255.0 U 0 0 0 eth0 212.214.172.0 * 255.255.255.0 U 0 0 0 eth1 default 212.214.172.1 0.0.0.0 UG 0 0 0 eth1 The addition of -n makes sure the ''route'' command does not try to substitute DNS names for IP addresses it knows. The second most used incarnation of ''route'' lies in the addition of a route, as has happened in the previous example. The route was added to the routing table using something like this: #route add -net 192.168.70.0 netmask 255.255.255.0 gw 212.214.172.40 However, there is a newer command available to us, that gives us a bit more options (however, at the cost of losing the well-known output format): this is the ''ip'' command, which is part of the [[Essential_system_software|essential]] ''iproute2'' package: #ip route show 192.168.70.0/24 via 212.214.172.50 dev eth1 src 192.168.67.10 192.168.67.0/24 dev eth0 proto kernel scope link src 192.168.67.10 212.214.172.0/24 dev eth1 proto kernel scope link src 212.214.172.50 default via 212.214.172.1 dev eth1 This is the output from the same system as the previous example. However, we see something interesting here: "ip" is capable of adding extra information to the route, like the first line shows (it's using "via"). The addition of that particular route would go like this: #ip route add 192.168.70.0/24 via 212.214.172.50 src 192.168.67.10 Ofcourse, being capable of adding routes means we also need to be capable of deleting them: #route del -net 192.168.70.0 netmask 255.255.255.0 #ip route del 192.168.70.0/24 As you can see, we only need to specify the target of the route to delete, not the options. ===Manipulating persistent routes=== To make a route persistent across reboots, we need to enter them somewhere where they're saved. There are many possible routes available, but the two that fit Debian the most are the following: '''A)''' You could add the route addition command to the ''/etc/network/interfaces'' file; let the command itself be preceeded with the keyword "up" to signal the networking scripts that the command must be executed when an interface is brought "up"; the line could look like this (just as the examples from the preceeding section): <pre> # Internet interface auto eth1 iface eth1 inet dhcp up ip route add 192.168.70.0/24 via 212.214.172.50 src 192.168.67.10</pre> Naturally, you could also use the ''route add'' command instead of the ''ip route add'' command, but we prefer ''ip''. Note: it matters --where-- in the ''interfaces'' file you put this line: it should be put in the same stanza as the interface it operates on. In this example, the external interface of the server is 212.214.172.50, which belongs with interface ''eth1''. Therefore, the "up" line appears in the stanza for ''eth1''. '''B)''' You could create a script that sets the route(s), and put it in the directory ''/etc/network/if-up.d''. Since all scripts that reside there get called when any interface goes "up", your route setting script would be called when ''any'' interface comes up, including ''lo''. This in turn means that a script for setting a route that belongs with a particular interface, should check on invocation which is the interface that goes up. At this moment in time, we don't employ any such script, so no example here, but if you look at the existing scripts in ''/etc/network/if-up.d'' you'll see how other programmers have done this. d64fade46ce781b1ef77477633ac34012011dd4f 1648 1625 2008-09-04T06:50:30Z 78.110.175.15 0 0 wikitext text/x-wiki DvASSS <a href="http://rknmksdkztxx.com/">rknmksdkztxx</a>, [url=http://zbxnklaifgxq.com/]zbxnklaifgxq[/url], [link=http://uppnzbojvtbo.com/]uppnzbojvtbo[/link], http://ohakgbxvmvqh.com/ 8bb02620c09b2921f0c1e044aec85fc967b0a76d 1649 1648 2008-09-04T06:58:36Z Saruman! 2 Reverted edits by [[Special:Contributions/78.110.175.15|78.110.175.15]] ([[User_talk:78.110.175.15|Talk]]); changed back to last version by [[User:Saruman!|Saruman!]] wikitext text/x-wiki ==Routes under Debian== When you need to add a networking route, there generally are two ways to do it: # manually adding a route at the command prompt: this means that the machine will "understand" the route for as long as it is running. However, when you reboot the machine, it will have "forgotten" the route. This is called a non-persistent route. # adding a route to the networking configuration files, so that it will be in place regardless of reboots or network restarts. This is called a persistent route. ===Manipulating non-persistent routes=== From the days of yore, the venerable ''route'' command enables us to view, add, change and delete routes. Its most known use is for printing the current routing table: #route -n Kernel IP routing table Destination Gateway Genmask Flags Metric Ref Use Iface 192.168.70.0 212.214.172.50 255.255.255.0 UG 0 0 0 eth1 192.168.67.0 * 255.255.255.0 U 0 0 0 eth0 212.214.172.0 * 255.255.255.0 U 0 0 0 eth1 default 212.214.172.1 0.0.0.0 UG 0 0 0 eth1 The addition of -n makes sure the ''route'' command does not try to substitute DNS names for IP addresses it knows. The second most used incarnation of ''route'' lies in the addition of a route, as has happened in the previous example. The route was added to the routing table using something like this: #route add -net 192.168.70.0 netmask 255.255.255.0 gw 212.214.172.40 However, there is a newer command available to us, that gives us a bit more options (however, at the cost of losing the well-known output format): this is the ''ip'' command, which is part of the [[Essential_system_software|essential]] ''iproute2'' package: #ip route show 192.168.70.0/24 via 212.214.172.50 dev eth1 src 192.168.67.10 192.168.67.0/24 dev eth0 proto kernel scope link src 192.168.67.10 212.214.172.0/24 dev eth1 proto kernel scope link src 212.214.172.50 default via 212.214.172.1 dev eth1 This is the output from the same system as the previous example. However, we see something interesting here: "ip" is capable of adding extra information to the route, like the first line shows (it's using "via"). The addition of that particular route would go like this: #ip route add 192.168.70.0/24 via 212.214.172.50 src 192.168.67.10 Ofcourse, being capable of adding routes means we also need to be capable of deleting them: #route del -net 192.168.70.0 netmask 255.255.255.0 #ip route del 192.168.70.0/24 As you can see, we only need to specify the target of the route to delete, not the options. ===Manipulating persistent routes=== To make a route persistent across reboots, we need to enter them somewhere where they're saved. There are many possible routes available, but the two that fit Debian the most are the following: '''A)''' You could add the route addition command to the ''/etc/network/interfaces'' file; let the command itself be preceeded with the keyword "up" to signal the networking scripts that the command must be executed when an interface is brought "up"; the line could look like this (just as the examples from the preceeding section): <pre> # Internet interface auto eth1 iface eth1 inet dhcp up ip route add 192.168.70.0/24 via 212.214.172.50 src 192.168.67.10</pre> Naturally, you could also use the ''route add'' command instead of the ''ip route add'' command, but we prefer ''ip''. Note: it matters --where-- in the ''interfaces'' file you put this line: it should be put in the same stanza as the interface it operates on. In this example, the external interface of the server is 212.214.172.50, which belongs with interface ''eth1''. Therefore, the "up" line appears in the stanza for ''eth1''. '''B)''' You could create a script that sets the route(s), and put it in the directory ''/etc/network/if-up.d''. Since all scripts that reside there get called when any interface goes "up", your route setting script would be called when ''any'' interface comes up, including ''lo''. This in turn means that a script for setting a route that belongs with a particular interface, should check on invocation which is the interface that goes up. At this moment in time, we don't employ any such script, so no example here, but if you look at the existing scripts in ''/etc/network/if-up.d'' you'll see how other programmers have done this. d64fade46ce781b1ef77477633ac34012011dd4f 1673 1649 2008-09-09T14:57:05Z 200.63.42.113 0 /* Routes under Debian */ wikitext text/x-wiki eVcnMz <a href="http://cresiflrtusv.com/">cresiflrtusv</a>, [url=http://slyvbrlzyntg.com/]slyvbrlzyntg[/url], [link=http://dlljkmuifxni.com/]dlljkmuifxni[/link], http://dhhvrdtnykao.com/ bccb69a222a5952b96d992ffeb40c460eafad2fd 1674 1673 2008-09-09T20:18:08Z Saruman! 2 Reverted edits by [[Special:Contributions/200.63.42.113|200.63.42.113]] ([[User_talk:200.63.42.113|Talk]]); changed back to last version by [[User:Saruman!|Saruman!]] wikitext text/x-wiki ==Routes under Debian== When you need to add a networking route, there generally are two ways to do it: # manually adding a route at the command prompt: this means that the machine will "understand" the route for as long as it is running. However, when you reboot the machine, it will have "forgotten" the route. This is called a non-persistent route. # adding a route to the networking configuration files, so that it will be in place regardless of reboots or network restarts. This is called a persistent route. ===Manipulating non-persistent routes=== From the days of yore, the venerable ''route'' command enables us to view, add, change and delete routes. Its most known use is for printing the current routing table: #route -n Kernel IP routing table Destination Gateway Genmask Flags Metric Ref Use Iface 192.168.70.0 212.214.172.50 255.255.255.0 UG 0 0 0 eth1 192.168.67.0 * 255.255.255.0 U 0 0 0 eth0 212.214.172.0 * 255.255.255.0 U 0 0 0 eth1 default 212.214.172.1 0.0.0.0 UG 0 0 0 eth1 The addition of -n makes sure the ''route'' command does not try to substitute DNS names for IP addresses it knows. The second most used incarnation of ''route'' lies in the addition of a route, as has happened in the previous example. The route was added to the routing table using something like this: #route add -net 192.168.70.0 netmask 255.255.255.0 gw 212.214.172.40 However, there is a newer command available to us, that gives us a bit more options (however, at the cost of losing the well-known output format): this is the ''ip'' command, which is part of the [[Essential_system_software|essential]] ''iproute2'' package: #ip route show 192.168.70.0/24 via 212.214.172.50 dev eth1 src 192.168.67.10 192.168.67.0/24 dev eth0 proto kernel scope link src 192.168.67.10 212.214.172.0/24 dev eth1 proto kernel scope link src 212.214.172.50 default via 212.214.172.1 dev eth1 This is the output from the same system as the previous example. However, we see something interesting here: "ip" is capable of adding extra information to the route, like the first line shows (it's using "via"). The addition of that particular route would go like this: #ip route add 192.168.70.0/24 via 212.214.172.50 src 192.168.67.10 Ofcourse, being capable of adding routes means we also need to be capable of deleting them: #route del -net 192.168.70.0 netmask 255.255.255.0 #ip route del 192.168.70.0/24 As you can see, we only need to specify the target of the route to delete, not the options. ===Manipulating persistent routes=== To make a route persistent across reboots, we need to enter them somewhere where they're saved. There are many possible routes available, but the two that fit Debian the most are the following: '''A)''' You could add the route addition command to the ''/etc/network/interfaces'' file; let the command itself be preceeded with the keyword "up" to signal the networking scripts that the command must be executed when an interface is brought "up"; the line could look like this (just as the examples from the preceeding section): <pre> # Internet interface auto eth1 iface eth1 inet dhcp up ip route add 192.168.70.0/24 via 212.214.172.50 src 192.168.67.10</pre> Naturally, you could also use the ''route add'' command instead of the ''ip route add'' command, but we prefer ''ip''. Note: it matters --where-- in the ''interfaces'' file you put this line: it should be put in the same stanza as the interface it operates on. In this example, the external interface of the server is 212.214.172.50, which belongs with interface ''eth1''. Therefore, the "up" line appears in the stanza for ''eth1''. '''B)''' You could create a script that sets the route(s), and put it in the directory ''/etc/network/if-up.d''. Since all scripts that reside there get called when any interface goes "up", your route setting script would be called when ''any'' interface comes up, including ''lo''. This in turn means that a script for setting a route that belongs with a particular interface, should check on invocation which is the interface that goes up. At this moment in time, we don't employ any such script, so no example here, but if you look at the existing scripts in ''/etc/network/if-up.d'' you'll see how other programmers have done this. d64fade46ce781b1ef77477633ac34012011dd4f 1676 1674 2008-09-10T14:16:48Z 200.63.42.109 0 /* Routes under Debian */ wikitext text/x-wiki <a href= http://www.linktv.org/community/profile/Phentermine >Phentermine</a>, jfusbi, bde23d245268c1bcc7dfdd1376d3264ba2d2a222 1677 1676 2008-09-10T14:27:06Z Saruman! 2 Reverted edits by [[Special:Contributions/200.63.42.109|200.63.42.109]] ([[User_talk:200.63.42.109|Talk]]); changed back to last version by [[User:Saruman!|Saruman!]] wikitext text/x-wiki ==Routes under Debian== When you need to add a networking route, there generally are two ways to do it: # manually adding a route at the command prompt: this means that the machine will "understand" the route for as long as it is running. However, when you reboot the machine, it will have "forgotten" the route. This is called a non-persistent route. # adding a route to the networking configuration files, so that it will be in place regardless of reboots or network restarts. This is called a persistent route. ===Manipulating non-persistent routes=== From the days of yore, the venerable ''route'' command enables us to view, add, change and delete routes. Its most known use is for printing the current routing table: #route -n Kernel IP routing table Destination Gateway Genmask Flags Metric Ref Use Iface 192.168.70.0 212.214.172.50 255.255.255.0 UG 0 0 0 eth1 192.168.67.0 * 255.255.255.0 U 0 0 0 eth0 212.214.172.0 * 255.255.255.0 U 0 0 0 eth1 default 212.214.172.1 0.0.0.0 UG 0 0 0 eth1 The addition of -n makes sure the ''route'' command does not try to substitute DNS names for IP addresses it knows. The second most used incarnation of ''route'' lies in the addition of a route, as has happened in the previous example. The route was added to the routing table using something like this: #route add -net 192.168.70.0 netmask 255.255.255.0 gw 212.214.172.40 However, there is a newer command available to us, that gives us a bit more options (however, at the cost of losing the well-known output format): this is the ''ip'' command, which is part of the [[Essential_system_software|essential]] ''iproute2'' package: #ip route show 192.168.70.0/24 via 212.214.172.50 dev eth1 src 192.168.67.10 192.168.67.0/24 dev eth0 proto kernel scope link src 192.168.67.10 212.214.172.0/24 dev eth1 proto kernel scope link src 212.214.172.50 default via 212.214.172.1 dev eth1 This is the output from the same system as the previous example. However, we see something interesting here: "ip" is capable of adding extra information to the route, like the first line shows (it's using "via"). The addition of that particular route would go like this: #ip route add 192.168.70.0/24 via 212.214.172.50 src 192.168.67.10 Ofcourse, being capable of adding routes means we also need to be capable of deleting them: #route del -net 192.168.70.0 netmask 255.255.255.0 #ip route del 192.168.70.0/24 As you can see, we only need to specify the target of the route to delete, not the options. ===Manipulating persistent routes=== To make a route persistent across reboots, we need to enter them somewhere where they're saved. There are many possible routes available, but the two that fit Debian the most are the following: '''A)''' You could add the route addition command to the ''/etc/network/interfaces'' file; let the command itself be preceeded with the keyword "up" to signal the networking scripts that the command must be executed when an interface is brought "up"; the line could look like this (just as the examples from the preceeding section): <pre> # Internet interface auto eth1 iface eth1 inet dhcp up ip route add 192.168.70.0/24 via 212.214.172.50 src 192.168.67.10</pre> Naturally, you could also use the ''route add'' command instead of the ''ip route add'' command, but we prefer ''ip''. Note: it matters --where-- in the ''interfaces'' file you put this line: it should be put in the same stanza as the interface it operates on. In this example, the external interface of the server is 212.214.172.50, which belongs with interface ''eth1''. Therefore, the "up" line appears in the stanza for ''eth1''. '''B)''' You could create a script that sets the route(s), and put it in the directory ''/etc/network/if-up.d''. Since all scripts that reside there get called when any interface goes "up", your route setting script would be called when ''any'' interface comes up, including ''lo''. This in turn means that a script for setting a route that belongs with a particular interface, should check on invocation which is the interface that goes up. At this moment in time, we don't employ any such script, so no example here, but if you look at the existing scripts in ''/etc/network/if-up.d'' you'll see how other programmers have done this. d64fade46ce781b1ef77477633ac34012011dd4f 1678 1677 2008-09-10T19:58:06Z 200.63.42.111 0 /* Routes under Debian */ wikitext text/x-wiki <a href= http://www.carspace.com/blogs/Phentermine/ >Phentermine</a>, >:-OO, 9be17d6adf75dc36894f9eb344bed6ef17a7969a 1679 1678 2008-09-10T20:10:03Z Saruman! 2 Reverted edits by [[Special:Contributions/200.63.42.111|200.63.42.111]] ([[User_talk:200.63.42.111|Talk]]); changed back to last version by [[User:Saruman!|Saruman!]] wikitext text/x-wiki ==Routes under Debian== When you need to add a networking route, there generally are two ways to do it: # manually adding a route at the command prompt: this means that the machine will "understand" the route for as long as it is running. However, when you reboot the machine, it will have "forgotten" the route. This is called a non-persistent route. # adding a route to the networking configuration files, so that it will be in place regardless of reboots or network restarts. This is called a persistent route. ===Manipulating non-persistent routes=== From the days of yore, the venerable ''route'' command enables us to view, add, change and delete routes. Its most known use is for printing the current routing table: #route -n Kernel IP routing table Destination Gateway Genmask Flags Metric Ref Use Iface 192.168.70.0 212.214.172.50 255.255.255.0 UG 0 0 0 eth1 192.168.67.0 * 255.255.255.0 U 0 0 0 eth0 212.214.172.0 * 255.255.255.0 U 0 0 0 eth1 default 212.214.172.1 0.0.0.0 UG 0 0 0 eth1 The addition of -n makes sure the ''route'' command does not try to substitute DNS names for IP addresses it knows. The second most used incarnation of ''route'' lies in the addition of a route, as has happened in the previous example. The route was added to the routing table using something like this: #route add -net 192.168.70.0 netmask 255.255.255.0 gw 212.214.172.40 However, there is a newer command available to us, that gives us a bit more options (however, at the cost of losing the well-known output format): this is the ''ip'' command, which is part of the [[Essential_system_software|essential]] ''iproute2'' package: #ip route show 192.168.70.0/24 via 212.214.172.50 dev eth1 src 192.168.67.10 192.168.67.0/24 dev eth0 proto kernel scope link src 192.168.67.10 212.214.172.0/24 dev eth1 proto kernel scope link src 212.214.172.50 default via 212.214.172.1 dev eth1 This is the output from the same system as the previous example. However, we see something interesting here: "ip" is capable of adding extra information to the route, like the first line shows (it's using "via"). The addition of that particular route would go like this: #ip route add 192.168.70.0/24 via 212.214.172.50 src 192.168.67.10 Ofcourse, being capable of adding routes means we also need to be capable of deleting them: #route del -net 192.168.70.0 netmask 255.255.255.0 #ip route del 192.168.70.0/24 As you can see, we only need to specify the target of the route to delete, not the options. ===Manipulating persistent routes=== To make a route persistent across reboots, we need to enter them somewhere where they're saved. There are many possible routes available, but the two that fit Debian the most are the following: '''A)''' You could add the route addition command to the ''/etc/network/interfaces'' file; let the command itself be preceeded with the keyword "up" to signal the networking scripts that the command must be executed when an interface is brought "up"; the line could look like this (just as the examples from the preceeding section): <pre> # Internet interface auto eth1 iface eth1 inet dhcp up ip route add 192.168.70.0/24 via 212.214.172.50 src 192.168.67.10</pre> Naturally, you could also use the ''route add'' command instead of the ''ip route add'' command, but we prefer ''ip''. Note: it matters --where-- in the ''interfaces'' file you put this line: it should be put in the same stanza as the interface it operates on. In this example, the external interface of the server is 212.214.172.50, which belongs with interface ''eth1''. Therefore, the "up" line appears in the stanza for ''eth1''. '''B)''' You could create a script that sets the route(s), and put it in the directory ''/etc/network/if-up.d''. Since all scripts that reside there get called when any interface goes "up", your route setting script would be called when ''any'' interface comes up, including ''lo''. This in turn means that a script for setting a route that belongs with a particular interface, should check on invocation which is the interface that goes up. At this moment in time, we don't employ any such script, so no example here, but if you look at the existing scripts in ''/etc/network/if-up.d'' you'll see how other programmers have done this. d64fade46ce781b1ef77477633ac34012011dd4f 1680 1679 2008-09-10T23:59:23Z 195.225.178.39 0 0 wikitext text/x-wiki KrDCcy <a href="http://awlxxniecfji.com/">awlxxniecfji</a>, [url=http://iiopwxthautk.com/]iiopwxthautk[/url], [link=http://njmqqdmuomqf.com/]njmqqdmuomqf[/link], http://pmtpdiftdmrb.com/ 5d8c46f95f8d0a9e0e7f0de7107a17f084b72090 1681 1680 2008-09-11T05:31:21Z Saruman! 2 Reverted edits by [[Special:Contributions/195.225.178.39|195.225.178.39]] ([[User_talk:195.225.178.39|Talk]]); changed back to last version by [[User:Saruman!|Saruman!]] wikitext text/x-wiki ==Routes under Debian== When you need to add a networking route, there generally are two ways to do it: # manually adding a route at the command prompt: this means that the machine will "understand" the route for as long as it is running. However, when you reboot the machine, it will have "forgotten" the route. This is called a non-persistent route. # adding a route to the networking configuration files, so that it will be in place regardless of reboots or network restarts. This is called a persistent route. ===Manipulating non-persistent routes=== From the days of yore, the venerable ''route'' command enables us to view, add, change and delete routes. Its most known use is for printing the current routing table: #route -n Kernel IP routing table Destination Gateway Genmask Flags Metric Ref Use Iface 192.168.70.0 212.214.172.50 255.255.255.0 UG 0 0 0 eth1 192.168.67.0 * 255.255.255.0 U 0 0 0 eth0 212.214.172.0 * 255.255.255.0 U 0 0 0 eth1 default 212.214.172.1 0.0.0.0 UG 0 0 0 eth1 The addition of -n makes sure the ''route'' command does not try to substitute DNS names for IP addresses it knows. The second most used incarnation of ''route'' lies in the addition of a route, as has happened in the previous example. The route was added to the routing table using something like this: #route add -net 192.168.70.0 netmask 255.255.255.0 gw 212.214.172.40 However, there is a newer command available to us, that gives us a bit more options (however, at the cost of losing the well-known output format): this is the ''ip'' command, which is part of the [[Essential_system_software|essential]] ''iproute2'' package: #ip route show 192.168.70.0/24 via 212.214.172.50 dev eth1 src 192.168.67.10 192.168.67.0/24 dev eth0 proto kernel scope link src 192.168.67.10 212.214.172.0/24 dev eth1 proto kernel scope link src 212.214.172.50 default via 212.214.172.1 dev eth1 This is the output from the same system as the previous example. However, we see something interesting here: "ip" is capable of adding extra information to the route, like the first line shows (it's using "via"). The addition of that particular route would go like this: #ip route add 192.168.70.0/24 via 212.214.172.50 src 192.168.67.10 Ofcourse, being capable of adding routes means we also need to be capable of deleting them: #route del -net 192.168.70.0 netmask 255.255.255.0 #ip route del 192.168.70.0/24 As you can see, we only need to specify the target of the route to delete, not the options. ===Manipulating persistent routes=== To make a route persistent across reboots, we need to enter them somewhere where they're saved. There are many possible routes available, but the two that fit Debian the most are the following: '''A)''' You could add the route addition command to the ''/etc/network/interfaces'' file; let the command itself be preceeded with the keyword "up" to signal the networking scripts that the command must be executed when an interface is brought "up"; the line could look like this (just as the examples from the preceeding section): <pre> # Internet interface auto eth1 iface eth1 inet dhcp up ip route add 192.168.70.0/24 via 212.214.172.50 src 192.168.67.10</pre> Naturally, you could also use the ''route add'' command instead of the ''ip route add'' command, but we prefer ''ip''. Note: it matters --where-- in the ''interfaces'' file you put this line: it should be put in the same stanza as the interface it operates on. In this example, the external interface of the server is 212.214.172.50, which belongs with interface ''eth1''. Therefore, the "up" line appears in the stanza for ''eth1''. '''B)''' You could create a script that sets the route(s), and put it in the directory ''/etc/network/if-up.d''. Since all scripts that reside there get called when any interface goes "up", your route setting script would be called when ''any'' interface comes up, including ''lo''. This in turn means that a script for setting a route that belongs with a particular interface, should check on invocation which is the interface that goes up. At this moment in time, we don't employ any such script, so no example here, but if you look at the existing scripts in ''/etc/network/if-up.d'' you'll see how other programmers have done this. d64fade46ce781b1ef77477633ac34012011dd4f 0 1409 1626 1518 2008-08-28T09:26:42Z Saruman! 2 [[Debian Etch base server]] moved to [[Debian Lenny base server]]: upgrade to Lenny info wikitext text/x-wiki <big>'''Debian Etch Base Server setup'''</big> ==Getting the hardware== {| class="wikitable" border="1" |- |Note: in the following we're assuming you'll be assembling an x86 or x64 type of machine, as it has about the best price/performance ratio you could wish. Hardware costs for other platforms, e.g. IBM's Series p or HP 9000, can be much higher, while platforms like ARM are just not very powerful. Also, the availability of components and of help can be less than with the ubiquietous x86/x64 platforms. |} Naturally, before we can begin to install the operating system, we need to obtain the necessary hardware. Which hardware you require depends on what you want the server for; a testserver on which you will test only a single feature for a short while does not need the same quality of hardware as does a server that's supposed to act as a homeserver for many tasks for a long time. We'll assume your server will be like ours: a home server that must perform many tasks with sufficient performance for a few users, that's reliable and will last for a couple of years. So build or obtain a server with at least the following hardware: * a spacious casing with big, quiet cooling fans, like the [http://www.coolermaster.com/products/product.php?act=detail&id=317 one we have]; * an efficient, heavy-duty power supply that's rated high enough for your devices, and has a decent efficiency. For example, a [http://www.corsair.com/products/power_supplies.aspx Corsair HX520] power supply; * a server class motherboard, e.g. an [http://www.intel.com/products/server/index.htm?iid=home+hdr_nav2_server Intel] or [http://uk.asus.com/products.aspx?l1=9&l2=39&l3=263 AMD] based single-processor motherboard. DO NOT go for the cheapest motherboard you can find: if you pay peanuts, that's what you get. Server class motherboards have the quality, stability and durability you'll need from it, and usually also most of the needed peripherals, like multiple ethernet network cards on-board. Usually a Linux server doesn not require much in the way of video performance (and the screen will be used rarely, if ever), so any old integrated graphics will do. * a matching CPU - or multiple, if you think you need the power and the selected motherboard has the sockets. * a CD-ROM- or DVD-player * ''multiple'' harddisks - you'll want redundancy, because every harddisk fails at some time. The drive with your data on it will fail fatally when it is most inconvenient to you, and any data on it that you consider valuable will likely be lost forever. To make Murphy's work somewhat harder for him, we're going to store our data redundantly, so that if any drive in the server fails, we'll not lose our data or our server. Thus, get yourself at least two harddisks for your operating system, at least 40GiB in size (don't think you'll be able to buy smaller ones nowadays), and spanking new (NEVER use old harddisks for your production server, new ones are just too cheap to run that risk!). * (multipe) network card(s) (NICs) if your motherboard does not have enough NICs integrated on-board. You'll want a NIC for your network, and another one for your Internet connection; and possible a third one for the wireless segment of your network. Now build a machine out of the above, or have someone build it for you. ==Preparation of the hardware== (Note: in the following we're again assuming you're running an x86/x64 type of machine. Hardware requirements and preparation for other platforms, e.g. IBM's Series p or HP 9000, can differ significantly) Next, check the assembled hardware: * is the configuration complete? If it does not have a CD/DVDplayer from which it can boot, then installing the software gets more difficult - at least get an USB external DVDdrive or something like that. * are all components connected properly (memory DIMMs seated correctly in their sockets, AGP card inserted correctly into the AGP slot, et cetera) and are all cable connections made (multiple power cables to the motherboard, one power cable plus one data cable to each hard disk, etcetera)? Following this, you may hook up the machine. It's going to need power, and you will need at least a keyboard and a monitor attached. And if you want to use a Graphic User Interface to install, a mouse is required also. When you've ensured that everything is safe, you can turn on the machine, and continue to check it: * do all fans start to run when you turn on the machine? (if not, then '''quickly''' turn off your machine and correct the problem!) * does/do the hard disk(s) spin up? * do the power button and reset button operate correctly? * are the power led, HDD led and other display gadgetry functional? * when you let the machine power up, does it emit a single beep? And does it then show a Power-On Self Test screen (POST)? * Does it show the correct amount of memory in the POST screen? The correct number & speed of the CPU(s)? * Does the machine recognise all controller cards (SCSI, S-ATA etc)? And all attached DVD-drives and hard disks? * are all BIOSes/firmwares up to date? * If you have a hardware RAID controller, are your RAID arrays built already? * does the machine attempt to boot from at least the hard disk? ...et cetera. If there is any problem, or you want to update the BIOS or firmwares, it's best to do it before the operating system is installed. This Wiki, however, is not the place (yet) to get the information on how to accomplish these type of tasks. The last steps in the preparation of the hardware, are * to ensure that the machine can boot from CD/DVD, so that you can start installing Debian from it. It is possible to install Debian over the network, but that requires setting up a [http://www.debian-administration.org/articles/478 PXE Boot server] which is (currently) outside the scope of this wiki. * to connect the hardware to the Internet, so that it can get all required updates etcetera; please do ''not'' connect the box ''straight'' to the Internet, but make sure that it's safely behind a firewall, or failing that, a NAT router. By now the system should be almost ready to receive it's Operating System. But first we have an issue to tackle: that of redundancy. ==Software or hardware RAID== Your hard disks will fail. They absolutely will. It is never a question of "if", only of "when". So what will you do when the hard disk containing your complete operating system fails (besides pulling your hair out, that is)? What we propose is this: hard disks are pretty cheap nowadays, so let's use [http://en.wikipedia.org/wiki/Redundant_array_of_independent_disks RAID technology] to make our hard drive space resilient against failure of a whole drive. So first make sure that you have ''two'' disks of equal size instead of only one. Had you already been planning to use multiple disks already, then make sure you have at least ''one'' disk more than your space requirements prescribe; the space on that extra drive will provide the needed redundancy. Next, [[RAID fundamentals under Linux | click here]] to learn a bit more about RAID, to make the decision to use hardware-based and/or software-based RAID, and to plan your RAID arrays. In this example, we'll assume you're using hardware RAID on a RAID controller that's supported by the Debian installation software. This means that the installation software will "see" your RAID array(s) and present them as usable drives. ==Planning your network names== If your machine must become a part of an existing network, then it's almost certain that you already have a DNS domain in place; in that case: obtain the DNS suffix your machine will get (the DNS domain your machine will "belong" to). However, it's also possible that this machine is going to be the first machine in your new network, in which case the whole issue of DNS suffixes is wide open. If you need more information on DNS, go [[http://www.isc.org/sw/bind/arm95/Bv9ARM-all.html#id2564824 here]]. For now we'll assume you have (or will quickly obtain) a working knowledge of the DNS system. Here is our tip on choosing a DNS domain for your home network: * do '''not''' use a publicly registered domain name (e.g. "cocacola.com") for any machine that's not primarily intended to serve the public on the Internet; * for machines serving a private network, we urge you to use Top Level Domain name "lan" (to signify your machine is on a Local Area Network or LAN) * for the Domain Name itself, we suggest you use a level 2 name, like "saruman.lan", and not a level 3 name, like "mister.saruman.lan". This is only a short section on DNS, but remember that once a proper DNS system is in place, it's pretty much work to change it. At any rate, this section has most likely showed you that you need to put some thought into the DNS Domain Name design of your home network. OK, with this out of the way, we can get to installing the OS. ==Operating System installation== To install an Operating System (OS), it's kinda instrumental that you have one. Here, we're going to use [http://www.debian.org/intro/about Debian], the biggest [http://www.debian.org/intro/about#free Free] OS that we know of. Free stands for Freedom, but incidentally that Freedom also means it's gratis, an appealing aspect of Free. To get your own copy of Debian, go to their [http://www.debian.org/distrib/ download site] and obtain the latest [http://www.debian.org/releases/ Stable] image - in this wiki it's Debian 4.0, or "Etch" as it's also known. Besides the choice which release of Debian you want to run, you also have to know for which platform you're downloading (in our case: either ''amd64'' or ''i386'' depending on your hardware platform) and what kind of install you wish - if you have a working, fast Internet connection available at the time of install, then we recommend getting the [[http://www.debian.org/CD/netinst/ netinst] CD image; it's a relatively small CD, that'll be able to get you going, but gets most of the software you'll need straight from the 'net at install time. So, since in the example at hand we're installing on a Xeon server on which we wish to install 32-bits software, we'll download [http://cdimage.debian.org/debian-cd/4.0_r3/i386/iso-cd/debian-40r3-i386-netinst.iso debian-40r3-i386-netinst.iso], the latest netinstall image at the time of writing. Burn this to a CD-recordable and boot your prepared hardware platform from this CD. After booting from the CD, a friendly prompt invites you to indicate how you want to boot the CD. Your choices are listed under &lt;F3&gt;; we're going to use the standard Command Line installation, so we type "install"&lt;enter&gt; or just simply &lt;enter&gt;. {| class="wikitable" border="1" |- |We could easily use "installgui", in which case we'd have a nice fresh Graphical User Interface for our installation. ''We're'' not going to, because we're real men, and [http://isg.ee.ethz.ch/tools/realmen/ Real Men Don't Click]. Also, we've found that from the GUI it's hard to switch to a second console and then back. We could also opt for "expert" as installation method, because it gives a much finer grain of control, but we usually don't need that control, and can do without the barrage of extra questions that the "expert" installation method pose. Finally, we could opt for "expertgui", where we have both the barrage of extra questions ''and'' the GUI, neither of which we need. |} After the Linux kernel finishes initializing the machine, a simple text-based installer appears that immediately starts asking questions. Answer them according to your needs. Our example system uses the following choices: * Language: english * country: other &gt; Netherlands * keymap: American English (since we have a keyboard with US layout) Some installation software loads, and we get to the next phase: if you have multiple NICs in your machine (which we believe you ''should'' have!!), and if they're detected properly, then you're required to indicate which of the detected network interface cards (NIC) is going to be the "primary" NIC. {| class="wikitable" border="1" |- |Here, trouble could begin. If your machine has network cards that are '''not''' supported, then you'll see '''no''' cards here - but then how are you going to do a NetInstall? A solution would be to (temporarily) install a NIC that ''is'' supported, like a cheap Realtek card, or an old 3Com 905 card. Then, when the whole system is installed, up and running, you could compile a new kernel that contains support for your actual NICs, and when these work, remove the temporary NIC. For now, we'll assume that at least one of your NICs is recognised properly by the Debian installation routine. |} Select the card that's connected and has (indirect) access to Internet (again: it should ''not'' be connected straight to the wild wild web, but sit safely behind a firewall, at least until we've installed our own firewall); if at all possible, let it be the NIC that'll be connected to your home network itself, on the ''inside'' of your server. Let's assume that this NIC is designated ''eth0'' by the Debian installation. This card will now be configured using DHCP, so if you're on a network with a DHCP-server, the network will work straight away. If it's not, you can either configure the network manually or fix your DHCP-server and connection between it and ''eth0''. Next is one of the hardest questions that any OS installation is going to ask you: what will be the host name of the system? You could change it at any time in the future, but with lots of hassle, so you better choose wisely. Here are our tips: * do '''not''' name your machine after the user that's going to use it, e.g. "bernie-pc" (at some time in the future, Bernie's machine will be moved to Alice, so then Alice is working on "bernie-pc" which makes the situation quite unclear); * do '''not''' name your machine after the department or workgroup that's using it most, e.g. "accounting-srv" (same reasoning); * do '''not''' name your machine after it's main function, e.g. "printserver" (at some time in the future, the main function is moved to another machine, and/or an alternative function will become the main function of the machine); * do '''not''' name your machine after it's location, e.g. "srv-boston" (at some time in the future, the box will be moved to another location); * do '''not''' name your machine after it's hardware configuration, e.g. "ibmx346" (at some time in the future, either another xSeries x346 will be wheeled in, or the machine will be upgraded to accomodate increased use or overcome hardware problems - your "ibmx346" could suddenly be running on an xSeries x3650). What we feel are safe names for ''any'' machine in your network are true names, perhaps linked to a common theme: names of European cities, names of movie characters, names of countries or holiday destinations et cetera. Immediately following comes the question of the Domain Name. This is about a DNS domain, so effectively the installation program is asking which DNS suffix the host name should have; if the DHCP-server already provided something it'll be suggested, but you can override it if need be. In the preparatory phase, you'll have decided on continuation of your current DNS schema, or starting a new one. Either way, put the chosen DNS suffix in and press &lt;enter&gt;. ==Partitioning== Next comes the question of partitioning, or how to divide the available disk space into chunks for the server to use. This is a tricky subject, because if you put all storage space into one partition, then some day a runaway process will fill up the entire disk with useless logs, and the system will crash. On the other hand, if you divvy up all space into little chunks, then some application is going to need space in one of those partitions where there is none, even though there may be plenty in other partitions. To prevent both problems from occuring, we're going to use [http://tldp.org/HOWTO/LVM-HOWTO/whatisvolman.html Logical Volume Management (LVM)] so that we can provision enough space to start our server, but keep some space in reserve to apply when needed, where it'll be needed. So, we at Saruman.biz have put together a recommended standard partitioning scheme. The basis is this: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Partition !style="background:#ffdead;"|MD !style="background:#ffdead;"|LVG !style="background:#ffdead;"|LV-name !style="background:#ffdead;"|Size <br> (physical machine) !style="background:#ffdead;"|Size (VM) !style="background:#ffdead;"|File System !style="background:#ffdead;"|Mount point |- | 1 | /dev/md0 | &nbsp; | &nbsp; | 100MiB | 100MiB | ext3 | /boot |- | 2 | /dev/md1 | &nbsp; | &nbsp; | 3GiB | 1GiB | ext3 | / |- | rowspan="7" valign="top" | 3 | rowspan="7" valign="top" | /dev/md2 | rowspan="7" valign="top" style="background:lightgrey"| system | style="background:lightgrey" | swap | 1GiB<ref name="swap">Rule of thumb: twice the size of the machine's RAM, but no less than 256MiB and no more than 2GiB</ref> | 256MiB<ref name="swap"/> | swap | &nbsp; |- | style="background:lightgrey" | var | 2GiB | 1GiB | ext3 | /var |- | style="background:lightgrey" | appslog | 3GiB | - | ext3 | /var/appslog |- | style="background:lightgrey" | home | 1GiB<ref name="home">Note that this heavily depends on the purpose of the machine; if it is not to house any users, then (almost) no space is needed for /home. But on the other hand if e.g. a virtual user is to be used for keeping mailstores, or other service users need home space, then /home needs to be big enough for that.</ref> | 512MiB<ref name="home"/> | ext3 | /home |- | style="background:lightgrey" | usr | 3GiB | 3GiB | ext3 | /usr |- | style="background:lightgrey" | tmp | 1GiB | 512MiB | ext3 | /tmp |- | style="background:lightgrey" | opt | 1GiB | - | ext3 | /opt |- ! colspan="4" style="text-align:right"| Total ! 18.1GiB ! 6.9GiB ! colspan="2" | |- |} As you can see, the partition table works as follows: we assume that we wind up with 3 partitions, either on three separate software RAID arrays (''md0'' through ''md2'') or on one single hardware RAID array (in which case the 2nd column ''MD'' does not apply). The size of the partitions depends on your machine's make: for standard physical machines the 5th column does sensible suggestions, even though you could choose to have different sizes and of course different divisions altogether. If your machine happens to be a virtual one, running inside a [http://www.vmware.com/products/server/ VMware Server] or [http://www.vmware.com/products/vi/esx/ VMware ESX host], or the like, then you might want to start out with more modest partitions. The same holds for small servers that must run off Flash drives. Anyways, we're now at the Debian installation screen that lets us partition our disks. We're ''not'' going to use any of the "guided" partitionings, we go for "manual". Choosing that brings us to a screen showing all drives that the installation routine has detected, and all partitions on those drives that the installer can "see". We're going to do some assuming here once more: let's assume the drive(s) on which you want to install are visible, and are empty (containing no other partitions). <references/> ===Software RAID partitioning=== If you're to use software RAID, you now have to select the free space on the first drive, press &lt;enter&gt;, and then tell what you want to do with the free space: create a new partition, tell which size you want it to be (see table above), give the type of partition (primary), and give where on the disk it'll sit (the beginning). Next, a screen comes up that details how the partition you're requesting will be created. Here we make some changes: under "use as" we're going to select "physical volume for RAID". This clears all the other options in this screen, except for the "bootable" flag, which must be "on" for the first partition that we'll mount as ''/boot''. Now select "Done setting up the partition". Next, go to the free space on the second disk, and do ''exactly'' the same, to create an identical physical volume for RAID - if it's the first partition, select the "bootable" flag as well (we'll want to be able to boot from this second disk if the first disk fails, right?). Then go back to the rest of the free space on the first disk, make the second physical volume for RAID, duplicate it on the second disk. Then, go back to the rest of the free space on the first disk, make the third physical volume for RAID, and again duplicate it on the second disk. If you now go back to the "partition disks" overview, you'll see all the partitions you've specified listed on their respective disks. But at the top an extra option has appeared, called "configure software RAID". When you now select this option, the installer will ask if it may write the changes you've made to disk. This actually creates the partition tables on the disks. ===Hardware RAID partitioning=== Now, if you have hardware RAID, then on your first (boot) disk just make 3 partitions, in the following manner: Select the free space on the intended boot disk, press &lt;enter&gt;, select "create a new partition", and fill out the desired size (100MB). Type is primary, location is beginning of the disk, and in the details of the partition, we only need to change the Mount point to "/boot", and set the Bootable flag to "On". Then we're "Done setting up this partition". The second partition is made the same way, but the desired size is 3GB, the Mount point is "/", and the Bootable flag remains off. Again, we're "Done setting up this partition". The third partition is again a primary partition, it takes up the entire rest of the disk, but the type is not ext3, but "physical volume for LVM". Again, we're "Done setting up this partition". But now from the main partitioner screen, we can access "Configure the Logical Volume Manager". The installer asks if it can write out the choices made to the disk, and then enters the LVM setup screen, which begins with a summary explaining that you have one Free Physical Volume, and nothing more. We now create a Volume Group (VG), which (in accordance to our partitioning standard) we'll call "system". In this VG, we'll add all Physical Volumes (being the one partition we've designated so in the previous step) using the space bar. Now we repeat the following process seven times: * select "Create Logical Volume" * select Volume Group "System" * give the LV Name (from the table, e.g. swap, var etc) * give the LV size (from the table, e.g. 1GB for swap etc) After this, we can select "Finish", the partitioner creates the seven LVs, and we're back at the partitioner screen, where there are now 7 extra "disks", with names such as ''LVM VG system, LV appslog - 3.2GB Linux device mapper''. Each of these "disks" has one block of empty space, which we now assign: seven times we repeat the following process: * select the unassigned chunk of empty space of an LV (e.g. appslog) and press &lt;enter&gt;; * Change "Use as: do not use" into the desired filesystem (ext3 - only the LV "swap" gets as filesystem type "swap area") * Change the mount point from "none" to the one corresponding with the name of the LV (note: the swap LV has no mountpoint; the appslog mountpoint must be entered manually as "/var/appslog") * If so desired, a label can be assigned to the partition (we usually don't) * select "Done setting up the partition" Once all this is done, we can look over the configuration once more, and then select "Finish partitioning and write changes to disk". A summary configuration screen will show, and we'll affirm with "yes" that these partitions can indeed be formatted. After some formatting screens flashing by (unless your partitions are particularly big, your system is particularly slow, or something goes wrong) the installation procedure continues. ==Final installer steps== Next comes one '''VERY''' important question: what to use as root password? We cannot stress this enough: choose a SAFE password! Do NOT go for an easy-to-remember one, go for STRONG and SAFE. There are tools to help you generate strong passwords, like [http://www.pctools.com/guides/password/ this page]: use them! We strongly suggest 10 characters or more, including letters, mixed case, and numbers, so something like ''SuCRe4hecH'' (do NOT use this, generate your own!). Next, give the full name of the principal user of this server (your own, we assume), give the login-name (your given name, we assume), and a corresponding password. Again, use a SAFE password. As long as you don't make your principal user equivalent to root, you might go for a slightly weaker password (8 characters instead of 10), but we rather suggest you make the password just as strong (and different from!) the root password. After entering the details of these two users "root" and "you", the Debian installer will ask you how it can contact the Debian archives, in the dialoge "configure the package manager". For the NetInstall version of Debian, this is as good as mandatory. So here, we say "yes, use a Network Mirror", and in the following list select the country in which we are (in our case: the Netherlands), so the installer can present us with a number of network mirrors "close by". We select ftp.nl.debian.org. Next screen: should you be behind a proxy server, then it's possible to specify that here. And then the test: the system will say "scanning the mirror..." and try to contact the specified mirror. If it does not succeed, then there is either a network problem, a problem with this box's network card, or you've not specified the mirror or proxy correctly - so fix it. You'll know the network mirror has succesfully been contacted when the next dialogue appears - currently "configuring popularity-contest". Answer this question as you please. And then one of the last "big" questions: Software Selection. In this dialogue, you can easily select bundles of software to be installed. The choices are currently: * Desktop environment * Web server * Print server * DNS server * File server * Mail server * SQL database * Laptop * Standard system (selected by default) We have to make a little confession here: we've never before used this option in the installer. In fact, we even deselect the Standard System, so as to minimize the number of software packages that the base installation of our server contains. This makes it more work to manually add packages later, but we feel it gives us more control and understanding of our systems. So if you are like us: deselect the Standard System entry, and select Continue. The next dialogue handles the installation of the [http://www.gnu.org/software/grub/ ''grub'' bootloader]. Unless your disks weren't empty and you're attempting to make this system multiboot, you'll most likely get a question if you'll allow the installer to install ''grub'' into the boot sector of the first hard disk. We'll confirm with "Yes". After the installation of grub is completed, the CD-ROM is ejected, and the system is ready to reboot into Debian Etch. Remove the CD and select "Continue" ==Finishing up the installation== The system should reboot into Debian. This means you should see the following boot sequence: * your machine's standard POST messages * then, a blue grub menu on a black screen, with two entries: ** Debian GNU/Linux, kernel 2.6.&lt;something&gt; ** Debian GNU/Linux, kernel 2.6.&lt;something&gt (single-user mode); * then, after a default time-out, the first grub option will go into effect, and the Linux kernel is started. Lots of cryptic messages in grey-on-black will scroll by, until the last few lines read: "Debian GNU/Linux 4.0 &lt;hostname&gt; tty1" and "&lt;hostname&gt; login:" If your system does not reach this login, and/or some horrible error messages appear anywhere in this boot sequence, then you've got some extra work ahead. For now we'll assume you've reached the login prompt without problem. Log in as the principal user (try to avoid logging in as root! That's BAD practice!). Once logged in, save a copy of the boot messages using ''sudo dmesg > boot.txt'' or whatever you like. Then look through the boot messages, e.g. with ''vi -R boot.txt''. Furthermore, [[APT_and_aptitude | use Aptitude]] to make sure ''all'' your software is updated to the latest version. Done! Your base system is ready. You probably now want to [[essential system software | install essential software]], [[roll your own kernel]] and [[connect your server to the Internet]]. 37ad5c211dac2e53119a3dff2be1098a41da6957 1629 1626 2008-08-28T10:09:34Z Saruman! 2 Lenny adaptations wikitext text/x-wiki <big>'''Debian Lenny Base Server setup'''</big> ==Getting the hardware== {| class="wikitable" border="1" |- |Note: in the following we're assuming you'll be assembling an x86 or x64 type of machine, as it has about the best price/performance ratio you could wish. Hardware costs for other platforms, e.g. IBM's Series p or HP 9000, can be much higher, while platforms like ARM are just not very powerful. Also, the availability of components and of help can be less than with the ubiquietous x86/x64 platforms. |} Naturally, before we can begin to install the operating system, we need to obtain the necessary hardware. Which hardware you require depends on what you want the server for; a testserver on which you will test only a single feature for a short while does not need the same quality of hardware as does a server that's supposed to act as a homeserver for many tasks for a long time. We'll assume your server will be like ours: a home server that must perform many tasks with sufficient performance for a few users, that's reliable and will last for a couple of years. So build or obtain a server with at least the following hardware: * a spacious casing with big, quiet cooling fans, like the [http://www.coolermaster.com/products/product.php?act=detail&id=317 one we have]; * an efficient, heavy-duty power supply that's rated high enough for your devices, and has a decent efficiency. For example, a [http://www.corsair.com/products/power_supplies.aspx Corsair HX520] power supply; * a server class motherboard, e.g. an [http://www.intel.com/products/server/index.htm?iid=home+hdr_nav2_server Intel] or [http://uk.asus.com/products.aspx?l1=9&l2=39&l3=263 AMD] based single-processor motherboard. DO NOT go for the cheapest motherboard you can find: if you pay peanuts, that's what you get. Server class motherboards have the quality, stability and durability you'll need from it, and usually also most of the needed peripherals, like multiple ethernet network cards on-board. Usually a Linux server doesn not require much in the way of video performance (and the screen will be used rarely, if ever), so any old integrated graphics will do. * a matching CPU - or multiple, if you think you need the power and the selected motherboard has the sockets. Furthermore, it pays to think about the energy use of your server CPU. For instance, you could choose an AMD Athlon X2 5600+, running at 2,8 Ghz and 89W maximum, but you can also go for an AMD Athlon X2 4850E, which is dualcore at 2,5GHz, but uses only 45W maximum - almost half of the former! And over a one year period, this choice can save up to 385 kWH. With electricity costing close to €0,20 per kWH (at least for some of us), that could save you €77,- a year. All I'm saying is: think about power use. * a CD-ROM- or DVD-player - although you might not need it any more after installation. * ''multiple'' harddisks - you'll want redundancy, because every harddisk fails at some time. The drive with your data on it will fail fatally when it is most inconvenient to you, and any data on it that you consider valuable will likely be lost forever. To make Murphy's work somewhat harder for him, we're going to store our data redundantly, so that if any drive in the server fails, we'll not lose our data or our server. Thus, get yourself at least two harddisks for your operating system, at least 40GiB in size (don't think you'll be able to buy smaller ones nowadays), and spanking new (NEVER use old harddisks for your production server, new ones are just too cheap to run that risk!). * (multipe) network card(s) (NICs) if your motherboard does not have enough NICs integrated on-board. You'll want a NIC for your network, and another one for your Internet connection; and possible a third one for the wireless segment of your network. Now build a machine out of the above, or have someone build it for you. ==Preparation of the hardware== (Note: in the following we're again assuming you're running an x86/x64 type of machine. Hardware requirements and preparation for other platforms, e.g. IBM's Series p or HP 9000, can differ significantly) Next, check the assembled hardware: * is the configuration complete? If it does not have a CD/DVDplayer from which it can boot, then installing the software gets more difficult - at least get an USB external DVDdrive or something like that. * are all components connected properly (memory DIMMs seated correctly in their sockets, AGP card inserted correctly into the AGP slot, et cetera) and are all cable connections made (multiple power cables to the motherboard, one power cable plus one data cable to each hard disk, etcetera)? Following this, you may hook up the machine. It's going to need power, and you will need at least a keyboard and a monitor attached. And if you want to use a Graphic User Interface to install, a mouse is required also. When you've ensured that everything is safe, you can turn on the machine, and continue to check it: * do all fans start to run when you turn on the machine? (if not, then '''quickly''' turn off your machine and correct the problem!) * does/do the hard disk(s) spin up? * do the power button and reset button operate correctly? * are the power led, HDD led and other display gadgetry functional? * when you let the machine power up, does it emit a single beep? And does it then show a Power-On Self Test screen (POST)? * Does it show the correct amount of memory in the POST screen? The correct number & speed of the CPU(s)? * Does the machine recognise all controller cards (SCSI, S-ATA etc)? And all attached DVD-drives and hard disks? * are all BIOSes/firmwares up to date? * If you have a hardware RAID controller, are your RAID arrays built already? * does the machine attempt to boot from at least the hard disk? ...et cetera. If there is any problem, or you want to update the BIOS or firmwares, it's best to do it before the operating system is installed. This Wiki, however, is not the place (yet) to get the information on how to accomplish these type of tasks. The last steps in the preparation of the hardware, are * to ensure that the machine can boot from CD/DVD, so that you can start installing Debian from it. It is possible to install Debian over the network, but that requires setting up a [http://www.debian-administration.org/articles/478 PXE Boot server] which is (currently) outside the scope of this wiki. * to connect the hardware to the Internet, so that it can get all required updates etcetera; please do ''not'' connect the box ''straight'' to the Internet, but make sure that it's safely behind a firewall, or failing that, a NAT router. By now the system should be almost ready to receive it's Operating System. But first we have an issue to tackle: that of redundancy. ==Software or hardware RAID== Your hard disks will fail. They absolutely will. It is never a question of "if", only of "when". So what will you do when the hard disk containing your complete operating system fails (besides pulling your hair out, that is)? What we propose is this: hard disks are pretty cheap nowadays, so let's use [http://en.wikipedia.org/wiki/Redundant_array_of_independent_disks RAID technology] to make our hard drive space resilient against failure of a whole drive. So first make sure that you have ''two'' disks of equal size instead of only one. Had you already been planning to use multiple disks already, then make sure you have at least ''one'' disk more than your space requirements prescribe; the space on that extra drive will provide the needed redundancy. Next, [[RAID fundamentals under Linux | click here]] to learn a bit more about RAID, to make the decision to use hardware-based and/or software-based RAID, and to plan your RAID arrays. In this example, we'll assume you're using hardware RAID on a RAID controller that's supported by the Debian installation software. This means that the installation software will "see" your RAID array(s) and present them as usable drives. ==Planning your network names== If your machine must become a part of an existing network, then it's almost certain that you already have a DNS domain in place; in that case: obtain the DNS suffix your machine will get (the DNS domain your machine will "belong" to). However, it's also possible that this machine is going to be the first machine in your new network, in which case the whole issue of DNS suffixes is wide open. If you need more information on DNS, go [[http://www.isc.org/sw/bind/arm95/Bv9ARM-all.html#id2564824 here]]. For now we'll assume you have (or will quickly obtain) a working knowledge of the DNS system. Here is our tip on choosing a DNS domain for your home network: * do '''not''' use a publicly registered domain name (e.g. "cocacola.com") for any machine that's not primarily intended to serve the public on the Internet; * for machines serving a private network, we urge you to use Top Level Domain name "lan" (to signify your machine is on a Local Area Network or LAN) * for the Domain Name itself, we suggest you use a level 2 name, like "saruman.lan", and not a level 3 name, like "mister.saruman.lan". This is only a short section on DNS, but remember that once a proper DNS system is in place, it's pretty much work to change it. At any rate, this section has most likely showed you that you need to put some thought into the DNS Domain Name design of your home network. OK, with this out of the way, we can get to installing the OS. ==Operating System installation== To install an Operating System (OS), it's kinda instrumental that you have one. Here, we're going to use [http://www.debian.org/intro/about Debian], the biggest [http://www.debian.org/intro/about#free Free] OS that we know of. Free stands for Freedom, but incidentally that Freedom also means it's gratis, an appealing aspect of Free. To get your own copy of Debian, go to their [http://www.debian.org/distrib/ download site] and obtain the latest [http://www.debian.org/releases/ Stable] image - in this wiki it's Debian 5.0, or "Lenny" as it's also known (although it wasn't stable at the time of writing this). Besides the choice which release of Debian you want to run, you also have to know for which platform you're downloading (in our case: either ''amd64'' or ''i386'' depending on your hardware platform) and what kind of install you wish - if you have a working, fast Internet connection available at the time of install, then we recommend getting the [[http://www.debian.org/CD/netinst/ netinst] CD image; it's a relatively small CD, that'll be able to get you going, but gets most of the software you'll need straight from the 'net at install time. In the example at hand we're installing on an AMD Athlon x2-based server, on which we wish to install 64-bits software. We'll download [http://cdimage.debian.org/cdimage/weekly-builds/amd64/iso-cd/debian-testing-amd64-CD-1.iso debian-testing-amd64-CD-1.iso], which is Lenny, not yet stable at the time of writing. Burn this to a CD-recordable and boot your prepared hardware platform from this CD. After booting from the CD, a friendly prompt invites you to indicate how you want to start installing (image 1). Your choices are listed under &lt;F3&gt;; we're going to use the standard Command Line installation, so we choose "install" and hit &lt;enter&gt;. {| class="wikitable" border="1" |- |We could easily use "Graphic install", in which case we'd have a nice fresh Graphical User Interface for our installation. ''We're'' not going to, because we're real men, and [http://isg.ee.ethz.ch/tools/realmen/ Real Men Don't Click]. Also, we've found that from the GUI it's hard to switch to a second console and then back. We could also go to the Advanced options (image 2), and opt for "Expert install" or "Graphical expert install" as installation method, because it gives a much finer grain of control; however we usually don't need that control, and can do without the barrage of extra questions that the "expert" installation method pose. |} After the Linux kernel finishes initializing the machine, a simple text-based installer appears (image 3) that immediately starts asking questions. Answer them according to your needs. Our example system uses the following choices: * Language: english * country: other &gt; Netherlands * keymap: American English (since we have a keyboard with US layout) Some installation software loads, and we get to the next phase: if you have multiple NICs in your machine (which we believe you ''should'' have!!), and if they're detected properly, then you're required to indicate which of the detected network interface cards (NIC) is going to be the "primary" NIC. {| class="wikitable" border="1" |- |Here, trouble could begin. If your machine has only network cards that are '''not''' supported, then you'll see '''no''' cards here - but then how are you going to do a NetInstall? A solution would be to (temporarily) install a NIC that ''is'' supported, like a cheap Realtek card, or an old 3Com 905 card. Then, when the whole system is installed, up and running, you could compile a new kernel that contains support for your actual NICs, and when these work, remove the temporary NIC. For now, we'll assume that at least one of your NICs is recognised properly by the Debian installation routine. |} Select the card that's connected and has (indirect) access to Internet (again: it should ''not'' be connected straight to the wild wild web, but sit safely behind a firewall, at least until we've installed our own firewall); if at all possible, let it be the NIC that'll be connected to your home network itself, on the ''inside'' of your server. Let's assume that this NIC is designated ''eth0'' by the Debian installation. This card will now be configured using DHCP, so if you're on a network with a DHCP-server, the network will work straight away. If it's not, you can either configure the network manually or fix your DHCP-server and connection between it and ''eth0''. Next is one of the hardest questions that any OS installation is going to ask you: what will be the host name of the system? You could change it at any time in the future, but with lots of hassle, so you better choose wisely. Here are our tips: * do '''not''' name your machine after the user that's going to use it, e.g. "bernie-pc" (at some time in the future, Bernie's machine will be moved to Alice, so then Alice is working on "bernie-pc" which makes the situation quite unclear); * do '''not''' name your machine after the department or workgroup that's using it most, e.g. "accounting-srv" (same reasoning); * do '''not''' name your machine after it's main function, e.g. "printserver" (at some time in the future, the main function is moved to another machine, and/or an alternative function will become the main function of the machine); * do '''not''' name your machine after it's location, e.g. "srv-boston" (at some time in the future, the box will be moved to another location); * do '''not''' name your machine after it's hardware configuration, e.g. "ibmx346" (at some time in the future, either another xSeries x346 will be wheeled in, or the machine will be upgraded to accomodate increased use or overcome hardware problems - your "ibmx346" could suddenly be running on an xSeries x3650). What we feel are safe names for ''any'' machine in your network are true names, perhaps linked to a common theme: names of European cities, names of movie characters, names of countries or holiday destinations et cetera. Immediately following comes the question of the Domain Name. This is about a DNS domain, so effectively the installation program is asking which DNS suffix the host name should have; if the DHCP-server already provided something it'll be suggested, but you can override it if need be. In the preparatory phase, you'll have decided on continuation of your current DNS schema, or starting a new one. Either way, put the chosen DNS suffix in and press &lt;enter&gt;. ==Partitioning== Next comes the question of partitioning, or how to divide the available disk space into chunks for the server to use. This is a tricky subject, because if you put all storage space into one partition, then some day a runaway process will fill up the entire disk with useless logs, and the system will crash. On the other hand, if you divvy up all space into little chunks, then some application is going to need space in one of those partitions where there is none, even though there may be plenty in other partitions. To prevent both problems from occuring, we're going to use [http://tldp.org/HOWTO/LVM-HOWTO/whatisvolman.html Logical Volume Management (LVM)] so that we can provision enough space to start our server, but keep some space in reserve to apply when needed, where it'll be needed. So, we at Saruman.biz have put together a recommended standard partitioning scheme. The basis is this: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Partition !style="background:#ffdead;"|MD !style="background:#ffdead;"|LVG !style="background:#ffdead;"|LV-name !style="background:#ffdead;"|Size <br> (physical machine) !style="background:#ffdead;"|Size (VM) !style="background:#ffdead;"|File System !style="background:#ffdead;"|Mount point |- | 1 | /dev/md0 | &nbsp; | &nbsp; | 100MiB | 100MiB | ext3 | /boot |- | 2 | /dev/md1 | &nbsp; | &nbsp; | 3GiB | 1GiB | ext3 | / |- | rowspan="7" valign="top" | 3 | rowspan="7" valign="top" | /dev/md2 | rowspan="7" valign="top" style="background:lightgrey"| system | style="background:lightgrey" | swap | 1GiB<ref name="swap">Rule of thumb: twice the size of the machine's RAM, but no less than 256MiB and no more than 2GiB</ref> | 256MiB<ref name="swap"/> | swap | &nbsp; |- | style="background:lightgrey" | var | 2GiB | 1GiB | ext3 | /var |- | style="background:lightgrey" | appslog | 3GiB | - | ext3 | /var/appslog |- | style="background:lightgrey" | home | 1GiB<ref name="home">Note that this heavily depends on the purpose of the machine; if it is not to house any users, then (almost) no space is needed for /home. But on the other hand if e.g. a virtual user is to be used for keeping mailstores, or other service users need home space, then /home needs to be big enough for that.</ref> | 512MiB<ref name="home"/> | ext3 | /home |- | style="background:lightgrey" | usr | 3GiB | 3GiB | ext3 | /usr |- | style="background:lightgrey" | tmp | 1GiB | 512MiB | ext3 | /tmp |- | style="background:lightgrey" | opt | 1GiB | - | ext3 | /opt |- ! colspan="4" style="text-align:right"| Total ! 18.1GiB ! 6.9GiB ! colspan="2" | |- |} As you can see, the partition table works as follows: we assume that we wind up with 3 partitions, either on three separate software RAID arrays (''md0'' through ''md2'') or on one single hardware RAID array (in which case the 2nd column ''MD'' does not apply). The size of the partitions depends on your machine's make: for standard physical machines the 5th column does sensible suggestions, even though you could choose to have different sizes and of course different divisions altogether. If your machine happens to be a virtual one, running inside a [http://www.vmware.com/products/server/ VMware Server] or [http://www.vmware.com/products/vi/esx/ VMware ESX host], or the like, then you might want to start out with more modest partitions. The same holds for small servers that must run off Flash drives. Anyways, we're now at the Debian installation screen that lets us partition our disks. We're ''not'' going to use any of the "guided" partitionings, we go for "manual". Choosing that brings us to a screen showing all drives that the installation routine has detected, and all partitions on those drives that the installer can "see". We're going to do some assuming here once more: let's assume the drive(s) on which you want to install are visible, and are empty (containing no other partitions). <references/> ===Software RAID partitioning=== If you're to use software RAID, you now have to select the free space on the first drive, press &lt;enter&gt;, and then tell what you want to do with the free space: create a new partition, tell which size you want it to be (see table above), give the type of partition (primary), and give where on the disk it'll sit (the beginning). Next, a screen comes up that details how the partition you're requesting will be created. Here we make some changes: under "use as" we're going to select "physical volume for RAID". This clears all the other options in this screen, except for the "bootable" flag, which must be "on" for the first partition that we'll mount as ''/boot''. Now select "Done setting up the partition". Next, go to the free space on the second disk, and do ''exactly'' the same, to create an identical physical volume for RAID - if it's the first partition, select the "bootable" flag as well (we'll want to be able to boot from this second disk if the first disk fails, right?). Then go back to the rest of the free space on the first disk, make the second physical volume for RAID, duplicate it on the second disk. Then, go back to the rest of the free space on the first disk, make the third physical volume for RAID, and again duplicate it on the second disk. If you now go back to the "partition disks" overview, you'll see all the partitions you've specified listed on their respective disks. But at the top an extra option has appeared, called "configure software RAID". When you now select this option, the installer will ask if it may write the changes you've made to disk. This actually creates the partition tables on the disks. ===Hardware RAID partitioning=== Now, if you have hardware RAID, then on your first (boot) disk just make 3 partitions, in the following manner: Select the free space on the intended boot disk, press &lt;enter&gt;, select "create a new partition", and fill out the desired size (100MB). Type is primary, location is beginning of the disk, and in the details of the partition, we only need to change the Mount point to "/boot", and set the Bootable flag to "On". Then we're "Done setting up this partition". The second partition is made the same way, but the desired size is 3GB, the Mount point is "/", and the Bootable flag remains off. Again, we're "Done setting up this partition". The third partition is again a primary partition, it takes up the entire rest of the disk, but the type is not ext3, but "physical volume for LVM". Again, we're "Done setting up this partition". But now from the main partitioner screen, we can access "Configure the Logical Volume Manager". The installer asks if it can write out the choices made to the disk, and then enters the LVM setup screen, which begins with a summary explaining that you have one Free Physical Volume, and nothing more. We now create a Volume Group (VG), which (in accordance to our partitioning standard) we'll call "system". In this VG, we'll add all Physical Volumes (being the one partition we've designated so in the previous step) using the space bar. Now we repeat the following process seven times: * select "Create Logical Volume" * select Volume Group "System" * give the LV Name (from the table, e.g. swap, var etc) * give the LV size (from the table, e.g. 1GB for swap etc) After this, we can select "Finish", the partitioner creates the seven LVs, and we're back at the partitioner screen, where there are now 7 extra "disks", with names such as ''LVM VG system, LV appslog - 3.2GB Linux device mapper''. Each of these "disks" has one block of empty space, which we now assign: seven times we repeat the following process: * select the unassigned chunk of empty space of an LV (e.g. appslog) and press &lt;enter&gt;; * Change "Use as: do not use" into the desired filesystem (ext3 - only the LV "swap" gets as filesystem type "swap area") * Change the mount point from "none" to the one corresponding with the name of the LV (note: the swap LV has no mountpoint; the appslog mountpoint must be entered manually as "/var/appslog") * If so desired, a label can be assigned to the partition (we usually don't) * select "Done setting up the partition" Once all this is done, we can look over the configuration once more, and then select "Finish partitioning and write changes to disk". A summary configuration screen will show, and we'll affirm with "yes" that these partitions can indeed be formatted. After some formatting screens flashing by (unless your partitions are particularly big, your system is particularly slow, or something goes wrong) the installation procedure continues. ==Final installer steps== Next comes one '''VERY''' important question: what to use as root password? We cannot stress this enough: choose a SAFE password! Do NOT go for an easy-to-remember one, go for STRONG and SAFE. There are tools to help you generate strong passwords, like [http://www.pctools.com/guides/password/ this page]: use them! We strongly suggest 10 characters or more, including letters, mixed case, and numbers, so something like ''SuCRe4hecH'' (do NOT use this, generate your own!). Next, give the full name of the principal user of this server (your own, we assume), give the login-name (your given name, we assume), and a corresponding password. Again, use a SAFE password. As long as you don't make your principal user equivalent to root, you might go for a slightly weaker password (8 characters instead of 10), but we rather suggest you make the password just as strong (and different from!) the root password. After entering the details of these two users "root" and "you", the Debian installer will ask you how it can contact the Debian archives, in the dialoge "configure the package manager". For the NetInstall version of Debian, this is as good as mandatory. So here, we say "yes, use a Network Mirror", and in the following list select the country in which we are (in our case: the Netherlands), so the installer can present us with a number of network mirrors "close by". We select ftp.nl.debian.org. Next screen: should you be behind a proxy server, then it's possible to specify that here. And then the test: the system will say "scanning the mirror..." and try to contact the specified mirror. If it does not succeed, then there is either a network problem, a problem with this box's network card, or you've not specified the mirror or proxy correctly - so fix it. You'll know the network mirror has succesfully been contacted when the next dialogue appears - currently "configuring popularity-contest". Answer this question as you please. And then one of the last "big" questions: Software Selection. In this dialogue, you can easily select bundles of software to be installed. The choices are currently: * Desktop environment * Web server * Print server * DNS server * File server * Mail server * SQL database * Laptop * Standard system (selected by default) We have to make a little confession here: we've never before used this option in the installer. In fact, we even deselect the Standard System, so as to minimize the number of software packages that the base installation of our server contains. This makes it more work to manually add packages later, but we feel it gives us more control and understanding of our systems. So if you are like us: deselect the Standard System entry, and select Continue. The next dialogue handles the installation of the [http://www.gnu.org/software/grub/ ''grub'' bootloader]. Unless your disks weren't empty and you're attempting to make this system multiboot, you'll most likely get a question if you'll allow the installer to install ''grub'' into the boot sector of the first hard disk. We'll confirm with "Yes". After the installation of grub is completed, the CD-ROM is ejected, and the system is ready to reboot into Debian Etch. Remove the CD and select "Continue" ==Finishing up the installation== The system should reboot into Debian. This means you should see the following boot sequence: * your machine's standard POST messages * then, a blue grub menu on a black screen, with two entries: ** Debian GNU/Linux, kernel 2.6.&lt;something&gt; ** Debian GNU/Linux, kernel 2.6.&lt;something&gt (single-user mode); * then, after a default time-out, the first grub option will go into effect, and the Linux kernel is started. Lots of cryptic messages in grey-on-black will scroll by, until the last few lines read: "Debian GNU/Linux 4.0 &lt;hostname&gt; tty1" and "&lt;hostname&gt; login:" If your system does not reach this login, and/or some horrible error messages appear anywhere in this boot sequence, then you've got some extra work ahead. For now we'll assume you've reached the login prompt without problem. Log in as the principal user (try to avoid logging in as root! That's BAD practice!). Once logged in, save a copy of the boot messages using ''sudo dmesg > boot.txt'' or whatever you like. Then look through the boot messages, e.g. with ''vi -R boot.txt''. Furthermore, [[APT_and_aptitude | use Aptitude]] to make sure ''all'' your software is updated to the latest version. Done! Your base system is ready. You probably now want to [[essential system software | install essential software]], [[roll your own kernel]] and [[connect your server to the Internet]]. efdd9238c99234499097d51cc3be750bba245c38 1630 1629 2008-08-28T12:19:56Z Saruman! 2 /* Software RAID partitioning */ added MD start screen wikitext text/x-wiki <big>'''Debian Lenny Base Server setup'''</big> ==Getting the hardware== {| class="wikitable" border="1" |- |Note: in the following we're assuming you'll be assembling an x86 or x64 type of machine, as it has about the best price/performance ratio you could wish. Hardware costs for other platforms, e.g. IBM's Series p or HP 9000, can be much higher, while platforms like ARM are just not very powerful. Also, the availability of components and of help can be less than with the ubiquietous x86/x64 platforms. |} Naturally, before we can begin to install the operating system, we need to obtain the necessary hardware. Which hardware you require depends on what you want the server for; a testserver on which you will test only a single feature for a short while does not need the same quality of hardware as does a server that's supposed to act as a homeserver for many tasks for a long time. We'll assume your server will be like ours: a home server that must perform many tasks with sufficient performance for a few users, that's reliable and will last for a couple of years. So build or obtain a server with at least the following hardware: * a spacious casing with big, quiet cooling fans, like the [http://www.coolermaster.com/products/product.php?act=detail&id=317 one we have]; * an efficient, heavy-duty power supply that's rated high enough for your devices, and has a decent efficiency. For example, a [http://www.corsair.com/products/power_supplies.aspx Corsair HX520] power supply; * a server class motherboard, e.g. an [http://www.intel.com/products/server/index.htm?iid=home+hdr_nav2_server Intel] or [http://uk.asus.com/products.aspx?l1=9&l2=39&l3=263 AMD] based single-processor motherboard. DO NOT go for the cheapest motherboard you can find: if you pay peanuts, that's what you get. Server class motherboards have the quality, stability and durability you'll need from it, and usually also most of the needed peripherals, like multiple ethernet network cards on-board. Usually a Linux server doesn not require much in the way of video performance (and the screen will be used rarely, if ever), so any old integrated graphics will do. * a matching CPU - or multiple, if you think you need the power and the selected motherboard has the sockets. Furthermore, it pays to think about the energy use of your server CPU. For instance, you could choose an AMD Athlon X2 5600+, running at 2,8 Ghz and 89W maximum, but you can also go for an AMD Athlon X2 4850E, which is dualcore at 2,5GHz, but uses only 45W maximum - almost half of the former! And over a one year period, this choice can save up to 385 kWH. With electricity costing close to €0,20 per kWH (at least for some of us), that could save you €77,- a year. All I'm saying is: think about power use. * a CD-ROM- or DVD-player - although you might not need it any more after installation. * ''multiple'' harddisks - you'll want redundancy, because every harddisk fails at some time. The drive with your data on it will fail fatally when it is most inconvenient to you, and any data on it that you consider valuable will likely be lost forever. To make Murphy's work somewhat harder for him, we're going to store our data redundantly, so that if any drive in the server fails, we'll not lose our data or our server. Thus, get yourself at least two harddisks for your operating system, at least 40GiB in size (don't think you'll be able to buy smaller ones nowadays), and spanking new (NEVER use old harddisks for your production server, new ones are just too cheap to run that risk!). * (multipe) network card(s) (NICs) if your motherboard does not have enough NICs integrated on-board. You'll want a NIC for your network, and another one for your Internet connection; and possible a third one for the wireless segment of your network. Now build a machine out of the above, or have someone build it for you. ==Preparation of the hardware== (Note: in the following we're again assuming you're running an x86/x64 type of machine. Hardware requirements and preparation for other platforms, e.g. IBM's Series p or HP 9000, can differ significantly) Next, check the assembled hardware: * is the configuration complete? If it does not have a CD/DVDplayer from which it can boot, then installing the software gets more difficult - at least get an USB external DVDdrive or something like that. * are all components connected properly (memory DIMMs seated correctly in their sockets, AGP card inserted correctly into the AGP slot, et cetera) and are all cable connections made (multiple power cables to the motherboard, one power cable plus one data cable to each hard disk, etcetera)? Following this, you may hook up the machine. It's going to need power, and you will need at least a keyboard and a monitor attached. And if you want to use a Graphic User Interface to install, a mouse is required also. When you've ensured that everything is safe, you can turn on the machine, and continue to check it: * do all fans start to run when you turn on the machine? (if not, then '''quickly''' turn off your machine and correct the problem!) * does/do the hard disk(s) spin up? * do the power button and reset button operate correctly? * are the power led, HDD led and other display gadgetry functional? * when you let the machine power up, does it emit a single beep? And does it then show a Power-On Self Test screen (POST)? * Does it show the correct amount of memory in the POST screen? The correct number & speed of the CPU(s)? * Does the machine recognise all controller cards (SCSI, S-ATA etc)? And all attached DVD-drives and hard disks? * are all BIOSes/firmwares up to date? * If you have a hardware RAID controller, are your RAID arrays built already? * does the machine attempt to boot from at least the hard disk? ...et cetera. If there is any problem, or you want to update the BIOS or firmwares, it's best to do it before the operating system is installed. This Wiki, however, is not the place (yet) to get the information on how to accomplish these type of tasks. The last steps in the preparation of the hardware, are * to ensure that the machine can boot from CD/DVD, so that you can start installing Debian from it. It is possible to install Debian over the network, but that requires setting up a [http://www.debian-administration.org/articles/478 PXE Boot server] which is (currently) outside the scope of this wiki. * to connect the hardware to the Internet, so that it can get all required updates etcetera; please do ''not'' connect the box ''straight'' to the Internet, but make sure that it's safely behind a firewall, or failing that, a NAT router. By now the system should be almost ready to receive it's Operating System. But first we have an issue to tackle: that of redundancy. ==Software or hardware RAID== Your hard disks will fail. They absolutely will. It is never a question of "if", only of "when". So what will you do when the hard disk containing your complete operating system fails (besides pulling your hair out, that is)? What we propose is this: hard disks are pretty cheap nowadays, so let's use [http://en.wikipedia.org/wiki/Redundant_array_of_independent_disks RAID technology] to make our hard drive space resilient against failure of a whole drive. So first make sure that you have ''two'' disks of equal size instead of only one. Had you already been planning to use multiple disks already, then make sure you have at least ''one'' disk more than your space requirements prescribe; the space on that extra drive will provide the needed redundancy. Next, [[RAID fundamentals under Linux | click here]] to learn a bit more about RAID, to make the decision to use hardware-based and/or software-based RAID, and to plan your RAID arrays. In this example, we'll assume you're using hardware RAID on a RAID controller that's supported by the Debian installation software. This means that the installation software will "see" your RAID array(s) and present them as usable drives. ==Planning your network names== If your machine must become a part of an existing network, then it's almost certain that you already have a DNS domain in place; in that case: obtain the DNS suffix your machine will get (the DNS domain your machine will "belong" to). However, it's also possible that this machine is going to be the first machine in your new network, in which case the whole issue of DNS suffixes is wide open. If you need more information on DNS, go [[http://www.isc.org/sw/bind/arm95/Bv9ARM-all.html#id2564824 here]]. For now we'll assume you have (or will quickly obtain) a working knowledge of the DNS system. Here is our tip on choosing a DNS domain for your home network: * do '''not''' use a publicly registered domain name (e.g. "cocacola.com") for any machine that's not primarily intended to serve the public on the Internet; * for machines serving a private network, we urge you to use Top Level Domain name "lan" (to signify your machine is on a Local Area Network or LAN) * for the Domain Name itself, we suggest you use a level 2 name, like "saruman.lan", and not a level 3 name, like "mister.saruman.lan". This is only a short section on DNS, but remember that once a proper DNS system is in place, it's pretty much work to change it. At any rate, this section has most likely showed you that you need to put some thought into the DNS Domain Name design of your home network. OK, with this out of the way, we can get to installing the OS. ==Operating System installation== To install an Operating System (OS), it's kinda instrumental that you have one. Here, we're going to use [http://www.debian.org/intro/about Debian], the biggest [http://www.debian.org/intro/about#free Free] OS that we know of. Free stands for Freedom, but incidentally that Freedom also means it's gratis, an appealing aspect of Free. To get your own copy of Debian, go to their [http://www.debian.org/distrib/ download site] and obtain the latest [http://www.debian.org/releases/ Stable] image - in this wiki it's Debian 5.0, or "Lenny" as it's also known (although it wasn't stable at the time of writing this). Besides the choice which release of Debian you want to run, you also have to know for which platform you're downloading (in our case: either ''amd64'' or ''i386'' depending on your hardware platform) and what kind of install you wish - if you have a working, fast Internet connection available at the time of install, then we recommend getting the [[http://www.debian.org/CD/netinst/ netinst] CD image; it's a relatively small CD, that'll be able to get you going, but gets most of the software you'll need straight from the 'net at install time. In the example at hand we're installing on an AMD Athlon x2-based server, on which we wish to install 64-bits software. We'll download [http://cdimage.debian.org/cdimage/weekly-builds/amd64/iso-cd/debian-testing-amd64-CD-1.iso debian-testing-amd64-CD-1.iso], which is Lenny, not yet stable at the time of writing. Burn this to a CD-recordable and boot your prepared hardware platform from this CD. After booting from the CD, a friendly prompt invites you to indicate how you want to start installing (image 1). Your choices are listed under &lt;F3&gt;; we're going to use the standard Command Line installation, so we choose "install" and hit &lt;enter&gt;. {| class="wikitable" border="1" |- |We could easily use "Graphic install", in which case we'd have a nice fresh Graphical User Interface for our installation. ''We're'' not going to, because we're real men, and [http://isg.ee.ethz.ch/tools/realmen/ Real Men Don't Click]. Also, we've found that from the GUI it's hard to switch to a second console and then back. We could also go to the Advanced options (image 2), and opt for "Expert install" or "Graphical expert install" as installation method, because it gives a much finer grain of control; however we usually don't need that control, and can do without the barrage of extra questions that the "expert" installation method pose. |} After the Linux kernel finishes initializing the machine, a simple text-based installer appears (image 3) that immediately starts asking questions. Answer them according to your needs. Our example system uses the following choices: * Language: english * country: other &gt; Netherlands * keymap: American English (since we have a keyboard with US layout) Some installation software loads, and we get to the next phase: if you have multiple NICs in your machine (which we believe you ''should'' have!!), and if they're detected properly, then you're required to indicate which of the detected network interface cards (NIC) is going to be the "primary" NIC. {| class="wikitable" border="1" |- |Here, trouble could begin. If your machine has only network cards that are '''not''' supported, then you'll see '''no''' cards here - but then how are you going to do a NetInstall? A solution would be to (temporarily) install a NIC that ''is'' supported, like a cheap Realtek card, or an old 3Com 905 card. Then, when the whole system is installed, up and running, you could compile a new kernel that contains support for your actual NICs, and when these work, remove the temporary NIC. For now, we'll assume that at least one of your NICs is recognised properly by the Debian installation routine. |} Select the card that's connected and has (indirect) access to Internet (again: it should ''not'' be connected straight to the wild wild web, but sit safely behind a firewall, at least until we've installed our own firewall); if at all possible, let it be the NIC that'll be connected to your home network itself, on the ''inside'' of your server. Let's assume that this NIC is designated ''eth0'' by the Debian installation. This card will now be configured using DHCP, so if you're on a network with a DHCP-server, the network will work straight away. If it's not, you can either configure the network manually or fix your DHCP-server and connection between it and ''eth0''. Next is one of the hardest questions that any OS installation is going to ask you: what will be the host name of the system? You could change it at any time in the future, but with lots of hassle, so you better choose wisely. Here are our tips: * do '''not''' name your machine after the user that's going to use it, e.g. "bernie-pc" (at some time in the future, Bernie's machine will be moved to Alice, so then Alice is working on "bernie-pc" which makes the situation quite unclear); * do '''not''' name your machine after the department or workgroup that's using it most, e.g. "accounting-srv" (same reasoning); * do '''not''' name your machine after it's main function, e.g. "printserver" (at some time in the future, the main function is moved to another machine, and/or an alternative function will become the main function of the machine); * do '''not''' name your machine after it's location, e.g. "srv-boston" (at some time in the future, the box will be moved to another location); * do '''not''' name your machine after it's hardware configuration, e.g. "ibmx346" (at some time in the future, either another xSeries x346 will be wheeled in, or the machine will be upgraded to accomodate increased use or overcome hardware problems - your "ibmx346" could suddenly be running on an xSeries x3650). What we feel are safe names for ''any'' machine in your network are true names, perhaps linked to a common theme: names of European cities, names of movie characters, names of countries or holiday destinations et cetera. Immediately following comes the question of the Domain Name. This is about a DNS domain, so effectively the installation program is asking which DNS suffix the host name should have; if the DHCP-server already provided something it'll be suggested, but you can override it if need be. In the preparatory phase, you'll have decided on continuation of your current DNS schema, or starting a new one. Either way, put the chosen DNS suffix in and press &lt;enter&gt;. ==Partitioning== Next comes the question of partitioning, or how to divide the available disk space into chunks for the server to use. This is a tricky subject, because if you put all storage space into one partition, then some day a runaway process will fill up the entire disk with useless logs, and the system will crash. On the other hand, if you divvy up all space into little chunks, then some application is going to need space in one of those partitions where there is none, even though there may be plenty in other partitions. To prevent both problems from occuring, we're going to use [http://tldp.org/HOWTO/LVM-HOWTO/whatisvolman.html Logical Volume Management (LVM)] so that we can provision enough space to start our server, but keep some space in reserve to apply when needed, where it'll be needed. So, we at Saruman.biz have put together a recommended standard partitioning scheme. The basis is this: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Partition !style="background:#ffdead;"|MD !style="background:#ffdead;"|LVG !style="background:#ffdead;"|LV-name !style="background:#ffdead;"|Size <br> (physical machine) !style="background:#ffdead;"|Size (VM) !style="background:#ffdead;"|File System !style="background:#ffdead;"|Mount point |- | 1 | /dev/md0 | &nbsp; | &nbsp; | 100MiB | 100MiB | ext3 | /boot |- | 2 | /dev/md1 | &nbsp; | &nbsp; | 3GiB | 1GiB | ext3 | / |- | rowspan="7" valign="top" | 3 | rowspan="7" valign="top" | /dev/md2 | rowspan="7" valign="top" style="background:lightgrey"| system | style="background:lightgrey" | swap | 1GiB<ref name="swap">Rule of thumb: twice the size of the machine's RAM, but no less than 256MiB and no more than 2GiB</ref> | 256MiB<ref name="swap"/> | swap | &nbsp; |- | style="background:lightgrey" | var | 2GiB | 1GiB | ext3 | /var |- | style="background:lightgrey" | appslog | 3GiB | - | ext3 | /var/appslog |- | style="background:lightgrey" | home | 1GiB<ref name="home">Note that this heavily depends on the purpose of the machine; if it is not to house any users, then (almost) no space is needed for /home. But on the other hand if e.g. a virtual user is to be used for keeping mailstores, or other service users need home space, then /home needs to be big enough for that.</ref> | 512MiB<ref name="home"/> | ext3 | /home |- | style="background:lightgrey" | usr | 3GiB | 3GiB | ext3 | /usr |- | style="background:lightgrey" | tmp | 1GiB | 512MiB | ext3 | /tmp |- | style="background:lightgrey" | opt | 1GiB | - | ext3 | /opt |- ! colspan="4" style="text-align:right"| Total ! 18.1GiB ! 6.9GiB ! colspan="2" | |- |} As you can see, the partition table works as follows: we assume that we wind up with 3 partitions, either on three separate software RAID arrays (''md0'' through ''md2'') or on one single hardware RAID array (in which case the 2nd column ''MD'' does not apply). The size of the partitions depends on your machine's make: for standard physical machines the 5th column does sensible suggestions, even though you could choose to have different sizes and of course different divisions altogether. If your machine happens to be a virtual one, running inside a [http://www.vmware.com/products/server/ VMware Server] or [http://www.vmware.com/products/vi/esx/ VMware ESX host], or the like, then you might want to start out with more modest partitions. The same holds for small servers that must run off Flash drives. Anyways, we're now at the Debian installation screen that lets us partition our disks. We're ''not'' going to use any of the "guided" partitionings, we go for "manual". Choosing that brings us to a screen showing all drives that the installation routine has detected, and all partitions on those drives that the installer can "see". We're going to do some assuming here once more: let's assume the drive(s) on which you want to install are visible, and are empty (containing no other partitions). <references/> ===Software RAID partitioning=== If you're to use software RAID, you now have to select the free space on the first drive, press &lt;enter&gt;, and then tell what you want to do with the free space: create a new partition, tell which size you want it to be (see table above), give the type of partition (primary), and give where on the disk it'll sit (the beginning). Next, a screen comes up that details how the partition you're requesting will be created. Here we make some changes: under "use as" we're going to select "physical volume for RAID". This clears all the other options in this screen, except for the "bootable" flag, which must be "on" for the first partition that we'll mount as ''/boot''. Now select "Done setting up the partition". Next, go to the free space on the second disk, and do ''exactly'' the same, to create an identical physical volume for RAID - if it's the first partition, select the "bootable" flag as well (we'll want to be able to boot from this second disk if the first disk fails, right?). Then go back to the rest of the free space on the first disk, make the second physical volume for RAID, duplicate it on the second disk. Then, go back to the rest of the free space on the first disk, make the third physical volume for RAID, and again duplicate it on the second disk. If you now go back to the "partition disks" overview, you'll see all the partitions you've specified listed on their respective disks. But at the top an extra option has appeared, called "configure software RAID". When you now select this option, the installer will ask if it may write the changes you've made to disk. This actually creates the partition tables on the disks. Note that at the end of configuring your partitions, an extra screen may appear (image 4): this asks if you care to identify which MD RAID devices must be started in order to be able to mount the root filesystem. Answering this question with a list of MD's like "md0 md1 md2" or simply "all" will let your server start the listed MD's very early in the boot sequence. ===Hardware RAID partitioning=== Now, if you have hardware RAID, then on your first (boot) disk just make 3 partitions, in the following manner: Select the free space on the intended boot disk, press &lt;enter&gt;, select "create a new partition", and fill out the desired size (100MB). Type is primary, location is beginning of the disk, and in the details of the partition, we only need to change the Mount point to "/boot", and set the Bootable flag to "On". Then we're "Done setting up this partition". The second partition is made the same way, but the desired size is 3GB, the Mount point is "/", and the Bootable flag remains off. Again, we're "Done setting up this partition". The third partition is again a primary partition, it takes up the entire rest of the disk, but the type is not ext3, but "physical volume for LVM". Again, we're "Done setting up this partition". But now from the main partitioner screen, we can access "Configure the Logical Volume Manager". The installer asks if it can write out the choices made to the disk, and then enters the LVM setup screen, which begins with a summary explaining that you have one Free Physical Volume, and nothing more. We now create a Volume Group (VG), which (in accordance to our partitioning standard) we'll call "system". In this VG, we'll add all Physical Volumes (being the one partition we've designated so in the previous step) using the space bar. Now we repeat the following process seven times: * select "Create Logical Volume" * select Volume Group "System" * give the LV Name (from the table, e.g. swap, var etc) * give the LV size (from the table, e.g. 1GB for swap etc) After this, we can select "Finish", the partitioner creates the seven LVs, and we're back at the partitioner screen, where there are now 7 extra "disks", with names such as ''LVM VG system, LV appslog - 3.2GB Linux device mapper''. Each of these "disks" has one block of empty space, which we now assign: seven times we repeat the following process: * select the unassigned chunk of empty space of an LV (e.g. appslog) and press &lt;enter&gt;; * Change "Use as: do not use" into the desired filesystem (ext3 - only the LV "swap" gets as filesystem type "swap area") * Change the mount point from "none" to the one corresponding with the name of the LV (note: the swap LV has no mountpoint; the appslog mountpoint must be entered manually as "/var/appslog") * If so desired, a label can be assigned to the partition (we usually don't) * select "Done setting up the partition" Once all this is done, we can look over the configuration once more, and then select "Finish partitioning and write changes to disk". A summary configuration screen will show, and we'll affirm with "yes" that these partitions can indeed be formatted. After some formatting screens flashing by (unless your partitions are particularly big, your system is particularly slow, or something goes wrong) the installation procedure continues. ==Final installer steps== Next comes one '''VERY''' important question: what to use as root password? We cannot stress this enough: choose a SAFE password! Do NOT go for an easy-to-remember one, go for STRONG and SAFE. There are tools to help you generate strong passwords, like [http://www.pctools.com/guides/password/ this page]: use them! We strongly suggest 10 characters or more, including letters, mixed case, and numbers, so something like ''SuCRe4hecH'' (do NOT use this, generate your own!). Next, give the full name of the principal user of this server (your own, we assume), give the login-name (your given name, we assume), and a corresponding password. Again, use a SAFE password. As long as you don't make your principal user equivalent to root, you might go for a slightly weaker password (8 characters instead of 10), but we rather suggest you make the password just as strong (and different from!) the root password. After entering the details of these two users "root" and "you", the Debian installer will ask you how it can contact the Debian archives, in the dialoge "configure the package manager". For the NetInstall version of Debian, this is as good as mandatory. So here, we say "yes, use a Network Mirror", and in the following list select the country in which we are (in our case: the Netherlands), so the installer can present us with a number of network mirrors "close by". We select ftp.nl.debian.org. Next screen: should you be behind a proxy server, then it's possible to specify that here. And then the test: the system will say "scanning the mirror..." and try to contact the specified mirror. If it does not succeed, then there is either a network problem, a problem with this box's network card, or you've not specified the mirror or proxy correctly - so fix it. You'll know the network mirror has succesfully been contacted when the next dialogue appears - currently "configuring popularity-contest". Answer this question as you please. And then one of the last "big" questions: Software Selection. In this dialogue, you can easily select bundles of software to be installed. The choices are currently: * Desktop environment * Web server * Print server * DNS server * File server * Mail server * SQL database * Laptop * Standard system (selected by default) We have to make a little confession here: we've never before used this option in the installer. In fact, we even deselect the Standard System, so as to minimize the number of software packages that the base installation of our server contains. This makes it more work to manually add packages later, but we feel it gives us more control and understanding of our systems. So if you are like us: deselect the Standard System entry, and select Continue. The next dialogue handles the installation of the [http://www.gnu.org/software/grub/ ''grub'' bootloader]. Unless your disks weren't empty and you're attempting to make this system multiboot, you'll most likely get a question if you'll allow the installer to install ''grub'' into the boot sector of the first hard disk. We'll confirm with "Yes". After the installation of grub is completed, the CD-ROM is ejected, and the system is ready to reboot into Debian Etch. Remove the CD and select "Continue" ==Finishing up the installation== The system should reboot into Debian. This means you should see the following boot sequence: * your machine's standard POST messages * then, a blue grub menu on a black screen, with two entries: ** Debian GNU/Linux, kernel 2.6.&lt;something&gt; ** Debian GNU/Linux, kernel 2.6.&lt;something&gt (single-user mode); * then, after a default time-out, the first grub option will go into effect, and the Linux kernel is started. Lots of cryptic messages in grey-on-black will scroll by, until the last few lines read: "Debian GNU/Linux 4.0 &lt;hostname&gt; tty1" and "&lt;hostname&gt; login:" If your system does not reach this login, and/or some horrible error messages appear anywhere in this boot sequence, then you've got some extra work ahead. For now we'll assume you've reached the login prompt without problem. Log in as the principal user (try to avoid logging in as root! That's BAD practice!). Once logged in, save a copy of the boot messages using ''sudo dmesg > boot.txt'' or whatever you like. Then look through the boot messages, e.g. with ''vi -R boot.txt''. Furthermore, [[APT_and_aptitude | use Aptitude]] to make sure ''all'' your software is updated to the latest version. Done! Your base system is ready. You probably now want to [[essential system software | install essential software]], [[roll your own kernel]] and [[connect your server to the Internet]]. e15bad403256c1c058f9a710b792962946bc89cd 0 1465 1627 2008-08-28T09:26:42Z Saruman! 2 [[Debian Etch base server]] moved to [[Debian Lenny base server]]: upgrade to Lenny info wikitext text/x-wiki #REDIRECT [[Debian Lenny base server]] 20596b7c8fbf8813e199f07d83ae1ef03c85e8f3 0 1 1628 1567 2008-08-28T09:27:21Z Saruman! 2 moved etch base server to lenny base server wikitext text/x-wiki <big>'''Welcome to SaruWiki.'''</big> This Wiki is intended to document bits and bobs about [http://www.kernel.org/ Linux] (and some Unix) in general, and [http://www.debian.org Debian] in particular. In it, [[SaruTeam|we]] wish to collect the tips and tricks of both [[SaruTeam|our own team of Linux admins]] and those of other interested users. Consult the [http://meta.wikimedia.org/wiki/Help:Contents User's Guide] for information on using this wiki's software. ---- <big>'''Main Content'''</big> * Setting up a [[Debian Lenny base server]] is a howto on the installation of a very basic Linux box under Lenny (it's actually not even a server yet). * The use of [[APT and aptitude]] is crucial to the concept of a Debian machine. * [[Roll your own kernel]] discusses the pros and cons of compiling your own kernel, and how to do it. * [[Essential system software]] lists all (sets of) packages that we deem, well, essential. * [[Add an X11 server]] to your server, if you need one * The [[system boot procedure]] section explains what we can customise in the standard ways Debian boots. * The [[networking section]] treats subjects like setting persistent routes. * The [[firewall section]] is where we discuss "IPtables" (netfilter) and how we use it for firewalling. * The [[native IPsec tunnel]] section describes how to configure an IPsec tunnel. * Using ''md'' for [[software RAID]] contains our ideas and observations on redundancy. * [[Hardware monitoring]] is important for your server's health and reliability. * [[Database 101]] introduces you to MySQL. * [[Vmware_server|VMware Server basics]] gives some pointers on how to install VMware Server on a Debian server box. * Make your server a [[Microsoft PPTP server | Microsoft client compatible VPN Server ]]. * How to install [[Mediawiki Installation | Mediawiki]] on your Debian server - like what you're looking at now. ---- '''Note''': the Wiki admins reserve the right to edit or remove any content they feel is not suitable for this site, not relevant, (too) inaccurate or otherwise not in line with the intentions and spirit of the admin team. ---- <websiteFrame> website=http://www.google.com/talk/service/badge/Show?tk&#61;z01q6amlqld8jocej2ca891jl9dunqqra83nhehaoqpednb5skkur0fv70jsuavce4ii9ms5e9afdr8qmpsc1d9upni4jom8g1em3p1cvq1p5eo1ugv162fosgprdv867iuememlcogfle8n3dmcf97durjld85avnh8k5lm1&amp;w=200&amp;h=60 border=0 height=60 width=200 name=GoogleChatwithSaruman! allowtransparency=true </websiteFrame> ef81ca247e3dc300a29af3bf341ace4bdd7531c5 1635 1628 2008-08-29T06:04:30Z Saruman! 2 added OpenLDAP link wikitext text/x-wiki <big>'''Welcome to SaruWiki.'''</big> This Wiki is intended to document bits and bobs about [http://www.kernel.org/ Linux] (and some Unix) in general, and [http://www.debian.org Debian] in particular. In it, [[SaruTeam|we]] wish to collect the tips and tricks of both [[SaruTeam|our own team of Linux admins]] and those of other interested users. Consult the [http://meta.wikimedia.org/wiki/Help:Contents User's Guide] for information on using this wiki's software. ---- <big>'''Main Content'''</big> * Setting up a [[Debian Lenny base server]] is a howto on the installation of a very basic Linux box under Lenny (it's actually not even a server yet). * The use of [[APT and aptitude]] is crucial to the concept of a Debian machine. * [[Roll your own kernel]] discusses the pros and cons of compiling your own kernel, and how to do it. * [[Essential system software]] lists all (sets of) packages that we deem, well, essential. * [[Database 101]] introduces you to MySQL. * [[OpenLDAP]] is a rudimentary howto about getting OpenLDAP to be your central user repository. * [[Add an X11 server]] to your server, if you need one * The [[system boot procedure]] section explains what we can customise in the standard ways Debian boots. * The [[networking section]] treats subjects like setting persistent routes. * The [[firewall section]] is where we discuss "IPtables" (netfilter) and how we use it for firewalling. * The [[native IPsec tunnel]] section describes how to configure an IPsec tunnel. * Using ''md'' for [[software RAID]] contains our ideas and observations on redundancy. * [[Hardware monitoring]] is important for your server's health and reliability. * [[Vmware_server|VMware Server basics]] gives some pointers on how to install VMware Server on a Debian server box. * Make your server a [[Microsoft PPTP server | Microsoft client compatible VPN Server ]]. * How to install [[Mediawiki Installation | Mediawiki]] on your Debian server - like what you're looking at now. ---- '''Note''': the Wiki admins reserve the right to edit or remove any content they feel is not suitable for this site, not relevant, (too) inaccurate or otherwise not in line with the intentions and spirit of the admin team. ---- <websiteFrame> website=http://www.google.com/talk/service/badge/Show?tk&#61;z01q6amlqld8jocej2ca891jl9dunqqra83nhehaoqpednb5skkur0fv70jsuavce4ii9ms5e9afdr8qmpsc1d9upni4jom8g1em3p1cvq1p5eo1ugv162fosgprdv867iuememlcogfle8n3dmcf97durjld85avnh8k5lm1&amp;w=200&amp;h=60 border=0 height=60 width=200 name=GoogleChatwithSaruman! allowtransparency=true </websiteFrame> fa1bb09142592a4e1fc021b400110ba6fbc5ce33 0 1431 1631 1509 2008-08-28T18:06:41Z Saruman! 2 iproute is in lenny by default wikitext text/x-wiki All utilities listed below are command line utilities; install them using ''apt-get install'' or ''aptitude''. ''apticron'' checks your system daily, and mails you when there are updates for packages<br> ''bzip2'' is a file compressor/decompressor<br> ''ccze'' can "colorize" output, e.g. ''tail -f /var/log/syslog | ccze''<br> ''ipcalc'' is an IP address/mask calculator<br> (''[[IProute | iproute]]'' helps viewing and setting the [http://lartc.org/ IP configuration] - under Lenny it's installed by default, under Etch you'll have to do it yourself)<br> ''iptraf'' is an IP traffic monitor<br> ''less'' is a utility [http://blog.platinumsolutions.com/node/47 to view text files];<br> ''pwgen'' is a password generator ''[[Sudo | sudo]]'' enables you to execute commands with another user's credentials<br> ''[[TCPdump | tcpdump]] is a network sniffer<br> ''arj'' is a file compressor/decompressor for the .arj file format<br> ''unzip'' is a file decompressor for the .zip file format<br> ''unzoo'' is a file decompressor for the .zoo file format<br> 15126643e01f865a75928233dd5d2a02a55386be 1634 1631 2008-08-28T20:36:55Z Saruman! 2 lsof and pciutils added wikitext text/x-wiki All utilities listed below are command line utilities; install them using ''apt-get install'' or ''aptitude''. ''apticron'' checks your system daily, and mails you when there are updates for packages<br> ''arj'' is a file compressor/decompressor for the .arj file format<br> ''bzip2'' is a file compressor/decompressor<br> ''ccze'' can "colorize" output, e.g. ''tail -f /var/log/syslog | ccze''<br> ''ipcalc'' is an IP address/mask calculator<br> (''[[IProute | iproute]]'' helps viewing and setting the [http://lartc.org/ IP configuration] - under Lenny it's installed by default, under Etch you'll have to do it yourself)<br> ''iptraf'' is an IP traffic monitor<br> ''less'' is a utility [http://blog.platinumsolutions.com/node/47 to view text files];<br> ''lsof'' can show all open files<br> ''pwgen'' is a password generator ''[[Sudo | sudo]]'' enables you to execute commands with another user's credentials<br> ''[[TCPdump | tcpdump]] is a network sniffer<br> ''pciutils'' contains the ''lspci'' command, which can be useful to review your hardware<br> ''unzip'' is a file decompressor for the .zip file format<br> ''unzoo'' is a file decompressor for the .zoo file format<br> 8127c815b4c580d46b2def9109bc35b02d1162db 0 1466 1632 2008-08-28T19:23:23Z Saruman! 2 Page started wikitext text/x-wiki == MySQL installation == As with any package to be installed: use aptitude, update your APT, then make sure all your (other) software is up-to-date. Then find package ''mysql-server'' - under Lenny it'll be version 5.0.51a-something. Installing it will also automatically install some dependent packages, like mysql-common, mysql-client etcetera. So after downloading some 40MiB of files, MySQL is installed. To now configure the MySQL server, please take the following steps: Think up a strong password for the MySQL root user; something like ''waYacUbaT2uW''. DON'T use this example password, [http://www.pctools.com/guides/password/ generate your own one!]. Start the MySQL client from the command line: mysql -u root Then, from the mysql client prompt, set the password for the MySQL root user. At installation time, two accounts "root" were created, each with an empty password - NOT safe! One account is used to connect to the MySQL server from localhost, one to connect from the IP address of the machine. They can be treated as two different accounts, but we don't recommend that. We thus give both accounts the same password: mysql> SET PASSWORD FOR 'root'@'localhost' = PASSWORD('waYacUbaT2uW'); mysql> SET PASSWORD FOR 'root'@'<hostname>' = PASSWORD('waYacUbaT2uW'); Furthermore, there are two anonymous accounts created. These also have no password, and get full permission on the ''test'' database, as well as on any database who's name begins with ''test_''. These accounts can be fitted with a password (like we did for root - just use two quotes with nothing inbetween them, instead of two quotes with ''root'' inbetween), or they can be removed - which we recommend. The (single) command for this is: <pre>mysql> DROP USER '';</pre> 9fc9c6c174962ab2b292b44f5dee426f52cc465a 1633 1632 2008-08-28T20:03:37Z Saruman! 2 updated post-installation tasks wikitext text/x-wiki == MySQL installation == As with any package to be installed: use aptitude, update your APT, then make sure all your (other) software is up-to-date. Then find package ''mysql-server'' - under Lenny it'll be version 5.0.51a-something. Installing it will also automatically install some dependent packages, like mysql-common, mysql-client etcetera. So after downloading some 40MiB of files, MySQL is installed. Should you consult [http://dev.mysql.com/doc/refman/5.0/en/unix-post-installation.html the official MySQL documentation], you might see mention of the ''mysql_install_db'' script - do not worry about that, since Debian has run it for you when it was setting up the database. To now configure the MySQL server, please take the following steps: Think up a strong password for the MySQL root user; something like ''waYacUbaT2uW''. DON'T use this example password, [http://www.pctools.com/guides/password/ generate your own one!]. Start the MySQL client from the command line: mysql -u root Then, from the mysql client prompt, set the password for the MySQL root user. At installation time, two accounts "root" were created, each with an empty password - NOT safe! One account is used to connect to the MySQL server from localhost, one to connect from the IP address of the machine. They can be treated as two different accounts, but we don't recommend that. We thus give both accounts the same password: mysql> SET PASSWORD FOR 'root'@'localhost' = PASSWORD('waYacUbaT2uW'); mysql> SET PASSWORD FOR 'root'@'<hostname>' = PASSWORD('waYacUbaT2uW'); Furthermore, there are two anonymous accounts created. These also have no password, and get full permission on the ''test'' database, as well as on any database who's name begins with ''test_''. These accounts can be fitted with a password (like we did for root - just use two quotes with nothing inbetween them, instead of two quotes with ''root'' inbetween), or they can be removed - which we recommend. The (single) command for this is: <pre>mysql> DROP USER '';</pre> To verify the installation you might want to take some of the following steps: * run ''mysqlshow -u root -p'', and see if that command outputs at least two databases (''information_schema'' and ''mysql''); * check out the settings of your MySQL server by running ''mysqladmin -u root -p variables'' (piping the output to ''less'' or a file, if necessary); * have a peek in ''/var/lib/mysql''; the database data files should be there; * check ''/var/log'' for two logfiles ''mysql.err'' and ''mysql.log''. 2c4a5c5dd986159a8ae521ca17bc5160038ad372 0 1467 1636 2008-08-29T06:23:45Z Saruman! 2 page started wikitext text/x-wiki == OpenLDAP installation== Note: we're going to install OpenLDAP on our server as [http://www.openldap.org/doc/admin24/config.html#Local%20Directory%20Service the local directory service], without replication, referrals or other advanced features. Installing OpenLDAP on your Debian server is ridiculously simple. Just make sure your server is up-to-date (''sudo apt-get update'' followed by ''sudo apt-get upgrade''), and then install the two main components for your OpenLDAP server: sudo apt-get install slapd ldap-utils The Debian configuration script will ask you for an administrator password. As always: generate a strong password! ecbbcd7bec49945acc555b3481b25eaec2d6d1ad 1637 1636 2008-08-29T07:43:20Z Saruman! 2 added DB remark wikitext text/x-wiki == OpenLDAP installation== Note: we're going to install OpenLDAP on our server as [http://www.openldap.org/doc/admin24/config.html#Local%20Directory%20Service the local directory service], without replication, referrals or other advanced features. Installing OpenLDAP on your Debian server is ridiculously simple. Just make sure your server is up-to-date (''sudo apt-get update'' followed by ''sudo apt-get upgrade''), and then install the two main components for your OpenLDAP server: sudo apt-get install slapd ldap-utils The Debian configuration script will ask you for an administrator password. As always: generate a strong password! When you've provided the password, the LDAP database is created with the administrator name "admin" and the The database that your OpenLDAP server uses is a standard Berkeley DB (BDB) database. Now we most likely will require some other databases as well in our server setup, something modern like PostgreSQL or MySQL - so why don't we configure our OpenLDAP to use this same database as well? For the answer, see [http://www.openldap.org/doc/admin24/intro.html#LDAP%20vs%20RDBMS here] - in short, the LDAP tree structure does not lend itself very well to inclusion in a modern relational database. 08c3caa90011454f5ec2f7dea439567e6c4752f7 1656 1637 2008-09-06T16:13:13Z Saruman! 2 dpkg-reconfigure added to slapd install wikitext text/x-wiki == OpenLDAP installation== Note: we're going to install OpenLDAP on our server as [http://www.openldap.org/doc/admin24/config.html#Local%20Directory%20Service the local directory service], without replication, referrals or other advanced features. Installing OpenLDAP on your Debian server is ridiculously simple. Just make sure your server is up-to-date (''sudo apt-get update'' followed by ''sudo apt-get upgrade''), and then install the two main components for your OpenLDAP server: sudo apt-get install slapd ldap-utils The Debian configuration script will ask you for only one single thing: an administrator password. As always: generate a strong password! When you've provided the password, the LDAP database is created with the administrator name "admin" and as a base directory path, something based on your DNS name. Suppose your internal domain is "amber.lan", then the script will generate ''suffix "dc=amber,dc=lan,dc="''. Since this might not always be the most convenient configuration, we recommend that you run the configuration again using ''dpkg-reconfigure slapd''. Interestingly enough, this reconfiguration asks you many ''more'' questions. The answers could look like this: omit OpenLDAP config: no DNS domain name: saruman.biz Organization name: Saruman Ltd. Administrator passwd: wEt3udes Database backend: HDB DB remove after purge: no Move old DB: yes Allow LDAPv2: no As you can see, the reconfiguration yields much more configuration options than plain installation - although really you'll probably answer most questions with their default values anyway, with the exception of the database backend, which by default is BDB. The database that your OpenLDAP server uses is a standard Berkeley DB (BDB) database. Now we most likely will require some other databases as well in our server setup, something modern like PostgreSQL or MySQL - so why don't we configure our OpenLDAP to use this same database as well? For the answer, see [http://www.openldap.org/doc/admin24/intro.html#LDAP%20vs%20RDBMS here] - in short, the LDAP tree structure does not lend itself very well to inclusion in a modern relational database. 04aec490c1e17e17d90543e90001a00811723011 1657 1656 2008-09-06T16:22:21Z Saruman! 2 added BDB backends wikitext text/x-wiki == OpenLDAP installation== Note: we're going to install OpenLDAP on our server as [http://www.openldap.org/doc/admin24/config.html#Local%20Directory%20Service the local directory service], without replication, referrals or other advanced features. Installing OpenLDAP on your Debian server is ridiculously simple. Just make sure your server is up-to-date (''sudo apt-get update'' followed by ''sudo apt-get upgrade''), and then install the two main components for your OpenLDAP server: sudo apt-get install slapd ldap-utils The Debian configuration script will ask you for only one single thing: an administrator password. As always: generate a strong password! When you've provided the password, the LDAP database is created with the administrator name "admin" and as a base directory path, something based on your DNS name. Suppose your internal domain is "amber.lan", then the script will generate ''suffix "dc=amber,dc=lan,dc="''. Since this might not always be the most convenient configuration, we recommend that you run the configuration again using ''dpkg-reconfigure slapd''. Interestingly enough, this reconfiguration asks you many ''more'' questions. The answers could look like this: omit OpenLDAP config: no DNS domain name: saruman.biz Organization name: Saruman Ltd. Administrator passwd: wEt3udes Database backend: HDB DB remove after purge: no Move old DB: yes Allow LDAPv2: no As you can see, the reconfiguration yields much more configuration options than plain installation - although really you'll probably answer most questions with their default values anyway, with the exception of the database backend, which by default is BDB. The database that your OpenLDAP server uses is a standard Berkeley DB (BDB) database. Now we most likely will require some other databases as well in our server setup, something modern like PostgreSQL or MySQL - so why don't we configure our OpenLDAP to use this same database as well? For the answer, see [http://www.openldap.org/doc/admin24/intro.html#LDAP%20vs%20RDBMS here] - in short, the LDAP tree structure does not lend itself very well to inclusion in a modern relational database. Thus, we advise to stick with the Berkeley database provided with OpenLDAP.<br> Thus, for the database backend, we have the choice between two almost identical flavours: the ''bdb'' backend is the recommended primary backend for a normal slapd database. It uses the Oracle Berkeley DB package, referred to as ''BDB'', to store data. It makes extensive use of indexing and caching to speed data access. ''hdb'' is a variant of the ''bdb'' backend that uses a hierarchical database layout which supports subtree renames. It is otherwise identical to the ''bdb'' behavior, and all the same configuration options apply 2f1ffcc7e8f6a70a8f22f71fbff7c8eef845ecb7 1658 1657 2008-09-06T21:12:56Z Saruman! 2 ldap info getting usable... wikitext text/x-wiki == OpenLDAP installation and configuration== Note: we're going to install OpenLDAP on our server as [http://www.openldap.org/doc/admin24/config.html#Local%20Directory%20Service the local directory service], without replication, referrals or other advanced features. Installing OpenLDAP on your Debian server is ridiculously simple. Just make sure your server is up-to-date (''sudo apt-get update'' followed by ''sudo apt-get upgrade''), and then install the two main components for your OpenLDAP server: sudo apt-get install slapd ldap-utils The Debian configuration script will ask you for only one single thing: an administrator password. As always: generate a strong password! When you've provided the password, the LDAP database is created with the administrator name "admin" and as a base directory path, something based on your DNS name. Suppose your internal domain is "amber.lan.", then the script will generate ''suffix "dc=amber,dc=lan,dc="''. The last, empty, domain component (''dc'') is caused by the trailing dot in your DNS name: the DNS root. Since this might not always be the most convenient configuration, we recommend that you run the configuration again using ''dpkg-reconfigure slapd''. Interestingly enough, this reconfiguration asks you many ''more'' questions. The answers could look like this: omit OpenLDAP config: no DNS domain name: saruman.biz Organization name: Saruman Administrator passwd: wEt3udes Database backend: HDB DB remove after purge: no Move old DB: yes Allow LDAPv2: no As you can see, the reconfiguration yields much more configuration options than plain installation - although really you'll probably answer most questions with their default values anyway, with the exception of the database backend, which by default is BDB.<br> Anyway, the above method of configuring yields you an LDAP database with only two objects in it: * a single Organization (o="Saruman") with Distinguished Name dn="dc=saruman,dc=biz" * a single administrator with Common Name cn="admin", and dn="cn=admin,dc=saruman,dc=biz" The database that your OpenLDAP server uses is a standard Berkeley DB (BDB) database. Now we most likely will require some other databases as well in our server setup, something modern like PostgreSQL or MySQL - so why don't we configure our OpenLDAP to use this same database as well? For the answer, see [http://www.openldap.org/doc/admin24/intro.html#LDAP%20vs%20RDBMS here] - in short, the LDAP tree structure does not lend itself very well to inclusion in a modern relational database. Thus, we advise to stick with the Berkeley database provided with OpenLDAP.<br> Now, for the database backend, we have the choice between two almost identical flavours: the ''bdb'' backend is the recommended primary backend for a normal slapd database. It uses the Oracle Berkeley DB package, referred to as ''BDB'', to store data. It makes extensive use of indexing and caching to speed data access. ''hdb'' is a variant of the ''bdb'' backend that uses a hierarchical database layout which supports subtree renames. It is otherwise identical to the ''bdb'' behavior, and all the same configuration options apply. ==Installing and configuring an LDAP Account Manager== It's perfectly normal to manipulate your LDAP from the command line using LDAP utilities like ''ldapsearch'', ''ldapadd'', ''ldapdelete'' and ''ldapmodify'', as well as ''slapcat'', ''slappasswd'' etcetera. However, many people find a GUI for LDAP indispensible. If you are amongst those, then for you, my friend, the question becomes: which graphic tool do you want to use? Many people speak highly of ''[http://gq-project.org/ gq]'', ''[http://luma.sourceforge.net/about.html luma]'' and ''[http://phpldapadmin.sourceforge.net/ phpldapadmin]''. We go for ''lam'' ([http://lam.sourceforge.net/index.htm LDAP acount Manager]). f1f87d1a69a9539420f7be66ca37a4e4bc6304af 1668 1658 2008-09-07T14:15:47Z Saruman! 2 /* Installing and configuring an LDAP Account Manager */ config addition wikitext text/x-wiki == OpenLDAP installation and configuration== Note: we're going to install OpenLDAP on our server as [http://www.openldap.org/doc/admin24/config.html#Local%20Directory%20Service the local directory service], without replication, referrals or other advanced features. Installing OpenLDAP on your Debian server is ridiculously simple. Just make sure your server is up-to-date (''sudo apt-get update'' followed by ''sudo apt-get upgrade''), and then install the two main components for your OpenLDAP server: sudo apt-get install slapd ldap-utils The Debian configuration script will ask you for only one single thing: an administrator password. As always: generate a strong password! When you've provided the password, the LDAP database is created with the administrator name "admin" and as a base directory path, something based on your DNS name. Suppose your internal domain is "amber.lan.", then the script will generate ''suffix "dc=amber,dc=lan,dc="''. The last, empty, domain component (''dc'') is caused by the trailing dot in your DNS name: the DNS root. Since this might not always be the most convenient configuration, we recommend that you run the configuration again using ''dpkg-reconfigure slapd''. Interestingly enough, this reconfiguration asks you many ''more'' questions. The answers could look like this: omit OpenLDAP config: no DNS domain name: saruman.biz Organization name: Saruman Administrator passwd: wEt3udes Database backend: HDB DB remove after purge: no Move old DB: yes Allow LDAPv2: no As you can see, the reconfiguration yields much more configuration options than plain installation - although really you'll probably answer most questions with their default values anyway, with the exception of the database backend, which by default is BDB.<br> Anyway, the above method of configuring yields you an LDAP database with only two objects in it: * a single Organization (o="Saruman") with Distinguished Name dn="dc=saruman,dc=biz" * a single administrator with Common Name cn="admin", and dn="cn=admin,dc=saruman,dc=biz" The database that your OpenLDAP server uses is a standard Berkeley DB (BDB) database. Now we most likely will require some other databases as well in our server setup, something modern like PostgreSQL or MySQL - so why don't we configure our OpenLDAP to use this same database as well? For the answer, see [http://www.openldap.org/doc/admin24/intro.html#LDAP%20vs%20RDBMS here] - in short, the LDAP tree structure does not lend itself very well to inclusion in a modern relational database. Thus, we advise to stick with the Berkeley database provided with OpenLDAP.<br> Now, for the database backend, we have the choice between two almost identical flavours: the ''bdb'' backend is the recommended primary backend for a normal slapd database. It uses the Oracle Berkeley DB package, referred to as ''BDB'', to store data. It makes extensive use of indexing and caching to speed data access. ''hdb'' is a variant of the ''bdb'' backend that uses a hierarchical database layout which supports subtree renames. It is otherwise identical to the ''bdb'' behavior, and all the same configuration options apply. ==Installing and configuring an LDAP Account Manager== It's perfectly normal to manipulate your LDAP from the command line using LDAP utilities like ''ldapsearch'', ''ldapadd'', ''ldapdelete'' and ''ldapmodify'', as well as ''slapcat'', ''slappasswd'' etcetera. However, many people find a GUI for LDAP indispensible. If you are amongst those, then for you, my friend, the question becomes: which graphic tool do you want to use? Many people speak highly of ''[http://gq-project.org/ gq]'', ''[http://luma.sourceforge.net/about.html luma]'' and ''[http://phpldapadmin.sourceforge.net/ phpldapadmin]''. We go for ''lam'' ([http://lam.sourceforge.net/index.htm LDAP acount Manager]).<br> To install ''lam'', first ensure that you have installed Apache2 and PHP5. Then we can use ''apt-get install ldap-account-manager''. After installation, we can right away surf to http://<server-IP>/lam, where we can log in. However, note that in the upper right, there's a link ''LAM configuration''. We'll go there first. Under the LAM configuration page, there are two links to areas, where settings can be specified. The first one is "Edit general settings", and clicking it prompts you for a master password - by default this is "lam". Behind that password is a simple settings page, that can be filled with values like this: * Security settings ** Session timeout: '''15''' (the amount of minutes of inactivity that's allowed before a user is logged off) ** Allowed hosts: '''192.168.67.*''' (the range of IP numbers from which LAM accepts connections; empty would mean "all" so we recommend limiting the scope to your internal network, or even less if possible) b6cb4ef544d540d5a8c7aeced216afe5086800ea 1669 1668 2008-09-07T15:39:02Z Saruman! 2 /* Installing and configuring an LDAP Account Manager */ finished config description wikitext text/x-wiki == OpenLDAP installation and configuration== Note: we're going to install OpenLDAP on our server as [http://www.openldap.org/doc/admin24/config.html#Local%20Directory%20Service the local directory service], without replication, referrals or other advanced features. Installing OpenLDAP on your Debian server is ridiculously simple. Just make sure your server is up-to-date (''sudo apt-get update'' followed by ''sudo apt-get upgrade''), and then install the two main components for your OpenLDAP server: sudo apt-get install slapd ldap-utils The Debian configuration script will ask you for only one single thing: an administrator password. As always: generate a strong password! When you've provided the password, the LDAP database is created with the administrator name "admin" and as a base directory path, something based on your DNS name. Suppose your internal domain is "amber.lan.", then the script will generate ''suffix "dc=amber,dc=lan,dc="''. The last, empty, domain component (''dc'') is caused by the trailing dot in your DNS name: the DNS root. Since this might not always be the most convenient configuration, we recommend that you run the configuration again using ''dpkg-reconfigure slapd''. Interestingly enough, this reconfiguration asks you many ''more'' questions. The answers could look like this: omit OpenLDAP config: no DNS domain name: saruman.biz Organization name: Saruman Administrator passwd: wEt3udes Database backend: HDB DB remove after purge: no Move old DB: yes Allow LDAPv2: no As you can see, the reconfiguration yields much more configuration options than plain installation - although really you'll probably answer most questions with their default values anyway, with the exception of the database backend, which by default is BDB.<br> Anyway, the above method of configuring yields you an LDAP database with only two objects in it: * a single Organization (o="Saruman") with Distinguished Name dn="dc=saruman,dc=biz" * a single administrator with Common Name cn="admin", and dn="cn=admin,dc=saruman,dc=biz" The database that your OpenLDAP server uses is a standard Berkeley DB (BDB) database. Now we most likely will require some other databases as well in our server setup, something modern like PostgreSQL or MySQL - so why don't we configure our OpenLDAP to use this same database as well? For the answer, see [http://www.openldap.org/doc/admin24/intro.html#LDAP%20vs%20RDBMS here] - in short, the LDAP tree structure does not lend itself very well to inclusion in a modern relational database. Thus, we advise to stick with the Berkeley database provided with OpenLDAP.<br> Now, for the database backend, we have the choice between two almost identical flavours: the ''bdb'' backend is the recommended primary backend for a normal slapd database. It uses the Oracle Berkeley DB package, referred to as ''BDB'', to store data. It makes extensive use of indexing and caching to speed data access. ''hdb'' is a variant of the ''bdb'' backend that uses a hierarchical database layout which supports subtree renames. It is otherwise identical to the ''bdb'' behavior, and all the same configuration options apply. ==Installing and configuring an LDAP Account Manager== It's perfectly normal to manipulate your LDAP from the command line using LDAP utilities like ''ldapsearch'', ''ldapadd'', ''ldapdelete'' and ''ldapmodify'', as well as ''slapcat'', ''slappasswd'' etcetera. However, many people find a GUI for LDAP indispensible. If you are amongst those, then for you, my friend, the question becomes: which graphic tool do you want to use? Many people speak highly of ''[http://gq-project.org/ gq]'', ''[http://luma.sourceforge.net/about.html luma]'' and ''[http://phpldapadmin.sourceforge.net/ phpldapadmin]''. We go for ''lam'' ([http://lam.sourceforge.net/index.htm LDAP acount Manager]).<br> To install ''lam'', first ensure that you have installed Apache2 and PHP5. Then we can use ''apt-get install ldap-account-manager''. After installation, we can right away surf to http://<server-IP>/lam, where we can log in. However, note that in the upper right, there's a link ''LAM configuration''. We'll go there first. Under the LAM configuration page, there are two links to areas, where settings can be specified. The first one is "Edit general settings", and clicking it prompts you for a master password - by default this is "lam". Behind that password is a simple settings page, that can be filled with values like this ('''bold''' values deviate from the default): * Security settings ** Session timeout: '''15''' (the amount of minutes of inactivity that's allowed before a user is logged off) ** Allowed hosts: '''192.168.67.*''' (the range of IP numbers from which LAM accepts connections; empty would mean "all" so we recommend limiting the scope to your internal network, or even less if possible. Multiple hosts or network ranges can be inserted below each other) * Password policy (in this section you can specify lower limits on your LDAP passwords - tho currently it's not clear to us what you're limiting. We suspect it's the creation of all LDAP passwords from within LAM). ** Minimum password length: '''6''' ** Minimum lowercase characters: 0 ** Minimum uppercase characters: 0 ** Minimum numeric characters: 0 ** Minimum symbolic characters: 0 ** Minimum character classes: '''3''' (The character classes are: lowercase, uppercase, numeric and symbols) * Logging ** Log level: notice (this is the most detailed level; "warning" logs less information, "error" less still) ** Log destination: syslog (outputs all LAM messages to the syslogger; alternatively specify "no logging" or a file name & location) * Change master password ** New master password: '''*****''' (this is the password that'll replace "lam" to log into the LAM configuration; it is NOT the password of your rootdn, and if anywhere possible, you should avoid using that particular password here - for safety. Generate [http://www.pctools.com/guides/password/ yet another strong password].) ** Reenter new master password: '''*****''' After entering the above settings, we at least know LAM is operational, and coarsely secured (it's not using SSL yet). Click ''OK'' to save, or ''back to login'' if you change your mind and just want to go back. The second link from the LAM configuration page, "Edit server profiles" will again prompt you. However, this password prompt page contains an extra pulldown option, currently filled with the word "lam". This is because there is only one server profile, named "lam", and filled with some default values for your LDAP server. And under those two boxes, there's a link "manage server profiles".<br> Now first we'll rename that profile to something more descriptive. Click the "manage server profiles" link, in the "profile management page" check the radio button next to ''&#091;lam&#093; Rename profile'', put in the new name (e.g. "sarumanbiz"), fill in the shiny new master LAM password &#8212; it should no longer be the default "lam" since you've changed it, in line with the paragraph above :-) &#8212; and then click OK. Presto! The server profile is renamed.<br> When you now enter your password to edit the server preferences for profile "sarumanbiz", you get to a page with a lot of settings; the only ones we're currently interested in are: * Server settings ** Server address: ldap://localhost:389 (verify that it's either localhost, if both the LDAP server and your LAM Apache2 are on the same machine, or a correct IP address or DNS name if that's not the case) ** Tree Suffix: '''dc=saruman,dc=biz''' (the same suffix you've installed your LDAP server with) * Security settings ** List of valid users: '''cn=admin,dc=saruman,dc=biz''' (or whatever you've designated your root DN) ** New password: '''''leave empty''''' (because this is to change the master password to edit ''this'' server profile; when this remains empty, the "master master password" for LAM remains in effect) ** Reenter password: (make this the same as the new password, i.e. empty) Now click OK, and your LAM should be ready to go. 0512670e5e717306f0d2244847fea1e787b00302 1670 1669 2008-09-07T19:54:11Z Saruman! 2 /* Installing and configuring an LDAP Account Manager */ added OU creation wikitext text/x-wiki == OpenLDAP installation and configuration== Note: we're going to install OpenLDAP on our server as [http://www.openldap.org/doc/admin24/config.html#Local%20Directory%20Service the local directory service], without replication, referrals or other advanced features. Installing OpenLDAP on your Debian server is ridiculously simple. Just make sure your server is up-to-date (''sudo apt-get update'' followed by ''sudo apt-get upgrade''), and then install the two main components for your OpenLDAP server: sudo apt-get install slapd ldap-utils The Debian configuration script will ask you for only one single thing: an administrator password. As always: generate a strong password! When you've provided the password, the LDAP database is created with the administrator name "admin" and as a base directory path, something based on your DNS name. Suppose your internal domain is "amber.lan.", then the script will generate ''suffix "dc=amber,dc=lan,dc="''. The last, empty, domain component (''dc'') is caused by the trailing dot in your DNS name: the DNS root. Since this might not always be the most convenient configuration, we recommend that you run the configuration again using ''dpkg-reconfigure slapd''. Interestingly enough, this reconfiguration asks you many ''more'' questions. The answers could look like this: omit OpenLDAP config: no DNS domain name: saruman.biz Organization name: Saruman Administrator passwd: wEt3udes Database backend: HDB DB remove after purge: no Move old DB: yes Allow LDAPv2: no As you can see, the reconfiguration yields much more configuration options than plain installation - although really you'll probably answer most questions with their default values anyway, with the exception of the database backend, which by default is BDB.<br> Anyway, the above method of configuring yields you an LDAP database with only two objects in it: * a single Organization (o="Saruman") with Distinguished Name dn="dc=saruman,dc=biz" * a single administrator with Common Name cn="admin", and dn="cn=admin,dc=saruman,dc=biz" The database that your OpenLDAP server uses is a standard Berkeley DB (BDB) database. Now we most likely will require some other databases as well in our server setup, something modern like PostgreSQL or MySQL - so why don't we configure our OpenLDAP to use this same database as well? For the answer, see [http://www.openldap.org/doc/admin24/intro.html#LDAP%20vs%20RDBMS here] - in short, the LDAP tree structure does not lend itself very well to inclusion in a modern relational database. Thus, we advise to stick with the Berkeley database provided with OpenLDAP.<br> Now, for the database backend, we have the choice between two almost identical flavours: the ''bdb'' backend is the recommended primary backend for a normal slapd database. It uses the Oracle Berkeley DB package, referred to as ''BDB'', to store data. It makes extensive use of indexing and caching to speed data access. ''hdb'' is a variant of the ''bdb'' backend that uses a hierarchical database layout which supports subtree renames. It is otherwise identical to the ''bdb'' behavior, and all the same configuration options apply. ==Installing and configuring an LDAP Account Manager== It's perfectly normal to manipulate your LDAP from the command line using LDAP utilities like ''ldapsearch'', ''ldapadd'', ''ldapdelete'' and ''ldapmodify'', as well as ''slapcat'', ''slappasswd'' etcetera. However, many people find a GUI for LDAP indispensible. If you are amongst those, then for you, my friend, the question becomes: which graphic tool do you want to use? Many people speak highly of ''[http://gq-project.org/ gq]'', ''[http://luma.sourceforge.net/about.html luma]'' and ''[http://phpldapadmin.sourceforge.net/ phpldapadmin]''. We go for ''lam'' ([http://lam.sourceforge.net/index.htm LDAP acount Manager]).<br> To install ''lam'', first ensure that you have installed Apache2 and PHP5. Then we can use ''apt-get install ldap-account-manager''. After installation, we can right away surf to http://<server-IP>/lam, where we can log in. However, note that in the upper right, there's a link ''LAM configuration''. We'll go there first. Under the LAM configuration page, there are two links to areas, where settings can be specified. The first one is "Edit general settings", and clicking it prompts you for a master password - by default this is "lam". Behind that password is a simple settings page, that can be filled with values like this ('''bold''' values deviate from the default): * Security settings ** Session timeout: '''15''' (the amount of minutes of inactivity that's allowed before a user is logged off) ** Allowed hosts: '''192.168.67.*''' (the range of IP numbers from which LAM accepts connections; empty would mean "all" so we recommend limiting the scope to your internal network, or even less if possible. Multiple hosts or network ranges can be inserted below each other) * Password policy (in this section you can specify lower limits on your LDAP passwords - tho currently it's not clear to us what you're limiting. We suspect it's the creation of all LDAP passwords from within LAM). ** Minimum password length: '''6''' ** Minimum lowercase characters: 0 ** Minimum uppercase characters: 0 ** Minimum numeric characters: 0 ** Minimum symbolic characters: 0 ** Minimum character classes: '''3''' (The character classes are: lowercase, uppercase, numeric and symbols) * Logging ** Log level: notice (this is the most detailed level; "warning" logs less information, "error" less still) ** Log destination: syslog (outputs all LAM messages to the syslogger; alternatively specify "no logging" or a file name & location) * Change master password ** New master password: '''*****''' (this is the password that'll replace "lam" to log into the LAM configuration; it is NOT the password of your rootdn, and if anywhere possible, you should avoid using that particular password here - for safety. Generate [http://www.pctools.com/guides/password/ yet another strong password].) ** Reenter new master password: '''*****''' After entering the above settings, we at least know LAM is operational, and coarsely secured (it's not using SSL yet). Click ''OK'' to save, or ''back to login'' if you change your mind and just want to go back. The second link from the LAM configuration page, "Edit server profiles" will again prompt you. However, this password prompt page contains an extra pulldown option, currently filled with the word "lam". This is because there is only one server profile, named "lam", and filled with some default values for your LDAP server. And under those two boxes, there's a link "manage server profiles".<br> Now first we'll rename that profile to something more descriptive. Click the "manage server profiles" link, in the "profile management page" check the radio button next to ''&#091;lam&#093; Rename profile'', put in the new name (e.g. "sarumanbiz"), fill in the shiny new master LAM password &#8212; it should no longer be the default "lam" since you've changed it, in line with the paragraph above :-) &#8212; and then click OK. Presto! The server profile is renamed.<br> When you now enter your password to edit the server preferences for profile "sarumanbiz", you get to a page with a lot of settings; the only ones we're currently interested in are: * Server settings ** Server address: ldap://localhost:389 (verify that it's either localhost, if both the LDAP server and your LAM Apache2 are on the same machine, or a correct IP address or DNS name if that's not the case) ** Tree Suffix: '''dc=saruman,dc=biz''' (the same suffix you've installed your LDAP server with) * Account types ** Edit Account types *** Users **** LDAP Suffix: '''ou=people,dc=saruman,dc=biz''' (You'll have to designate an OU in which to store user accounts; it does not have to exist yet (LAM can create it for you any time you log in) but the base has to be accessible; in our example: saruman.biz. Any name will do, but since we're storing identities, and not specifically users, we're calling the OU "people") *** Groups **** LDAP Suffix: '''ou=groups,dc=saruman,dc=biz''' (This is the OU where groups will be stored) *** Hosts **** LDAP Suffix: '''ou=hosts,dc=saruman,dc=biz''' (This is where machines, i.e. hosts, will be stored) *** Samba domains **** LDAP Suffix: '''ou=domains,dc=saruman,dc=biz''' (This is where all Windows workgroups/domains will wind up) * Security settings ** List of valid users: '''cn=admin,dc=saruman,dc=biz''' (or whatever you've designated your root DN) ** New password: '''''leave empty''''' (because this is to change the master password to edit ''this'' server profile; when this remains empty, the "master master password" for LAM remains in effect) ** Reenter password: (make this the same as the new password, i.e. empty) Now click OK, and your LAM should be ready to go. When you first log into the LAM profile you've just created, LAM will ask you if it should create the four OU's you've designated for people/groups/machines/domains. This is a nice test: if LAM cannot create those OU's, then you've misconfigured it (or the LDAP tree itself). If it can, then you'll be able to click ''tree view'' and browse the LDAP tree. At least the administrator (e.g. cn=admin) and the four OU's (e.g. domains/groups/hosts/people) should be present under the root (e.g. dc=saruman,dc=biz).<br> Incidentally, the configuration you've just entered into LAM as profile "sarumanbiz" can also be found at ''/usr/share/ldap-account-manager/config/sarumanbiz.conf'', so if need be, you can edit the profile by hand. ==Securing LAM communications with SSL== Until just now, all communications with LAM have taken place over unencrypted connections - not a nice way to work in a production environment. We really need to use SSL to secure the LAM environment. Fortunately, that is as easy as enabling SSL on the underlying Apache2 webserver. ==Migrating User, Password and Group entries to an LDAP server== It's nice to have an LDAP, but it's ''much'' nicer if it is filled with information. We'll try to enter all existing users and groups from the host server into LDAP, using the available migration tools. 601fa372bfe524f115a1b85ef797590662ad2a1b 1682 1670 2008-09-20T19:18:55Z Saruman! 2 /* Creating new Users */ started wikitext text/x-wiki == OpenLDAP installation and configuration== Note: we're going to install OpenLDAP on our server as [http://www.openldap.org/doc/admin24/config.html#Local%20Directory%20Service the local directory service], without replication, referrals or other advanced features. Installing OpenLDAP on your Debian server is ridiculously simple. Just make sure your server is up-to-date (''sudo apt-get update'' followed by ''sudo apt-get upgrade''), and then install the two main components for your OpenLDAP server: sudo apt-get install slapd ldap-utils The Debian configuration script will ask you for only one single thing: an administrator password. As always: generate a strong password! When you've provided the password, the LDAP database is created with the administrator name "admin" and as a base directory path, something based on your DNS name. Suppose your internal domain is "amber.lan.", then the script will generate ''suffix "dc=amber,dc=lan,dc="''. The last, empty, domain component (''dc'') is caused by the trailing dot in your DNS name: the DNS root. Since this might not always be the most convenient configuration, we recommend that you run the configuration again using ''dpkg-reconfigure slapd''. Interestingly enough, this reconfiguration asks you many ''more'' questions. The answers could look like this: omit OpenLDAP config: no DNS domain name: saruman.biz Organization name: Saruman Administrator passwd: wEt3udes Database backend: HDB DB remove after purge: no Move old DB: yes Allow LDAPv2: no As you can see, the reconfiguration yields much more configuration options than plain installation - although really you'll probably answer most questions with their default values anyway, with the exception of the database backend, which by default is BDB.<br> Anyway, the above method of configuring yields you an LDAP database with only two objects in it: * a single Organization (o="Saruman") with Distinguished Name dn="dc=saruman,dc=biz" * a single administrator with Common Name cn="admin", and dn="cn=admin,dc=saruman,dc=biz" The database that your OpenLDAP server uses is a standard Berkeley DB (BDB) database. Now we most likely will require some other databases as well in our server setup, something modern like PostgreSQL or MySQL - so why don't we configure our OpenLDAP to use this same database as well? For the answer, see [http://www.openldap.org/doc/admin24/intro.html#LDAP%20vs%20RDBMS here] - in short, the LDAP tree structure does not lend itself very well to inclusion in a modern relational database. Thus, we advise to stick with the Berkeley database provided with OpenLDAP.<br> Now, for the database backend, we have the choice between two almost identical flavours: the ''bdb'' backend is the recommended primary backend for a normal slapd database. It uses the Oracle Berkeley DB package, referred to as ''BDB'', to store data. It makes extensive use of indexing and caching to speed data access. ''hdb'' is a variant of the ''bdb'' backend that uses a hierarchical database layout which supports subtree renames. It is otherwise identical to the ''bdb'' behavior, and all the same configuration options apply. ==Installing and configuring an LDAP Account Manager== It's perfectly normal to manipulate your LDAP from the command line using LDAP utilities like ''ldapsearch'', ''ldapadd'', ''ldapdelete'' and ''ldapmodify'', as well as ''slapcat'', ''slappasswd'' etcetera. However, many people find a GUI for LDAP indispensible. If you are amongst those, then for you, my friend, the question becomes: which graphic tool do you want to use? Many people speak highly of ''[http://gq-project.org/ gq]'', ''[http://luma.sourceforge.net/about.html luma]'' and ''[http://phpldapadmin.sourceforge.net/ phpldapadmin]''. We go for ''lam'' ([http://lam.sourceforge.net/index.htm LDAP acount Manager]).<br> To install ''lam'', first ensure that you have installed Apache2 and PHP5. Then we can use ''apt-get install ldap-account-manager''. After installation, we can right away surf to http://<server-IP>/lam, where we can log in. However, note that in the upper right, there's a link ''LAM configuration''. We'll go there first. Under the LAM configuration page, there are two links to areas, where settings can be specified. The first one is "Edit general settings", and clicking it prompts you for a master password - by default this is "lam". Behind that password is a simple settings page, that can be filled with values like this ('''bold''' values deviate from the default): * Security settings ** Session timeout: '''15''' (the amount of minutes of inactivity that's allowed before a user is logged off) ** Allowed hosts: '''192.168.67.*''' (the range of IP numbers from which LAM accepts connections; empty would mean "all" so we recommend limiting the scope to your internal network, or even less if possible. Multiple hosts or network ranges can be inserted below each other) * Password policy (in this section you can specify lower limits on your LDAP passwords - tho currently it's not clear to us what you're limiting. We suspect it's the creation of all LDAP passwords from within LAM). ** Minimum password length: '''6''' ** Minimum lowercase characters: 0 ** Minimum uppercase characters: 0 ** Minimum numeric characters: 0 ** Minimum symbolic characters: 0 ** Minimum character classes: '''3''' (The character classes are: lowercase, uppercase, numeric and symbols) * Logging ** Log level: notice (this is the most detailed level; "warning" logs less information, "error" less still) ** Log destination: syslog (outputs all LAM messages to the syslogger; alternatively specify "no logging" or a file name & location) * Change master password ** New master password: '''*****''' (this is the password that'll replace "lam" to log into the LAM configuration; it is NOT the password of your rootdn, and if anywhere possible, you should avoid using that particular password here - for safety. Generate [http://www.pctools.com/guides/password/ yet another strong password].) ** Reenter new master password: '''*****''' After entering the above settings, we at least know LAM is operational, and coarsely secured (it's not using SSL yet). Click ''OK'' to save, or ''back to login'' if you change your mind and just want to go back. The second link from the LAM configuration page, "Edit server profiles" will again prompt you. However, this password prompt page contains an extra pulldown option, currently filled with the word "lam". This is because there is only one server profile, named "lam", and filled with some default values for your LDAP server. And under those two boxes, there's a link "manage server profiles".<br> Now first we'll rename that profile to something more descriptive. Click the "manage server profiles" link, in the "profile management page" check the radio button next to ''&#091;lam&#093; Rename profile'', put in the new name (e.g. "sarumanbiz"), fill in the shiny new master LAM password &#8212; it should no longer be the default "lam" since you've changed it, in line with the paragraph above :-) &#8212; and then click OK. Presto! The server profile is renamed.<br> When you now enter your password to edit the server preferences for profile "sarumanbiz", you get to a page with a lot of settings; the only ones we're currently interested in are: * Server settings ** Server address: ldap://localhost:389 (verify that it's either localhost, if both the LDAP server and your LAM Apache2 are on the same machine, or a correct IP address or DNS name if that's not the case) ** Tree Suffix: '''dc=saruman,dc=biz''' (the same suffix you've installed your LDAP server with) * Account types ** Edit Account types *** Users **** LDAP Suffix: '''ou=people,dc=saruman,dc=biz''' (You'll have to designate an OU in which to store user accounts; it does not have to exist yet (LAM can create it for you any time you log in) but the base has to be accessible; in our example: saruman.biz. Any name will do, but since we're storing identities, and not specifically users, we're calling the OU "people") *** Groups **** LDAP Suffix: '''ou=groups,dc=saruman,dc=biz''' (This is the OU where groups will be stored) *** Hosts **** LDAP Suffix: '''ou=hosts,dc=saruman,dc=biz''' (This is where machines, i.e. hosts, will be stored) *** Samba domains **** LDAP Suffix: '''ou=domains,dc=saruman,dc=biz''' (This is where all Windows workgroups/domains will wind up) * Security settings ** List of valid users: '''cn=admin,dc=saruman,dc=biz''' (or whatever you've designated your root DN) ** New password: '''''leave empty''''' (because this is to change the master password to edit ''this'' server profile; when this remains empty, the "master master password" for LAM remains in effect) ** Reenter password: (make this the same as the new password, i.e. empty) Now click OK, and your LAM should be ready to go. When you first log into the LAM profile you've just created, LAM will ask you if it should create the four OU's you've designated for people/groups/machines/domains. This is a nice test: if LAM cannot create those OU's, then you've misconfigured it (or the LDAP tree itself). If it can, then you'll be able to click ''tree view'' and browse the LDAP tree. At least the administrator (e.g. cn=admin) and the four OU's (e.g. domains/groups/hosts/people) should be present under the root (e.g. dc=saruman,dc=biz).<br> Incidentally, the configuration you've just entered into LAM as profile "sarumanbiz" can also be found at ''/usr/share/ldap-account-manager/config/sarumanbiz.conf'', so if need be, you can edit the profile by hand. ==Securing LAM communications with SSL== Until just now, all communications with LAM have taken place over unencrypted connections - not a nice way to work in a production environment. We really need to use SSL to secure the LAM environment. Fortunately, that is as easy as enabling SSL on the underlying Apache2 webserver. ==Migrating User, Password and Group entries to an LDAP server== It's nice to have an LDAP, but it's ''much'' nicer if it is filled with information. We'll try to enter all existing users and groups from the host server into LDAP, using [[Migrating existing Unix users to OpenLDAP | the available migration tools]]. ==Creating new users == If we need new users (e.g. when the server you're setting up is spankin' new) then we can create them in several ways. Let's discuss two of them: === Adding a user with an LDIF file=== To add a user with the LDAP command line utilities, we first need to create an LDIF file. This file is a simple text file, that could look something like this: # Create a new user: dn: cn=Joe Sixpack,ou=people,dc=saruman,dc=biz objectclass: top objectclass: inetOrgPerson objectclass: PosixAccount objectclass: ShadowAccount cn: Joe Sixpack sn: Sixpack # The Unix login-name for the user: uid: sixpacjo # The group and user IDs: gidNumber: 1000 uidNumber: 1000 # The home directory for the user: homeDirectory: /home/sixpacjo # The encrypted password for the user: userPassword: {crypt}$1$qs70ynbk$UBuewN7ZdIvqavIxkxdmX0 AHA! you'll say. But how do I get to this encrypted password? It's simple. Try this: openssl passwd -crypt "secret" The argument ''-crypt'' makes openssl generate a password using the standard Unix password algorithm; this is also the default setting. An alternative would be to use ''-1'' instead of ''-crypt'', which'll give you an MD5 encrypted password. Ofcourse, using an MD5 encrypted password means you have to change the last line of the LDIF file to userPassword: {MD5}$1$yCuyTf63$NoAjuX/dYBmE29hXrsDb41 Note that prefixing the used encryption method is totally fine with OpenLDAP, but it actually is not according to the LDAP standard; this LDIF file can be understood by OpenLDAP, but not by every other piece of LDAP software out there... Back to the LDIF file. === Adding a user with LAM=== 238be5a463dd5594e590ae57323369c3d4db8b95 1683 1682 2008-09-20T19:55:24Z Saruman! 2 /* Creating new users */ expanded LDIF wikitext text/x-wiki == OpenLDAP installation and configuration== Note: we're going to install OpenLDAP on our server as [http://www.openldap.org/doc/admin24/config.html#Local%20Directory%20Service the local directory service], without replication, referrals or other advanced features. Installing OpenLDAP on your Debian server is ridiculously simple. Just make sure your server is up-to-date (''sudo apt-get update'' followed by ''sudo apt-get upgrade''), and then install the two main components for your OpenLDAP server: sudo apt-get install slapd ldap-utils The Debian configuration script will ask you for only one single thing: an administrator password. As always: generate a strong password! When you've provided the password, the LDAP database is created with the administrator name "admin" and as a base directory path, something based on your DNS name. Suppose your internal domain is "amber.lan.", then the script will generate ''suffix "dc=amber,dc=lan,dc="''. The last, empty, domain component (''dc'') is caused by the trailing dot in your DNS name: the DNS root. Since this might not always be the most convenient configuration, we recommend that you run the configuration again using ''dpkg-reconfigure slapd''. Interestingly enough, this reconfiguration asks you many ''more'' questions. The answers could look like this: omit OpenLDAP config: no DNS domain name: saruman.biz Organization name: Saruman Administrator passwd: wEt3udes Database backend: HDB DB remove after purge: no Move old DB: yes Allow LDAPv2: no As you can see, the reconfiguration yields much more configuration options than plain installation - although really you'll probably answer most questions with their default values anyway, with the exception of the database backend, which by default is BDB.<br> Anyway, the above method of configuring yields you an LDAP database with only two objects in it: * a single Organization (o="Saruman") with Distinguished Name dn="dc=saruman,dc=biz" * a single administrator with Common Name cn="admin", and dn="cn=admin,dc=saruman,dc=biz" The database that your OpenLDAP server uses is a standard Berkeley DB (BDB) database. Now we most likely will require some other databases as well in our server setup, something modern like PostgreSQL or MySQL - so why don't we configure our OpenLDAP to use this same database as well? For the answer, see [http://www.openldap.org/doc/admin24/intro.html#LDAP%20vs%20RDBMS here] - in short, the LDAP tree structure does not lend itself very well to inclusion in a modern relational database. Thus, we advise to stick with the Berkeley database provided with OpenLDAP.<br> Now, for the database backend, we have the choice between two almost identical flavours: the ''bdb'' backend is the recommended primary backend for a normal slapd database. It uses the Oracle Berkeley DB package, referred to as ''BDB'', to store data. It makes extensive use of indexing and caching to speed data access. ''hdb'' is a variant of the ''bdb'' backend that uses a hierarchical database layout which supports subtree renames. It is otherwise identical to the ''bdb'' behavior, and all the same configuration options apply. ==Installing and configuring an LDAP Account Manager== It's perfectly normal to manipulate your LDAP from the command line using LDAP utilities like ''ldapsearch'', ''ldapadd'', ''ldapdelete'' and ''ldapmodify'', as well as ''slapcat'', ''slappasswd'' etcetera. However, many people find a GUI for LDAP indispensible. If you are amongst those, then for you, my friend, the question becomes: which graphic tool do you want to use? Many people speak highly of ''[http://gq-project.org/ gq]'', ''[http://luma.sourceforge.net/about.html luma]'' and ''[http://phpldapadmin.sourceforge.net/ phpldapadmin]''. We go for ''lam'' ([http://lam.sourceforge.net/index.htm LDAP acount Manager]).<br> To install ''lam'', first ensure that you have installed Apache2 and PHP5. Then we can use ''apt-get install ldap-account-manager''. After installation, we can right away surf to http://<server-IP>/lam, where we can log in. However, note that in the upper right, there's a link ''LAM configuration''. We'll go there first. Under the LAM configuration page, there are two links to areas, where settings can be specified. The first one is "Edit general settings", and clicking it prompts you for a master password - by default this is "lam". Behind that password is a simple settings page, that can be filled with values like this ('''bold''' values deviate from the default): * Security settings ** Session timeout: '''15''' (the amount of minutes of inactivity that's allowed before a user is logged off) ** Allowed hosts: '''192.168.67.*''' (the range of IP numbers from which LAM accepts connections; empty would mean "all" so we recommend limiting the scope to your internal network, or even less if possible. Multiple hosts or network ranges can be inserted below each other) * Password policy (in this section you can specify lower limits on your LDAP passwords - tho currently it's not clear to us what you're limiting. We suspect it's the creation of all LDAP passwords from within LAM). ** Minimum password length: '''6''' ** Minimum lowercase characters: 0 ** Minimum uppercase characters: 0 ** Minimum numeric characters: 0 ** Minimum symbolic characters: 0 ** Minimum character classes: '''3''' (The character classes are: lowercase, uppercase, numeric and symbols) * Logging ** Log level: notice (this is the most detailed level; "warning" logs less information, "error" less still) ** Log destination: syslog (outputs all LAM messages to the syslogger; alternatively specify "no logging" or a file name & location) * Change master password ** New master password: '''*****''' (this is the password that'll replace "lam" to log into the LAM configuration; it is NOT the password of your rootdn, and if anywhere possible, you should avoid using that particular password here - for safety. Generate [http://www.pctools.com/guides/password/ yet another strong password].) ** Reenter new master password: '''*****''' After entering the above settings, we at least know LAM is operational, and coarsely secured (it's not using SSL yet). Click ''OK'' to save, or ''back to login'' if you change your mind and just want to go back. The second link from the LAM configuration page, "Edit server profiles" will again prompt you. However, this password prompt page contains an extra pulldown option, currently filled with the word "lam". This is because there is only one server profile, named "lam", and filled with some default values for your LDAP server. And under those two boxes, there's a link "manage server profiles".<br> Now first we'll rename that profile to something more descriptive. Click the "manage server profiles" link, in the "profile management page" check the radio button next to ''&#091;lam&#093; Rename profile'', put in the new name (e.g. "sarumanbiz"), fill in the shiny new master LAM password &#8212; it should no longer be the default "lam" since you've changed it, in line with the paragraph above :-) &#8212; and then click OK. Presto! The server profile is renamed.<br> When you now enter your password to edit the server preferences for profile "sarumanbiz", you get to a page with a lot of settings; the only ones we're currently interested in are: * Server settings ** Server address: ldap://localhost:389 (verify that it's either localhost, if both the LDAP server and your LAM Apache2 are on the same machine, or a correct IP address or DNS name if that's not the case) ** Tree Suffix: '''dc=saruman,dc=biz''' (the same suffix you've installed your LDAP server with) * Account types ** Edit Account types *** Users **** LDAP Suffix: '''ou=people,dc=saruman,dc=biz''' (You'll have to designate an OU in which to store user accounts; it does not have to exist yet (LAM can create it for you any time you log in) but the base has to be accessible; in our example: saruman.biz. Any name will do, but since we're storing identities, and not specifically users, we're calling the OU "people") *** Groups **** LDAP Suffix: '''ou=groups,dc=saruman,dc=biz''' (This is the OU where groups will be stored) *** Hosts **** LDAP Suffix: '''ou=hosts,dc=saruman,dc=biz''' (This is where machines, i.e. hosts, will be stored) *** Samba domains **** LDAP Suffix: '''ou=domains,dc=saruman,dc=biz''' (This is where all Windows workgroups/domains will wind up) * Security settings ** List of valid users: '''cn=admin,dc=saruman,dc=biz''' (or whatever you've designated your root DN) ** New password: '''''leave empty''''' (because this is to change the master password to edit ''this'' server profile; when this remains empty, the "master master password" for LAM remains in effect) ** Reenter password: (make this the same as the new password, i.e. empty) Now click OK, and your LAM should be ready to go. When you first log into the LAM profile you've just created, LAM will ask you if it should create the four OU's you've designated for people/groups/machines/domains. This is a nice test: if LAM cannot create those OU's, then you've misconfigured it (or the LDAP tree itself). If it can, then you'll be able to click ''tree view'' and browse the LDAP tree. At least the administrator (e.g. cn=admin) and the four OU's (e.g. domains/groups/hosts/people) should be present under the root (e.g. dc=saruman,dc=biz).<br> Incidentally, the configuration you've just entered into LAM as profile "sarumanbiz" can also be found at ''/usr/share/ldap-account-manager/config/sarumanbiz.conf'', so if need be, you can edit the profile by hand. ==Securing LAM communications with SSL== Until just now, all communications with LAM have taken place over unencrypted connections - not a nice way to work in a production environment. We really need to use SSL to secure the LAM environment. Fortunately, that is as easy as enabling SSL on the underlying Apache2 webserver. ==Migrating User, Password and Group entries to an LDAP server== It's nice to have an LDAP, but it's ''much'' nicer if it is filled with information. We'll try to enter all existing users and groups from the host server into LDAP, using [[Migrating existing Unix users to OpenLDAP | the available migration tools]]. ==Creating new users == If we need new users (e.g. when the server you're setting up is spankin' new) then we can create them in several ways. Let's discuss two of them: === Adding a user with an LDIF file=== To add a user with the LDAP command line utilities, we first need to create an LDIF file. This file is a simple text file, that could look something like this: # Create the user group dn: cn=networkusers,ou=groups,dc=saruman,dc=biz objectClass: posixGroup description: Internal network users gidNumber: 10001 cn: TestGroup # Create a new user: dn: uid=sixpacjo,ou=people,dc=saruman,dc=biz objectclass: top objectclass: inetOrgPerson objectclass: posixAccount objectclass: shadowAccount cn: Joe Sixpack description: Your Average Network User givenName: Joe sn: Sixpack mail: joe.sixpack@saruman.biz # The Unix login-name for the user: uid: sixpacjo # The group and user IDs: gidNumber: 10001 uidNumber: 10001 # The Unix account data: homeDirectory: /home/sixpacjo loginShell: /bin/bash # The encrypted password for the user: userPassword: {crypt}$1$qs70ynbk$UBuewN7ZdIvqavIxkxdmX0 AHA! you'll say. But how do I get to this encrypted password? It's simple. Try this: openssl passwd -crypt "secret" The argument ''-crypt'' makes openssl generate a password using the standard Unix password algorithm; this is also the default setting. An alternative would be to use ''-1'' instead of ''-crypt'', which'll give you an MD5 encrypted password. Ofcourse, using an MD5 encrypted password means you have to change the last line of the LDIF file to userPassword: {MD5}$1$yCuyTf63$NoAjuX/dYBmE29hXrsDb41 Note that prefixing the used encryption method is totally fine with OpenLDAP, but it actually is not according to the LDAP standard; this LDIF file can be understood by OpenLDAP, but not by every other piece of LDAP software out there... Back to the LDIF file. === Adding a user with LAM=== b8813a003769554dc8f3aa24f2f32fbcc0d8ac74 1684 1683 2008-09-25T15:49:41Z Saruman! 2 split off entering accounts to separate page wikitext text/x-wiki == OpenLDAP installation and configuration== Note: we're going to install OpenLDAP on our server as [http://www.openldap.org/doc/admin24/config.html#Local%20Directory%20Service the local directory service], without replication, referrals or other advanced features. Installing OpenLDAP on your Debian server is ridiculously simple. Just make sure your server is up-to-date (''sudo apt-get update'' followed by ''sudo apt-get upgrade''), and then install the two main components for your OpenLDAP server: sudo apt-get install slapd ldap-utils The Debian configuration script will ask you for only one single thing: an administrator password. As always: generate a strong password! When you've provided the password, the LDAP database is created with the administrator name "admin" and as a base directory path, something based on your DNS name. Suppose your internal domain is "amber.lan.", then the script will generate ''suffix "dc=amber,dc=lan,dc="''. The last, empty, domain component (''dc'') is caused by the trailing dot in your DNS name: the DNS root. Since this might not always be the most convenient configuration, we recommend that you run the configuration again using ''dpkg-reconfigure slapd''. Interestingly enough, this reconfiguration asks you many ''more'' questions. The answers could look like this: omit OpenLDAP config: no DNS domain name: saruman.biz Organization name: Saruman Administrator passwd: wEt3udes Database backend: HDB DB remove after purge: no Move old DB: yes Allow LDAPv2: no As you can see, the reconfiguration yields much more configuration options than plain installation - although really you'll probably answer most questions with their default values anyway, with the exception of the database backend, which by default is BDB.<br> Anyway, the above method of configuring yields you an LDAP database with only two objects in it: * a single Organization (o="Saruman") with Distinguished Name dn="dc=saruman,dc=biz" * a single administrator with Common Name cn="admin", and dn="cn=admin,dc=saruman,dc=biz" The database that your OpenLDAP server uses is a standard Berkeley DB (BDB) database. Now we most likely will require some other databases as well in our server setup, something modern like PostgreSQL or MySQL - so why don't we configure our OpenLDAP to use this same database as well? For the answer, see [http://www.openldap.org/doc/admin24/intro.html#LDAP%20vs%20RDBMS here] - in short, the LDAP tree structure does not lend itself very well to inclusion in a modern relational database. Thus, we advise to stick with the Berkeley database provided with OpenLDAP.<br> Now, for the database backend, we have the choice between two almost identical flavours: the ''bdb'' backend is the recommended primary backend for a normal slapd database. It uses the Oracle Berkeley DB package, referred to as ''BDB'', to store data. It makes extensive use of indexing and caching to speed data access. ''hdb'' is a variant of the ''bdb'' backend that uses a hierarchical database layout which supports subtree renames. It is otherwise identical to the ''bdb'' behavior, and all the same configuration options apply. ==Installing and configuring an LDAP Account Manager== It's perfectly normal to manipulate your LDAP from the command line using LDAP utilities like ''ldapsearch'', ''ldapadd'', ''ldapdelete'' and ''ldapmodify'', as well as ''slapcat'', ''slappasswd'' etcetera. However, many people find a GUI for LDAP indispensible. If you are amongst those, then for you, my friend, the question becomes: which graphic tool do you want to use? Many people speak highly of ''[http://gq-project.org/ gq]'', ''[http://luma.sourceforge.net/about.html luma]'' and ''[http://phpldapadmin.sourceforge.net/ phpldapadmin]''. We go for ''lam'' ([http://lam.sourceforge.net/index.htm LDAP acount Manager]).<br> To install ''lam'', first ensure that you have installed Apache2 and PHP5. Then we can use ''apt-get install ldap-account-manager''. After installation, we can right away surf to http://<server-IP>/lam, where we can log in. However, note that in the upper right, there's a link ''LAM configuration''. We'll go there first. Under the LAM configuration page, there are two links to areas, where settings can be specified. The first one is "Edit general settings", and clicking it prompts you for a master password - by default this is "lam". Behind that password is a simple settings page, that can be filled with values like this ('''bold''' values deviate from the default): * Security settings ** Session timeout: '''15''' (the amount of minutes of inactivity that's allowed before a user is logged off) ** Allowed hosts: '''192.168.67.*''' (the range of IP numbers from which LAM accepts connections; empty would mean "all" so we recommend limiting the scope to your internal network, or even less if possible. Multiple hosts or network ranges can be inserted below each other) * Password policy (in this section you can specify lower limits on your LDAP passwords - tho currently it's not clear to us what you're limiting. We suspect it's the creation of all LDAP passwords from within LAM). ** Minimum password length: '''6''' ** Minimum lowercase characters: 0 ** Minimum uppercase characters: 0 ** Minimum numeric characters: 0 ** Minimum symbolic characters: 0 ** Minimum character classes: '''3''' (The character classes are: lowercase, uppercase, numeric and symbols) * Logging ** Log level: notice (this is the most detailed level; "warning" logs less information, "error" less still) ** Log destination: syslog (outputs all LAM messages to the syslogger; alternatively specify "no logging" or a file name & location) * Change master password ** New master password: '''*****''' (this is the password that'll replace "lam" to log into the LAM configuration; it is NOT the password of your rootdn, and if anywhere possible, you should avoid using that particular password here - for safety. Generate [http://www.pctools.com/guides/password/ yet another strong password].) ** Reenter new master password: '''*****''' After entering the above settings, we at least know LAM is operational, and coarsely secured (it's not using SSL yet). Click ''OK'' to save, or ''back to login'' if you change your mind and just want to go back. The second link from the LAM configuration page, "Edit server profiles" will again prompt you. However, this password prompt page contains an extra pulldown option, currently filled with the word "lam". This is because there is only one server profile, named "lam", and filled with some default values for your LDAP server. And under those two boxes, there's a link "manage server profiles".<br> Now first we'll rename that profile to something more descriptive. Click the "manage server profiles" link, in the "profile management page" check the radio button next to ''&#091;lam&#093; Rename profile'', put in the new name (e.g. "sarumanbiz"), fill in the shiny new master LAM password &#8212; it should no longer be the default "lam" since you've changed it, in line with the paragraph above :-) &#8212; and then click OK. Presto! The server profile is renamed.<br> When you now enter your password to edit the server preferences for profile "sarumanbiz", you get to a page with a lot of settings; the only ones we're currently interested in are: * Server settings ** Server address: ldap://localhost:389 (verify that it's either localhost, if both the LDAP server and your LAM Apache2 are on the same machine, or a correct IP address or DNS name if that's not the case) ** Tree Suffix: '''dc=saruman,dc=biz''' (the same suffix you've installed your LDAP server with) * Account types ** Edit Account types *** Users **** LDAP Suffix: '''ou=people,dc=saruman,dc=biz''' (You'll have to designate an OU in which to store user accounts; it does not have to exist yet (LAM can create it for you any time you log in) but the base has to be accessible; in our example: saruman.biz. Any name will do, but since we're storing identities, and not specifically users, we're calling the OU "people") *** Groups **** LDAP Suffix: '''ou=groups,dc=saruman,dc=biz''' (This is the OU where groups will be stored) *** Hosts **** LDAP Suffix: '''ou=hosts,dc=saruman,dc=biz''' (This is where machines, i.e. hosts, will be stored) *** Samba domains **** LDAP Suffix: '''ou=domains,dc=saruman,dc=biz''' (This is where all Windows workgroups/domains will wind up) * Security settings ** List of valid users: '''cn=admin,dc=saruman,dc=biz''' (or whatever you've designated your root DN) ** New password: '''''leave empty''''' (because this is to change the master password to edit ''this'' server profile; when this remains empty, the "master master password" for LAM remains in effect) ** Reenter password: (make this the same as the new password, i.e. empty) Now click OK, and your LAM should be ready to go. When you first log into the LAM profile you've just created, LAM will ask you if it should create the four OU's you've designated for people/groups/machines/domains. This is a nice test: if LAM cannot create those OU's, then you've misconfigured it (or the LDAP tree itself). If it can, then you'll be able to click ''tree view'' and browse the LDAP tree. At least the administrator (e.g. cn=admin) and the four OU's (e.g. domains/groups/hosts/people) should be present under the root (e.g. dc=saruman,dc=biz).<br> Incidentally, the configuration you've just entered into LAM as profile "sarumanbiz" can also be found at ''/usr/share/ldap-account-manager/config/sarumanbiz.conf'', so if need be, you can edit the profile by hand. ==Securing LAM communications with SSL== Until just now, all communications with LAM have taken place over unencrypted connections - not a nice way to work in a production environment. We really need to use SSL to secure the LAM environment. Fortunately, that is as easy as enabling SSL on the underlying Apache2 webserver. This completes the setup of the LDAP server. To fill it with relevant data, go to [[Filling an OpenLDAP database | the next section]]. 63a4621e4b670c4eeb3afc66784a64ebc77dcb7f 1686 1684 2008-09-25T16:37:29Z Saruman! 2 /* OpenLDAP installation and configuration */ added indexing wikitext text/x-wiki == OpenLDAP installation and configuration== Note: we're going to install OpenLDAP on our server as [http://www.openldap.org/doc/admin24/config.html#Local%20Directory%20Service the local directory service], without replication, referrals or other advanced features. Installing OpenLDAP on your Debian server is ridiculously simple. Just make sure your server is up-to-date (''sudo apt-get update'' followed by ''sudo apt-get upgrade''), and then install the two main components for your OpenLDAP server: sudo apt-get install slapd ldap-utils The Debian configuration script will ask you for only one single thing: an administrator password. As always: generate a strong password! When you've provided the password, the LDAP database is created with the administrator name "admin" and as a base directory path, something based on your DNS name. Suppose your internal domain is "amber.lan.", then the script will generate ''suffix "dc=amber,dc=lan,dc="''. The last, empty, domain component (''dc'') is caused by the trailing dot in your DNS name: the DNS root. Since this might not always be the most convenient configuration, we recommend that you run the configuration again using ''dpkg-reconfigure slapd''. Interestingly enough, this reconfiguration asks you many ''more'' questions. The answers could look like this: omit OpenLDAP config: no DNS domain name: saruman.biz Organization name: Saruman Administrator passwd: wEt3udes Database backend: HDB DB remove after purge: no Move old DB: yes Allow LDAPv2: no As you can see, the reconfiguration yields much more configuration options than plain installation - although really you'll probably answer most questions with their default values anyway, with the exception of the database backend, which by default is BDB.<br> Anyway, the above method of configuring yields you an LDAP database with only two objects in it: * a single Organization (o="Saruman") with Distinguished Name dn="dc=saruman,dc=biz" * a single administrator with Common Name cn="admin", and dn="cn=admin,dc=saruman,dc=biz" The database that your OpenLDAP server uses is a standard Berkeley DB (BDB) database. Now we most likely will require some other databases as well in our server setup, something modern like PostgreSQL or MySQL - so why don't we configure our OpenLDAP to use this same database as well? For the answer, see [http://www.openldap.org/doc/admin24/intro.html#LDAP%20vs%20RDBMS here] - in short, the LDAP tree structure does not lend itself very well to inclusion in a modern relational database. Thus, we advise to stick with the Berkeley database provided with OpenLDAP.<br> Now, for the database backend, we have the choice between two almost identical flavours: the ''bdb'' backend is the recommended primary backend for a normal slapd database. It uses the Oracle Berkeley DB package, referred to as ''BDB'', to store data. It makes extensive use of indexing and caching to speed data access. ''hdb'' is a variant of the ''bdb'' backend that uses a hierarchical database layout which supports subtree renames. It is otherwise identical to the ''bdb'' behavior, and all the same configuration options apply. To finetune the OpenLDAP configuration, we make some changes to the main configuration file for the OpenLDAP server, ''/etc/ldap/slapd.conf'': We find the line beginning with "loglevel" and change it from ''none'' to ''256''. This value means connections/operations/results wil be logged to the ''syslogd'' daemon. There, it will be logged to the ''LOG_LOCAL4'' facility. We find the line beginning with ''index'', and add a second line to it. This will make the section look like this: index objectClass eq index uid eq The purpose of this change is to make the OpenLDAP server create another index, on LDAP attribute ''uid''. This is important, because under some circumstances you might not receive any result on a valid query unless the searched entries are indexed. This entry makes sure all objects with a ''uid'' attribute are indexed, and thus can be found when queried. Finally, we check to be certain all necessary schema's are included: in the beginning of the file we should see include /etc/ldap/schema/core.schema include /etc/ldap/schema/cosine.schema include /etc/ldap/schema/nis.schema include /etc/ldap/schema/inetorgperson.schema If any line got missing, we need to (re)enter it in order to be able to create the LDAP entries that we want. After these little refinements, we must stop, reindex, and restart the OpenLDAP server. This can be done with the following sequence of commands: sudo invoke-rc.d slapd stop sudo -u openldap slapindex sudo invoke-rc.d slapd start Note: you need to have your ''sudo'' configured to allow you to ''su'' to user ''openldap'' in order to run the second command. ==Installing and configuring an LDAP Account Manager== It's perfectly normal to manipulate your LDAP from the command line using LDAP utilities like ''ldapsearch'', ''ldapadd'', ''ldapdelete'' and ''ldapmodify'', as well as ''slapcat'', ''slappasswd'' etcetera. However, many people find a GUI for LDAP indispensible. If you are amongst those, then for you, my friend, the question becomes: which graphic tool do you want to use? Many people speak highly of ''[http://gq-project.org/ gq]'', ''[http://luma.sourceforge.net/about.html luma]'' and ''[http://phpldapadmin.sourceforge.net/ phpldapadmin]''. We go for ''lam'' ([http://lam.sourceforge.net/index.htm LDAP acount Manager]).<br> To install ''lam'', first ensure that you have installed Apache2 and PHP5. Then we can use ''apt-get install ldap-account-manager''. After installation, we can right away surf to http://<server-IP>/lam, where we can log in. However, note that in the upper right, there's a link ''LAM configuration''. We'll go there first. Under the LAM configuration page, there are two links to areas, where settings can be specified. The first one is "Edit general settings", and clicking it prompts you for a master password - by default this is "lam". Behind that password is a simple settings page, that can be filled with values like this ('''bold''' values deviate from the default): * Security settings ** Session timeout: '''15''' (the amount of minutes of inactivity that's allowed before a user is logged off) ** Allowed hosts: '''192.168.67.*''' (the range of IP numbers from which LAM accepts connections; empty would mean "all" so we recommend limiting the scope to your internal network, or even less if possible. Multiple hosts or network ranges can be inserted below each other) * Password policy (in this section you can specify lower limits on your LDAP passwords - tho currently it's not clear to us what you're limiting. We suspect it's the creation of all LDAP passwords from within LAM). ** Minimum password length: '''6''' ** Minimum lowercase characters: 0 ** Minimum uppercase characters: 0 ** Minimum numeric characters: 0 ** Minimum symbolic characters: 0 ** Minimum character classes: '''3''' (The character classes are: lowercase, uppercase, numeric and symbols) * Logging ** Log level: notice (this is the most detailed level; "warning" logs less information, "error" less still) ** Log destination: syslog (outputs all LAM messages to the syslogger; alternatively specify "no logging" or a file name & location) * Change master password ** New master password: '''*****''' (this is the password that'll replace "lam" to log into the LAM configuration; it is NOT the password of your rootdn, and if anywhere possible, you should avoid using that particular password here - for safety. Generate [http://www.pctools.com/guides/password/ yet another strong password].) ** Reenter new master password: '''*****''' After entering the above settings, we at least know LAM is operational, and coarsely secured (it's not using SSL yet). Click ''OK'' to save, or ''back to login'' if you change your mind and just want to go back. The second link from the LAM configuration page, "Edit server profiles" will again prompt you. However, this password prompt page contains an extra pulldown option, currently filled with the word "lam". This is because there is only one server profile, named "lam", and filled with some default values for your LDAP server. And under those two boxes, there's a link "manage server profiles".<br> Now first we'll rename that profile to something more descriptive. Click the "manage server profiles" link, in the "profile management page" check the radio button next to ''&#091;lam&#093; Rename profile'', put in the new name (e.g. "sarumanbiz"), fill in the shiny new master LAM password &#8212; it should no longer be the default "lam" since you've changed it, in line with the paragraph above :-) &#8212; and then click OK. Presto! The server profile is renamed.<br> When you now enter your password to edit the server preferences for profile "sarumanbiz", you get to a page with a lot of settings; the only ones we're currently interested in are: * Server settings ** Server address: ldap://localhost:389 (verify that it's either localhost, if both the LDAP server and your LAM Apache2 are on the same machine, or a correct IP address or DNS name if that's not the case) ** Tree Suffix: '''dc=saruman,dc=biz''' (the same suffix you've installed your LDAP server with) * Account types ** Edit Account types *** Users **** LDAP Suffix: '''ou=people,dc=saruman,dc=biz''' (You'll have to designate an OU in which to store user accounts; it does not have to exist yet (LAM can create it for you any time you log in) but the base has to be accessible; in our example: saruman.biz. Any name will do, but since we're storing identities, and not specifically users, we're calling the OU "people") *** Groups **** LDAP Suffix: '''ou=groups,dc=saruman,dc=biz''' (This is the OU where groups will be stored) *** Hosts **** LDAP Suffix: '''ou=hosts,dc=saruman,dc=biz''' (This is where machines, i.e. hosts, will be stored) *** Samba domains **** LDAP Suffix: '''ou=domains,dc=saruman,dc=biz''' (This is where all Windows workgroups/domains will wind up) * Security settings ** List of valid users: '''cn=admin,dc=saruman,dc=biz''' (or whatever you've designated your root DN) ** New password: '''''leave empty''''' (because this is to change the master password to edit ''this'' server profile; when this remains empty, the "master master password" for LAM remains in effect) ** Reenter password: (make this the same as the new password, i.e. empty) Now click OK, and your LAM should be ready to go. When you first log into the LAM profile you've just created, LAM will ask you if it should create the four OU's you've designated for people/groups/machines/domains. This is a nice test: if LAM cannot create those OU's, then you've misconfigured it (or the LDAP tree itself). If it can, then you'll be able to click ''tree view'' and browse the LDAP tree. At least the administrator (e.g. cn=admin) and the four OU's (e.g. domains/groups/hosts/people) should be present under the root (e.g. dc=saruman,dc=biz).<br> Incidentally, the configuration you've just entered into LAM as profile "sarumanbiz" can also be found at ''/usr/share/ldap-account-manager/config/sarumanbiz.conf'', so if need be, you can edit the profile by hand. ==Securing LAM communications with SSL== Until just now, all communications with LAM have taken place over unencrypted connections - not a nice way to work in a production environment. We really need to use SSL to secure the LAM environment. Fortunately, that is as easy as enabling SSL on the underlying Apache2 webserver. This completes the setup of the LDAP server. To fill it with relevant data, go to [[Filling an OpenLDAP database | the next section]]. ea39cafaf832f1aca069070d666d49edfe3eec06 0 1426 1638 1524 2008-08-29T13:29:06Z Saruman! 2 Moved Iceditch to finished projects wikitext text/x-wiki ==Project List== The following projects need to be done on the SaruWiki Admin Team home servers ===Priority 1=== # Installation and configuration of ''[http://www.debian-administration.org/articles/585 OpenLDAP]'' to replace ''passwd'' # Reconfiguration of ''SaMBa'' to use ''OpenLDAP'' # Reconfiguration of ''Horde3'' to use ''OpenLDAP'' # Reconfiguration of ''postfix/courier'' Virtual Mailbox setup to use ''OpenLDAP'' ===Priority 2=== # Installation of a certificate authority # Reconfiguration of ''OpenSSH'' to use certificates instead of passwords # Installation of [http://www.asterisk.org/ Asterisk], to use [http://www.xs4all.nl/helpdesk/bellen/ XS4all VoIP] together with [http://www.telec.nl/producten/p55455/digium_pci_4-poort_a_b-kaart_1x_fxo_3x_fxs_(tdm431b).html KPN analog telephone lines]. ===Priority 3=== # Configuration of WebDAV on Apache2 # Configure traffic shaping measures, e.g. [http://werner.orkz.net/howtos/HTB%20bandwidth%20limiting%20in%20Linux%20HOWTO.html HTB] # Configure [http://www.mythtv.org/ MythTV] ===Priority 4=== The following projects are research projects only, so they're listed under Prio 4: # ''[http://iscsitarget.sourceforge.net IET]'' iSCSI Enterprise Target: have a Linux server become an iSCSI target # ''[http://www.howtoforge.com/iscsi_on_linux iSCSI initiator on Linux] # (semi)dynamic persistant route addition by scripting something under ''/etc/network/if-up.d'' ===Finished projects=== # Create a startup script for setting ''/proc/sys'' - was already there, see [[Procsys recommendations]] # Create a startup script for setting network routes - using the available networking options, see [[networking section]]. We still could look into more elaborate scripts under ''/etc/network/if-up.d'' but that's a really low priority expansion on persistant routing. # Create an IPtables parser script (the ''"Iceditch"'' project, see the [[firewall section]]) 4a2e08fb8086e80aad85fe6d9bbabc5533422cab 0 1422 1644 1494 2008-09-02T05:22:29Z Saruman! 2 /* Introduction */ expounded modal editor section wikitext text/x-wiki ==Introduction== The screen-oriented text editor ''vim'' stems from ''vi'', written in '76 for an early BSD Unix release by [http://www.engin.umich.edu/alumni/engineer/04SS/achievements/advances.html#joy Bill Joy]. ''vi'' is old, nonintuitive, and complex. However, it was the successor of the [http://www.wisegeek.com/what-is-a-line-editor.htm line editor] [http://www.apl.jhu.edu/Misc/Unix-info/unixintro/chap9.html ex]; the very name ''vi'' stands for "'''vi'''sual", and in the seventies, going from ''ex'' to ''vi'' was a big improvement indeed.<br> ''[http://en.wikipedia.org/wiki/Vim_%28text_editor%29 vim]'' stems from 1991, and stands for '''''V'''i '''IM'''proved'', but its improvements do not lessen it's nonintuitivity or complexity. So why do we feel that ''vim'' is an essential system tool? Well, it's because * vi can be found on just about any Linux and Unix system * vi is very powerful * with some practice, it's even quite usable but most importantly * if something goes horribly wrong, ''vi'' might just be the only means left to change your configuration files ===About vi as a modal editor=== ''vi'' is a modal editor; this type of editors will operate differently depending on which mode is selected. A ''vi'' session knows two modes: # ''insert mode'', where typed text is added into the document at the place of the prompt, and # ''normal mode'' or command mode, where keystrokes are interpreted as commands that control the session, or act on the document (depending on the command). ''vi'' begins in normal mode, but several commands (notably ''i'' and ''a'') will switch it to insert mode. Once in insert mode, most anything you type becomes part of your document. Only when you press <esc> does your ''vi'' return to normal mode. ==Installation and configuration== To get ''vim'', simply use ''sudo apt-get install vim'' or ''sudo aptitude'', and find ''vim'' in the available packages. Nice to know: when you install ''vim'', you also get ''xxd'', a tool to make a hexdump, or convert a hex dump back to it's original binary form. In Debian Etch, the default editor is nano instead of vim. This can be changed in the following way: which vim.basic sudo update-alternatives --set editor /usr/bin/vim.basic (The first line is to check that you really have vim.basic in place) Now '''all''' commands that invoke an editor will use ''vim'' instead of ''nano''. Is that a good thing? We're not sure, but we do want to keep our ''vi'' skills up to par, so we do this. ==Using vim== Vim operates in two modes: a command mode and an insert mode. You start in command mode, so almost every key is a command. Several commands you can issue will bring you into '''--INSERT--''' moode, e.g. ''i'' or ''a''; to return in command mode press ''&lt;esc&gt;'' or ( ''&lt;ctrl&gt; ['' ). It can be confusing to remember if you're in command mode or insert mode (even though there's a bright marker in the left bottom of the ''vim'' screen :-). So remember: when you're in insert mode, ''&lt;esc&gt;'' will bring you to command mode; when you're already in command mode, ''&lt;esc&gt;'' does nothing (no harm done). So press ''&lt;esc&gt;'' two or three times, and you're sure to be in command mode. Another thing to remember: if you're in command mode and you start entering a number ''before'' a command, the command will get repeated that many times. The most used feature of this is deleting lines. Deleting the current line is done with the command ''dd''; deleting (for example) twelve lines can be accomplished using ''12dd''. Another example is the use of a number in front of G: command ''12G'' (use &lt;shift&gt;-g) will bring you to the beginning of the 12th line. A special number is zero; pressing 0 as the first character in a command means immediately going to the beginning of the line. ===Exiting vim=== {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Command !style="background:#ffdead;"|Output |- |:w |Save |- |:w ''filename'' |Save with this filename |- |:q |quit vim |- |:q! |quit without save |- |:wq |save and quit |} ===Cursor positioning=== {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Key(s) !style="background:#ffdead;"|Movement |- |h |one character back |- |j |down one line, same column |- |k |up one line, same column |- |l,&lt;space&gt; |one character forward |- |b |one word back (to beginning of previous word) |- |e |one word back (to end of previous word) |- |w |one word forward |- |&lt;enter&gt; |beginning of next line |- |0 (zero) |beginning of line |- |$ |end of line |- |''n''G |to beginning of line ''n''; if no number given, the last line of the file |- |:''n'' |also to beginning of line ''n'' (but this is visible as command) |- |} Note that h,j,k,l is one block on your (US) keyboard ===Searching=== {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Key(s) !style="background:#ffdead;"|Search |- |/''pattern'' |Moves the cursor to the next occurrence of ''pattern''; will wrap around to the beginning of the file from the last occurence |- |?''pattern'' |Moves the cursor backward to the previous occurrence of ''pattern''; will wrap around to the end of the file from the first occurence |- |n |repeats last pattern search (either forward or backward) |- |} ===Text insertion=== {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Key(s) !style="background:#ffdead;"|Effect |- |a |appends text after cursor & switches to Insert mode |- |A |appends text at the '''end''' of the line & switches to Insert mode |- |i |inserts text before cursor & switches to Insert mode |- |I |inserts text at the '''beginning''' of the line & switches to Insert mode |- |o |opens new line below the current line for text insertion & switches to Insert mode |- |O |opens new line '''above''' the current line for text insertion & switches to Insert mode |- |&lt;del&gt; |overwrites last character during text insertion |- |&lt;esc&gt; |stops text insertion. The escape key on the DECstations is the &lt;F11&gt; key |- |} ===Text deletion=== {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Key(s) !style="background:#ffdead;"|Effect |- |x |deletes character under the cursor |- |dd |deletes current line |- |dw |deletes word under the cursor |- |d) |deletes to the end of the current sentence (up to and including the dot) |- |D |deletes to the end of the current line |- |d$ |same (deletes to the end of the current line) |- |p |"paste", puts the buffer (e.g. text from the previous deletion) after the position of the cursor |- |P |"Paste", puts the buffer (e.g. text from the previous deletion) '''before''' the position of the cursor |- |} e7b1c4e1e21133423e0d2626d595422f1e179b73 1647 1644 2008-09-04T05:26:40Z Saruman! 2 /* Text insertion */ del/backspace wikitext text/x-wiki ==Introduction== The screen-oriented text editor ''vim'' stems from ''vi'', written in '76 for an early BSD Unix release by [http://www.engin.umich.edu/alumni/engineer/04SS/achievements/advances.html#joy Bill Joy]. ''vi'' is old, nonintuitive, and complex. However, it was the successor of the [http://www.wisegeek.com/what-is-a-line-editor.htm line editor] [http://www.apl.jhu.edu/Misc/Unix-info/unixintro/chap9.html ex]; the very name ''vi'' stands for "'''vi'''sual", and in the seventies, going from ''ex'' to ''vi'' was a big improvement indeed.<br> ''[http://en.wikipedia.org/wiki/Vim_%28text_editor%29 vim]'' stems from 1991, and stands for '''''V'''i '''IM'''proved'', but its improvements do not lessen it's nonintuitivity or complexity. So why do we feel that ''vim'' is an essential system tool? Well, it's because * vi can be found on just about any Linux and Unix system * vi is very powerful * with some practice, it's even quite usable but most importantly * if something goes horribly wrong, ''vi'' might just be the only means left to change your configuration files ===About vi as a modal editor=== ''vi'' is a modal editor; this type of editors will operate differently depending on which mode is selected. A ''vi'' session knows two modes: # ''insert mode'', where typed text is added into the document at the place of the prompt, and # ''normal mode'' or command mode, where keystrokes are interpreted as commands that control the session, or act on the document (depending on the command). ''vi'' begins in normal mode, but several commands (notably ''i'' and ''a'') will switch it to insert mode. Once in insert mode, most anything you type becomes part of your document. Only when you press <esc> does your ''vi'' return to normal mode. ==Installation and configuration== To get ''vim'', simply use ''sudo apt-get install vim'' or ''sudo aptitude'', and find ''vim'' in the available packages. Nice to know: when you install ''vim'', you also get ''xxd'', a tool to make a hexdump, or convert a hex dump back to it's original binary form. In Debian Etch, the default editor is nano instead of vim. This can be changed in the following way: which vim.basic sudo update-alternatives --set editor /usr/bin/vim.basic (The first line is to check that you really have vim.basic in place) Now '''all''' commands that invoke an editor will use ''vim'' instead of ''nano''. Is that a good thing? We're not sure, but we do want to keep our ''vi'' skills up to par, so we do this. ==Using vim== Vim operates in two modes: a command mode and an insert mode. You start in command mode, so almost every key is a command. Several commands you can issue will bring you into '''--INSERT--''' moode, e.g. ''i'' or ''a''; to return in command mode press ''&lt;esc&gt;'' or ( ''&lt;ctrl&gt; ['' ). It can be confusing to remember if you're in command mode or insert mode (even though there's a bright marker in the left bottom of the ''vim'' screen :-). So remember: when you're in insert mode, ''&lt;esc&gt;'' will bring you to command mode; when you're already in command mode, ''&lt;esc&gt;'' does nothing (no harm done). So press ''&lt;esc&gt;'' two or three times, and you're sure to be in command mode. Another thing to remember: if you're in command mode and you start entering a number ''before'' a command, the command will get repeated that many times. The most used feature of this is deleting lines. Deleting the current line is done with the command ''dd''; deleting (for example) twelve lines can be accomplished using ''12dd''. Another example is the use of a number in front of G: command ''12G'' (use &lt;shift&gt;-g) will bring you to the beginning of the 12th line. A special number is zero; pressing 0 as the first character in a command means immediately going to the beginning of the line. ===Exiting vim=== {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Command !style="background:#ffdead;"|Output |- |:w |Save |- |:w ''filename'' |Save with this filename |- |:q |quit vim |- |:q! |quit without save |- |:wq |save and quit |} ===Cursor positioning=== {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Key(s) !style="background:#ffdead;"|Movement |- |h |one character back |- |j |down one line, same column |- |k |up one line, same column |- |l,&lt;space&gt; |one character forward |- |b |one word back (to beginning of previous word) |- |e |one word back (to end of previous word) |- |w |one word forward |- |&lt;enter&gt; |beginning of next line |- |0 (zero) |beginning of line |- |$ |end of line |- |''n''G |to beginning of line ''n''; if no number given, the last line of the file |- |:''n'' |also to beginning of line ''n'' (but this is visible as command) |- |} Note that h,j,k,l is one block on your (US) keyboard ===Searching=== {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Key(s) !style="background:#ffdead;"|Search |- |/''pattern'' |Moves the cursor to the next occurrence of ''pattern''; will wrap around to the beginning of the file from the last occurence |- |?''pattern'' |Moves the cursor backward to the previous occurrence of ''pattern''; will wrap around to the end of the file from the first occurence |- |n |repeats last pattern search (either forward or backward) |- |} ===Text insertion=== {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Key(s) !style="background:#ffdead;"|Effect |- |a |appends text after cursor & switches to Insert mode |- |A |appends text at the '''end''' of the line & switches to Insert mode |- |i |inserts text before cursor & switches to Insert mode |- |I |inserts text at the '''beginning''' of the line & switches to Insert mode |- |o |opens new line below the current line for text insertion & switches to Insert mode |- |O |opens new line '''above''' the current line for text insertion & switches to Insert mode |- |&lt;backspace&gt; |removes last character during text insertion |- |&lt;del&gt; |removes next character during text insertion |- |&lt;esc&gt; |stops text insertion. The escape key on the DECstations is the &lt;F11&gt; key |- |} ===Text deletion=== {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Key(s) !style="background:#ffdead;"|Effect |- |x |deletes character under the cursor |- |dd |deletes current line |- |dw |deletes word under the cursor |- |d) |deletes to the end of the current sentence (up to and including the dot) |- |D |deletes to the end of the current line |- |d$ |same (deletes to the end of the current line) |- |p |"paste", puts the buffer (e.g. text from the previous deletion) after the position of the cursor |- |P |"Paste", puts the buffer (e.g. text from the previous deletion) '''before''' the position of the cursor |- |} 402d5d788082531663ea1b4bda9235265bc9b0c6 1650 1647 2008-09-05T14:00:28Z Saruman! 2 /* Searching */ added substitute wikitext text/x-wiki ==Introduction== The screen-oriented text editor ''vim'' stems from ''vi'', written in '76 for an early BSD Unix release by [http://www.engin.umich.edu/alumni/engineer/04SS/achievements/advances.html#joy Bill Joy]. ''vi'' is old, nonintuitive, and complex. However, it was the successor of the [http://www.wisegeek.com/what-is-a-line-editor.htm line editor] [http://www.apl.jhu.edu/Misc/Unix-info/unixintro/chap9.html ex]; the very name ''vi'' stands for "'''vi'''sual", and in the seventies, going from ''ex'' to ''vi'' was a big improvement indeed.<br> ''[http://en.wikipedia.org/wiki/Vim_%28text_editor%29 vim]'' stems from 1991, and stands for '''''V'''i '''IM'''proved'', but its improvements do not lessen it's nonintuitivity or complexity. So why do we feel that ''vim'' is an essential system tool? Well, it's because * vi can be found on just about any Linux and Unix system * vi is very powerful * with some practice, it's even quite usable but most importantly * if something goes horribly wrong, ''vi'' might just be the only means left to change your configuration files ===About vi as a modal editor=== ''vi'' is a modal editor; this type of editors will operate differently depending on which mode is selected. A ''vi'' session knows two modes: # ''insert mode'', where typed text is added into the document at the place of the prompt, and # ''normal mode'' or command mode, where keystrokes are interpreted as commands that control the session, or act on the document (depending on the command). ''vi'' begins in normal mode, but several commands (notably ''i'' and ''a'') will switch it to insert mode. Once in insert mode, most anything you type becomes part of your document. Only when you press <esc> does your ''vi'' return to normal mode. ==Installation and configuration== To get ''vim'', simply use ''sudo apt-get install vim'' or ''sudo aptitude'', and find ''vim'' in the available packages. Nice to know: when you install ''vim'', you also get ''xxd'', a tool to make a hexdump, or convert a hex dump back to it's original binary form. In Debian Etch, the default editor is nano instead of vim. This can be changed in the following way: which vim.basic sudo update-alternatives --set editor /usr/bin/vim.basic (The first line is to check that you really have vim.basic in place) Now '''all''' commands that invoke an editor will use ''vim'' instead of ''nano''. Is that a good thing? We're not sure, but we do want to keep our ''vi'' skills up to par, so we do this. ==Using vim== Vim operates in two modes: a command mode and an insert mode. You start in command mode, so almost every key is a command. Several commands you can issue will bring you into '''--INSERT--''' moode, e.g. ''i'' or ''a''; to return in command mode press ''&lt;esc&gt;'' or ( ''&lt;ctrl&gt; ['' ). It can be confusing to remember if you're in command mode or insert mode (even though there's a bright marker in the left bottom of the ''vim'' screen :-). So remember: when you're in insert mode, ''&lt;esc&gt;'' will bring you to command mode; when you're already in command mode, ''&lt;esc&gt;'' does nothing (no harm done). So press ''&lt;esc&gt;'' two or three times, and you're sure to be in command mode. Another thing to remember: if you're in command mode and you start entering a number ''before'' a command, the command will get repeated that many times. The most used feature of this is deleting lines. Deleting the current line is done with the command ''dd''; deleting (for example) twelve lines can be accomplished using ''12dd''. Another example is the use of a number in front of G: command ''12G'' (use &lt;shift&gt;-g) will bring you to the beginning of the 12th line. A special number is zero; pressing 0 as the first character in a command means immediately going to the beginning of the line. ===Exiting vim=== {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Command !style="background:#ffdead;"|Output |- |:w |Save |- |:w ''filename'' |Save with this filename |- |:q |quit vim |- |:q! |quit without save |- |:wq |save and quit |} ===Cursor positioning=== {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Key(s) !style="background:#ffdead;"|Movement |- |h |one character back |- |j |down one line, same column |- |k |up one line, same column |- |l,&lt;space&gt; |one character forward |- |b |one word back (to beginning of previous word) |- |e |one word back (to end of previous word) |- |w |one word forward |- |&lt;enter&gt; |beginning of next line |- |0 (zero) |beginning of line |- |$ |end of line |- |''n''G |to beginning of line ''n''; if no number given, the last line of the file |- |:''n'' |also to beginning of line ''n'' (but this is visible as command) |- |} Note that h,j,k,l is one block on your (US) keyboard ===Searching=== {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Key(s) !style="background:#ffdead;"|Search |- |/''pattern'' |Moves the cursor to the next occurrence of ''pattern''; will wrap around to the beginning of the file from the last occurence |- |?''pattern'' |Moves the cursor backward to the previous occurrence of ''pattern''; will wrap around to the end of the file from the first occurence |- |n |repeats last pattern search (either forward or backward) |- |} <br> ===Search and replace=== If you think searching is fun, then search-and-replace is even more fun! Check out the "substitute" command: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Key(s) !style="background:#ffdead;"|Search |- |%s/''pattern''/''replacement'' |Moves the cursor to the next occurrence of ''pattern''; will wrap around to the beginning of the file from the last occurence |- |?''pattern'' |Moves the cursor backward to the previous occurrence of ''pattern''; will wrap around to the end of the file from the first occurence |- |n |repeats last pattern search (either forward or backward) |- |} ===Text insertion=== {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Key(s) !style="background:#ffdead;"|Effect |- |a |appends text after cursor & switches to Insert mode |- |A |appends text at the '''end''' of the line & switches to Insert mode |- |i |inserts text before cursor & switches to Insert mode |- |I |inserts text at the '''beginning''' of the line & switches to Insert mode |- |o |opens new line below the current line for text insertion & switches to Insert mode |- |O |opens new line '''above''' the current line for text insertion & switches to Insert mode |- |&lt;backspace&gt; |removes last character during text insertion |- |&lt;del&gt; |removes next character during text insertion |- |&lt;esc&gt; |stops text insertion. The escape key on the DECstations is the &lt;F11&gt; key |- |} ===Text deletion=== {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Key(s) !style="background:#ffdead;"|Effect |- |x |deletes character under the cursor |- |dd |deletes current line |- |dw |deletes word under the cursor |- |d) |deletes to the end of the current sentence (up to and including the dot) |- |D |deletes to the end of the current line |- |d$ |same (deletes to the end of the current line) |- |p |"paste", puts the buffer (e.g. text from the previous deletion) after the position of the cursor |- |P |"Paste", puts the buffer (e.g. text from the previous deletion) '''before''' the position of the cursor |- |} 90f1cc8e4fdcd279e16236cc721a212f7b1efce2 1651 1650 2008-09-05T14:14:38Z Saruman! 2 /* Search and replace */ properly wikitext text/x-wiki ==Introduction== The screen-oriented text editor ''vim'' stems from ''vi'', written in '76 for an early BSD Unix release by [http://www.engin.umich.edu/alumni/engineer/04SS/achievements/advances.html#joy Bill Joy]. ''vi'' is old, nonintuitive, and complex. However, it was the successor of the [http://www.wisegeek.com/what-is-a-line-editor.htm line editor] [http://www.apl.jhu.edu/Misc/Unix-info/unixintro/chap9.html ex]; the very name ''vi'' stands for "'''vi'''sual", and in the seventies, going from ''ex'' to ''vi'' was a big improvement indeed.<br> ''[http://en.wikipedia.org/wiki/Vim_%28text_editor%29 vim]'' stems from 1991, and stands for '''''V'''i '''IM'''proved'', but its improvements do not lessen it's nonintuitivity or complexity. So why do we feel that ''vim'' is an essential system tool? Well, it's because * vi can be found on just about any Linux and Unix system * vi is very powerful * with some practice, it's even quite usable but most importantly * if something goes horribly wrong, ''vi'' might just be the only means left to change your configuration files ===About vi as a modal editor=== ''vi'' is a modal editor; this type of editors will operate differently depending on which mode is selected. A ''vi'' session knows two modes: # ''insert mode'', where typed text is added into the document at the place of the prompt, and # ''normal mode'' or command mode, where keystrokes are interpreted as commands that control the session, or act on the document (depending on the command). ''vi'' begins in normal mode, but several commands (notably ''i'' and ''a'') will switch it to insert mode. Once in insert mode, most anything you type becomes part of your document. Only when you press <esc> does your ''vi'' return to normal mode. ==Installation and configuration== To get ''vim'', simply use ''sudo apt-get install vim'' or ''sudo aptitude'', and find ''vim'' in the available packages. Nice to know: when you install ''vim'', you also get ''xxd'', a tool to make a hexdump, or convert a hex dump back to it's original binary form. In Debian Etch, the default editor is nano instead of vim. This can be changed in the following way: which vim.basic sudo update-alternatives --set editor /usr/bin/vim.basic (The first line is to check that you really have vim.basic in place) Now '''all''' commands that invoke an editor will use ''vim'' instead of ''nano''. Is that a good thing? We're not sure, but we do want to keep our ''vi'' skills up to par, so we do this. ==Using vim== Vim operates in two modes: a command mode and an insert mode. You start in command mode, so almost every key is a command. Several commands you can issue will bring you into '''--INSERT--''' moode, e.g. ''i'' or ''a''; to return in command mode press ''&lt;esc&gt;'' or ( ''&lt;ctrl&gt; ['' ). It can be confusing to remember if you're in command mode or insert mode (even though there's a bright marker in the left bottom of the ''vim'' screen :-). So remember: when you're in insert mode, ''&lt;esc&gt;'' will bring you to command mode; when you're already in command mode, ''&lt;esc&gt;'' does nothing (no harm done). So press ''&lt;esc&gt;'' two or three times, and you're sure to be in command mode. Another thing to remember: if you're in command mode and you start entering a number ''before'' a command, the command will get repeated that many times. The most used feature of this is deleting lines. Deleting the current line is done with the command ''dd''; deleting (for example) twelve lines can be accomplished using ''12dd''. Another example is the use of a number in front of G: command ''12G'' (use &lt;shift&gt;-g) will bring you to the beginning of the 12th line. A special number is zero; pressing 0 as the first character in a command means immediately going to the beginning of the line. ===Exiting vim=== {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Command !style="background:#ffdead;"|Output |- |:w |Save |- |:w ''filename'' |Save with this filename |- |:q |quit vim |- |:q! |quit without save |- |:wq |save and quit |} ===Cursor positioning=== {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Key(s) !style="background:#ffdead;"|Movement |- |h |one character back |- |j |down one line, same column |- |k |up one line, same column |- |l,&lt;space&gt; |one character forward |- |b |one word back (to beginning of previous word) |- |e |one word back (to end of previous word) |- |w |one word forward |- |&lt;enter&gt; |beginning of next line |- |0 (zero) |beginning of line |- |$ |end of line |- |''n''G |to beginning of line ''n''; if no number given, the last line of the file |- |:''n'' |also to beginning of line ''n'' (but this is visible as command) |- |} Note that h,j,k,l is one block on your (US) keyboard ===Searching=== {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Key(s) !style="background:#ffdead;"|Search |- |/''pattern'' |Moves the cursor to the next occurrence of ''pattern''; will wrap around to the beginning of the file from the last occurence |- |?''pattern'' |Moves the cursor backward to the previous occurrence of ''pattern''; will wrap around to the end of the file from the first occurence |- |n |repeats last pattern search (either forward or backward) |- |} <br> ===Search and replace=== If you think searching is fun, then search-and-replace is even more fun! Check out the "substitute" command! :[range]s[ubstitute]/{pattern}/{string}/[&][c][e][g][p][r][i][I] [count] For each line in [range] replace a match of {pattern} with {string}. For the {pattern} see |pattern|. {string} can be a literal string, or something special; see |sub-replace-special|. When [range] and [count] are omitted, replace in the current line only. When [count] is given, replace in [count] lines, starting with the last line in [range]. When [range] is omitted start in the current line. [range] can be something like<br> % = whole file<br> 1,$ = also whole file<br> 3,7 = lines 3 through 7<br> .,+5 = current line (denoted with the period) through the next five lines<br> 'a,'b = between marks ''a'' and ''b''.<br> Well that sounds wonderful, but how do you use this in practice? Usually something like this: :%s/{pattern}/{string}/gic This means: search the whole file for case-insensitive occurrances of {pattern}, and replace each occurrance (even multiple on a single line) with {string} ''after'' confirmation of each replacement. ===Text insertion=== {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Key(s) !style="background:#ffdead;"|Effect |- |a |appends text after cursor & switches to Insert mode |- |A |appends text at the '''end''' of the line & switches to Insert mode |- |i |inserts text before cursor & switches to Insert mode |- |I |inserts text at the '''beginning''' of the line & switches to Insert mode |- |o |opens new line below the current line for text insertion & switches to Insert mode |- |O |opens new line '''above''' the current line for text insertion & switches to Insert mode |- |&lt;backspace&gt; |removes last character during text insertion |- |&lt;del&gt; |removes next character during text insertion |- |&lt;esc&gt; |stops text insertion. The escape key on the DECstations is the &lt;F11&gt; key |- |} ===Text deletion=== {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Key(s) !style="background:#ffdead;"|Effect |- |x |deletes character under the cursor |- |dd |deletes current line |- |dw |deletes word under the cursor |- |d) |deletes to the end of the current sentence (up to and including the dot) |- |D |deletes to the end of the current line |- |d$ |same (deletes to the end of the current line) |- |p |"paste", puts the buffer (e.g. text from the previous deletion) after the position of the cursor |- |P |"Paste", puts the buffer (e.g. text from the previous deletion) '''before''' the position of the cursor |- |} 56651c470099c80765e4b87a41a5882d6ca07bfd 1671 1651 2008-09-08T07:40:27Z Saruman! 2 /* Exiting vim */ added ZZ wikitext text/x-wiki ==Introduction== The screen-oriented text editor ''vim'' stems from ''vi'', written in '76 for an early BSD Unix release by [http://www.engin.umich.edu/alumni/engineer/04SS/achievements/advances.html#joy Bill Joy]. ''vi'' is old, nonintuitive, and complex. However, it was the successor of the [http://www.wisegeek.com/what-is-a-line-editor.htm line editor] [http://www.apl.jhu.edu/Misc/Unix-info/unixintro/chap9.html ex]; the very name ''vi'' stands for "'''vi'''sual", and in the seventies, going from ''ex'' to ''vi'' was a big improvement indeed.<br> ''[http://en.wikipedia.org/wiki/Vim_%28text_editor%29 vim]'' stems from 1991, and stands for '''''V'''i '''IM'''proved'', but its improvements do not lessen it's nonintuitivity or complexity. So why do we feel that ''vim'' is an essential system tool? Well, it's because * vi can be found on just about any Linux and Unix system * vi is very powerful * with some practice, it's even quite usable but most importantly * if something goes horribly wrong, ''vi'' might just be the only means left to change your configuration files ===About vi as a modal editor=== ''vi'' is a modal editor; this type of editors will operate differently depending on which mode is selected. A ''vi'' session knows two modes: # ''insert mode'', where typed text is added into the document at the place of the prompt, and # ''normal mode'' or command mode, where keystrokes are interpreted as commands that control the session, or act on the document (depending on the command). ''vi'' begins in normal mode, but several commands (notably ''i'' and ''a'') will switch it to insert mode. Once in insert mode, most anything you type becomes part of your document. Only when you press <esc> does your ''vi'' return to normal mode. ==Installation and configuration== To get ''vim'', simply use ''sudo apt-get install vim'' or ''sudo aptitude'', and find ''vim'' in the available packages. Nice to know: when you install ''vim'', you also get ''xxd'', a tool to make a hexdump, or convert a hex dump back to it's original binary form. In Debian Etch, the default editor is nano instead of vim. This can be changed in the following way: which vim.basic sudo update-alternatives --set editor /usr/bin/vim.basic (The first line is to check that you really have vim.basic in place) Now '''all''' commands that invoke an editor will use ''vim'' instead of ''nano''. Is that a good thing? We're not sure, but we do want to keep our ''vi'' skills up to par, so we do this. ==Using vim== Vim operates in two modes: a command mode and an insert mode. You start in command mode, so almost every key is a command. Several commands you can issue will bring you into '''--INSERT--''' moode, e.g. ''i'' or ''a''; to return in command mode press ''&lt;esc&gt;'' or ( ''&lt;ctrl&gt; ['' ). It can be confusing to remember if you're in command mode or insert mode (even though there's a bright marker in the left bottom of the ''vim'' screen :-). So remember: when you're in insert mode, ''&lt;esc&gt;'' will bring you to command mode; when you're already in command mode, ''&lt;esc&gt;'' does nothing (no harm done). So press ''&lt;esc&gt;'' two or three times, and you're sure to be in command mode. Another thing to remember: if you're in command mode and you start entering a number ''before'' a command, the command will get repeated that many times. The most used feature of this is deleting lines. Deleting the current line is done with the command ''dd''; deleting (for example) twelve lines can be accomplished using ''12dd''. Another example is the use of a number in front of G: command ''12G'' (use &lt;shift&gt;-g) will bring you to the beginning of the 12th line. A special number is zero; pressing 0 as the first character in a command means immediately going to the beginning of the line. ===Exiting vim=== {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Command !style="background:#ffdead;"|Output |- |:w |Save |- |:w ''filename'' |Save with this filename |- |:q |quit vim |- |:q! |quit without save |- |:wq |save and quit |ZZ |''also'' save and quit (no colon, just two caps) |} ===Cursor positioning=== {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Key(s) !style="background:#ffdead;"|Movement |- |h |one character back |- |j |down one line, same column |- |k |up one line, same column |- |l,&lt;space&gt; |one character forward |- |b |one word back (to beginning of previous word) |- |e |one word back (to end of previous word) |- |w |one word forward |- |&lt;enter&gt; |beginning of next line |- |0 (zero) |beginning of line |- |$ |end of line |- |''n''G |to beginning of line ''n''; if no number given, the last line of the file |- |:''n'' |also to beginning of line ''n'' (but this is visible as command) |- |} Note that h,j,k,l is one block on your (US) keyboard ===Searching=== {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Key(s) !style="background:#ffdead;"|Search |- |/''pattern'' |Moves the cursor to the next occurrence of ''pattern''; will wrap around to the beginning of the file from the last occurence |- |?''pattern'' |Moves the cursor backward to the previous occurrence of ''pattern''; will wrap around to the end of the file from the first occurence |- |n |repeats last pattern search (either forward or backward) |- |} <br> ===Search and replace=== If you think searching is fun, then search-and-replace is even more fun! Check out the "substitute" command! :[range]s[ubstitute]/{pattern}/{string}/[&][c][e][g][p][r][i][I] [count] For each line in [range] replace a match of {pattern} with {string}. For the {pattern} see |pattern|. {string} can be a literal string, or something special; see |sub-replace-special|. When [range] and [count] are omitted, replace in the current line only. When [count] is given, replace in [count] lines, starting with the last line in [range]. When [range] is omitted start in the current line. [range] can be something like<br> % = whole file<br> 1,$ = also whole file<br> 3,7 = lines 3 through 7<br> .,+5 = current line (denoted with the period) through the next five lines<br> 'a,'b = between marks ''a'' and ''b''.<br> Well that sounds wonderful, but how do you use this in practice? Usually something like this: :%s/{pattern}/{string}/gic This means: search the whole file for case-insensitive occurrances of {pattern}, and replace each occurrance (even multiple on a single line) with {string} ''after'' confirmation of each replacement. ===Text insertion=== {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Key(s) !style="background:#ffdead;"|Effect |- |a |appends text after cursor & switches to Insert mode |- |A |appends text at the '''end''' of the line & switches to Insert mode |- |i |inserts text before cursor & switches to Insert mode |- |I |inserts text at the '''beginning''' of the line & switches to Insert mode |- |o |opens new line below the current line for text insertion & switches to Insert mode |- |O |opens new line '''above''' the current line for text insertion & switches to Insert mode |- |&lt;backspace&gt; |removes last character during text insertion |- |&lt;del&gt; |removes next character during text insertion |- |&lt;esc&gt; |stops text insertion. The escape key on the DECstations is the &lt;F11&gt; key |- |} ===Text deletion=== {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Key(s) !style="background:#ffdead;"|Effect |- |x |deletes character under the cursor |- |dd |deletes current line |- |dw |deletes word under the cursor |- |d) |deletes to the end of the current sentence (up to and including the dot) |- |D |deletes to the end of the current line |- |d$ |same (deletes to the end of the current line) |- |p |"paste", puts the buffer (e.g. text from the previous deletion) after the position of the cursor |- |P |"Paste", puts the buffer (e.g. text from the previous deletion) '''before''' the position of the cursor |- |} ac79e0c484cf4f783077e81b6c9eb49a27129167 1672 1671 2008-09-08T07:40:51Z Saruman! 2 /* Exiting vim */ table cleanup :-) wikitext text/x-wiki ==Introduction== The screen-oriented text editor ''vim'' stems from ''vi'', written in '76 for an early BSD Unix release by [http://www.engin.umich.edu/alumni/engineer/04SS/achievements/advances.html#joy Bill Joy]. ''vi'' is old, nonintuitive, and complex. However, it was the successor of the [http://www.wisegeek.com/what-is-a-line-editor.htm line editor] [http://www.apl.jhu.edu/Misc/Unix-info/unixintro/chap9.html ex]; the very name ''vi'' stands for "'''vi'''sual", and in the seventies, going from ''ex'' to ''vi'' was a big improvement indeed.<br> ''[http://en.wikipedia.org/wiki/Vim_%28text_editor%29 vim]'' stems from 1991, and stands for '''''V'''i '''IM'''proved'', but its improvements do not lessen it's nonintuitivity or complexity. So why do we feel that ''vim'' is an essential system tool? Well, it's because * vi can be found on just about any Linux and Unix system * vi is very powerful * with some practice, it's even quite usable but most importantly * if something goes horribly wrong, ''vi'' might just be the only means left to change your configuration files ===About vi as a modal editor=== ''vi'' is a modal editor; this type of editors will operate differently depending on which mode is selected. A ''vi'' session knows two modes: # ''insert mode'', where typed text is added into the document at the place of the prompt, and # ''normal mode'' or command mode, where keystrokes are interpreted as commands that control the session, or act on the document (depending on the command). ''vi'' begins in normal mode, but several commands (notably ''i'' and ''a'') will switch it to insert mode. Once in insert mode, most anything you type becomes part of your document. Only when you press <esc> does your ''vi'' return to normal mode. ==Installation and configuration== To get ''vim'', simply use ''sudo apt-get install vim'' or ''sudo aptitude'', and find ''vim'' in the available packages. Nice to know: when you install ''vim'', you also get ''xxd'', a tool to make a hexdump, or convert a hex dump back to it's original binary form. In Debian Etch, the default editor is nano instead of vim. This can be changed in the following way: which vim.basic sudo update-alternatives --set editor /usr/bin/vim.basic (The first line is to check that you really have vim.basic in place) Now '''all''' commands that invoke an editor will use ''vim'' instead of ''nano''. Is that a good thing? We're not sure, but we do want to keep our ''vi'' skills up to par, so we do this. ==Using vim== Vim operates in two modes: a command mode and an insert mode. You start in command mode, so almost every key is a command. Several commands you can issue will bring you into '''--INSERT--''' moode, e.g. ''i'' or ''a''; to return in command mode press ''&lt;esc&gt;'' or ( ''&lt;ctrl&gt; ['' ). It can be confusing to remember if you're in command mode or insert mode (even though there's a bright marker in the left bottom of the ''vim'' screen :-). So remember: when you're in insert mode, ''&lt;esc&gt;'' will bring you to command mode; when you're already in command mode, ''&lt;esc&gt;'' does nothing (no harm done). So press ''&lt;esc&gt;'' two or three times, and you're sure to be in command mode. Another thing to remember: if you're in command mode and you start entering a number ''before'' a command, the command will get repeated that many times. The most used feature of this is deleting lines. Deleting the current line is done with the command ''dd''; deleting (for example) twelve lines can be accomplished using ''12dd''. Another example is the use of a number in front of G: command ''12G'' (use &lt;shift&gt;-g) will bring you to the beginning of the 12th line. A special number is zero; pressing 0 as the first character in a command means immediately going to the beginning of the line. ===Exiting vim=== {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Command !style="background:#ffdead;"|Output |- |:w |Save |- |:w ''filename'' |Save with this filename |- |:q |quit vim |- |:q! |quit without save |- |:wq |save and quit |- |ZZ |''also'' save and quit (no colon, just two caps) |} ===Cursor positioning=== {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Key(s) !style="background:#ffdead;"|Movement |- |h |one character back |- |j |down one line, same column |- |k |up one line, same column |- |l,&lt;space&gt; |one character forward |- |b |one word back (to beginning of previous word) |- |e |one word back (to end of previous word) |- |w |one word forward |- |&lt;enter&gt; |beginning of next line |- |0 (zero) |beginning of line |- |$ |end of line |- |''n''G |to beginning of line ''n''; if no number given, the last line of the file |- |:''n'' |also to beginning of line ''n'' (but this is visible as command) |- |} Note that h,j,k,l is one block on your (US) keyboard ===Searching=== {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Key(s) !style="background:#ffdead;"|Search |- |/''pattern'' |Moves the cursor to the next occurrence of ''pattern''; will wrap around to the beginning of the file from the last occurence |- |?''pattern'' |Moves the cursor backward to the previous occurrence of ''pattern''; will wrap around to the end of the file from the first occurence |- |n |repeats last pattern search (either forward or backward) |- |} <br> ===Search and replace=== If you think searching is fun, then search-and-replace is even more fun! Check out the "substitute" command! :[range]s[ubstitute]/{pattern}/{string}/[&][c][e][g][p][r][i][I] [count] For each line in [range] replace a match of {pattern} with {string}. For the {pattern} see |pattern|. {string} can be a literal string, or something special; see |sub-replace-special|. When [range] and [count] are omitted, replace in the current line only. When [count] is given, replace in [count] lines, starting with the last line in [range]. When [range] is omitted start in the current line. [range] can be something like<br> % = whole file<br> 1,$ = also whole file<br> 3,7 = lines 3 through 7<br> .,+5 = current line (denoted with the period) through the next five lines<br> 'a,'b = between marks ''a'' and ''b''.<br> Well that sounds wonderful, but how do you use this in practice? Usually something like this: :%s/{pattern}/{string}/gic This means: search the whole file for case-insensitive occurrances of {pattern}, and replace each occurrance (even multiple on a single line) with {string} ''after'' confirmation of each replacement. ===Text insertion=== {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Key(s) !style="background:#ffdead;"|Effect |- |a |appends text after cursor & switches to Insert mode |- |A |appends text at the '''end''' of the line & switches to Insert mode |- |i |inserts text before cursor & switches to Insert mode |- |I |inserts text at the '''beginning''' of the line & switches to Insert mode |- |o |opens new line below the current line for text insertion & switches to Insert mode |- |O |opens new line '''above''' the current line for text insertion & switches to Insert mode |- |&lt;backspace&gt; |removes last character during text insertion |- |&lt;del&gt; |removes next character during text insertion |- |&lt;esc&gt; |stops text insertion. The escape key on the DECstations is the &lt;F11&gt; key |- |} ===Text deletion=== {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Key(s) !style="background:#ffdead;"|Effect |- |x |deletes character under the cursor |- |dd |deletes current line |- |dw |deletes word under the cursor |- |d) |deletes to the end of the current sentence (up to and including the dot) |- |D |deletes to the end of the current line |- |d$ |same (deletes to the end of the current line) |- |p |"paste", puts the buffer (e.g. text from the previous deletion) after the position of the cursor |- |P |"Paste", puts the buffer (e.g. text from the previous deletion) '''before''' the position of the cursor |- |} 2da0107d880bbc1256c9d5be09df9ba485392a9b 1 1471 1645 2008-09-02T05:25:33Z Saruman! 2 Created an empty blocked page to prevent spamming wikitext text/x-wiki Unfortunately a lot of bots try to spam our wiki, a.o. by editing this very page. It is now protected to "block" spammers, as it were. c2fc9b10223a35c3d3dec0353f93b8d59763302c 1646 1645 2008-09-02T05:25:48Z Saruman! 2 Protected "[[Talk:Wiki/index.php]]": spamblocking [edit=sysop:move=sysop] wikitext text/x-wiki Unfortunately a lot of bots try to spam our wiki, a.o. by editing this very page. It is now protected to "block" spammers, as it were. c2fc9b10223a35c3d3dec0353f93b8d59763302c 0 1472 1685 2008-09-25T15:51:24Z Saruman! 2 Recreated user addition sections wikitext text/x-wiki ==Migrating User, Password and Group entries to an LDAP server== It's nice to have an LDAP, but it's ''much'' nicer if it is filled with information. We'll try to enter all existing users and groups from the host server into LDAP, using [[Migrating existing Unix users to OpenLDAP | the available migration tools]]. ==Creating new users == If we need new users (e.g. when the server you're setting up is spankin' new) then we can create them in several ways. Let's discuss two of them: === Adding a user with an LDIF file=== To add a user with the LDAP command line utilities, we first need to create an LDIF file. This file is a simple text file, that could look something like this: # Create the user group dn: cn=networkusers,ou=groups,dc=saruman,dc=biz objectClass: posixGroup description: Internal network users gidNumber: 10001 cn: TestGroup # Create a new user: dn: uid=sixpacjo,ou=people,dc=saruman,dc=biz objectclass: top objectclass: inetOrgPerson objectclass: posixAccount objectclass: shadowAccount cn: Joe Sixpack description: Your Average Network User givenName: Joe sn: Sixpack mail: joe.sixpack@saruman.biz # The Unix login-name for the user: uid: sixpacjo # The group and user IDs: gidNumber: 10001 uidNumber: 10001 # The Unix account data: homeDirectory: /home/sixpacjo loginShell: /bin/bash # The encrypted password for the user: userPassword: {crypt}$1$qs70ynbk$UBuewN7ZdIvqavIxkxdmX0 For a line-by-line explanation of this LDIF file, go [[LDIF syntax explanation | here]]. AHA! you'll say. But how do I get to this encrypted password? It's simple. Try this: openssl passwd -crypt "secret" The argument ''-crypt'' makes openssl generate a password using the standard Unix password algorithm; this is also the default setting. An alternative would be to use ''-1'' instead of ''-crypt'', which'll give you an MD5 encrypted password. Ofcourse, using an MD5 encrypted password means you have to change the last line of the LDIF file to userPassword: {MD5}$1$yCuyTf63$NoAjuX/dYBmE29hXrsDb41 Note that prefixing the used encryption method is totally fine with OpenLDAP, but it actually is not according to the LDAP standard; this LDIF file can be understood by OpenLDAP, but not by every other piece of LDAP software out there... === Adding a user with LAM=== 094fd62777f7deb716e88bef343538c7b80ddceb 1687 1685 2008-09-25T16:56:55Z Saruman! 2 OU creation added wikitext text/x-wiki == Creating your first Organizational Units == On the offchance that you haven't installed LAM, and thus haven't created the organizational units ''people'', ''groups'', ''hosts'' and ''domains'', here's how to create them manually. Create a file containing the following information: dn: ou=people,dc=saruman,dc=biz ou: people objectClass: top objectClass: organizationalUnit structuralObjectClass: organizationalUnit dn: ou=groups,dc=saruman,dc=biz ou: groups objectClass: top objectClass: organizationalUnit structuralObjectClass: organizationalUnit dn: ou=hosts,dc=saruman,dc=biz ou: hosts objectClass: top objectClass: organizationalUnit structuralObjectClass: organizationalUnit dn: ou=domains,dc=saruman,dc=biz ou: domains objectClass: top objectClass: organizationalUnit structuralObjectClass: organizationalUnit Let's suppose this file is named ''orgunits.ldif''. Now from the directory that contains this file, feed the information into your OpenLDAP using the following commands: sudo invoke-rc.d slapd stop sudo slapadd -c -v -l orgunits.ldif sudo invoke-rc.d slapd start This effectively stops the server, writes the information directly into the database, and then starts the server again. Another way to do the ''same'' thing, would be to add the information with the ''ldapadd'' command: ldapadd -c -x -D cn=admin,dc=saruman,dc=biz -W -f orgunits.ldif This binds to the OpenLDAP server (which must be running) using the admin account. This causes the command to request the admin password, and then feed the contents from the ''orgunits.ldif'' file into the database. ==Migrating User, Password and Group entries to an LDAP server== It's nice to have an LDAP, but it's ''much'' nicer if it is filled with information. We'll try to enter all existing users and groups from the host server into LDAP, using [[Migrating existing Unix users to OpenLDAP | the available migration tools]]. ==Creating new users == If we need new users (e.g. when the server you're setting up is spankin' new) then we can create them in several ways. Let's discuss two of them: === Adding a user with an LDIF file=== To add a user with the LDAP command line utilities, we first need to create an LDIF file. This file is a simple text file, that could look something like this: # Create the user group dn: cn=networkusers,ou=groups,dc=saruman,dc=biz objectClass: posixGroup description: Internal network users gidNumber: 10001 cn: TestGroup # Create a new user: dn: uid=sixpacjo,ou=people,dc=saruman,dc=biz objectclass: top objectclass: inetOrgPerson objectclass: posixAccount objectclass: shadowAccount cn: Joe Sixpack description: Your Average Network User givenName: Joe sn: Sixpack mail: joe.sixpack@saruman.biz # The Unix login-name for the user: uid: sixpacjo # The group and user IDs: gidNumber: 10001 uidNumber: 10001 # The Unix account data: homeDirectory: /home/sixpacjo loginShell: /bin/bash # The encrypted password for the user: userPassword: {crypt}$1$qs70ynbk$UBuewN7ZdIvqavIxkxdmX0 For a line-by-line explanation of this LDIF file, go [[LDIF syntax explanation | here]]. AHA! you'll say. But how do I get to this encrypted password? It's simple. Try this: openssl passwd -crypt "secret" The argument ''-crypt'' makes openssl generate a password using the standard Unix password algorithm; this is also the default setting. An alternative would be to use ''-1'' instead of ''-crypt'', which'll give you an MD5 encrypted password. Ofcourse, using an MD5 encrypted password means you have to change the last line of the LDIF file to userPassword: {MD5}$1$yCuyTf63$NoAjuX/dYBmE29hXrsDb41 Note that prefixing the used encryption method is totally fine with OpenLDAP, but it actually is not according to the LDAP standard; this LDIF file can be understood by OpenLDAP, but not by every other piece of LDAP software out there... === Adding a user with LAM=== a8d072cc7e23c5d96580d2a7fb3233ca1b2bc1ff 1688 1687 2008-09-25T16:57:58Z Saruman! 2 /* Creating your first Organizational Units */ ldif file layout corrected wikitext text/x-wiki == Creating your first Organizational Units == On the offchance that you haven't installed LAM, and thus haven't created the organizational units ''people'', ''groups'', ''hosts'' and ''domains'', here's how to create them manually. Create a file containing the following information: <pre> dn: ou=people,dc=saruman,dc=biz ou: people objectClass: top objectClass: organizationalUnit structuralObjectClass: organizationalUnit dn: ou=groups,dc=saruman,dc=biz ou: groups objectClass: top objectClass: organizationalUnit structuralObjectClass: organizationalUnit dn: ou=hosts,dc=saruman,dc=biz ou: hosts objectClass: top objectClass: organizationalUnit structuralObjectClass: organizationalUnit dn: ou=domains,dc=saruman,dc=biz ou: domains objectClass: top objectClass: organizationalUnit structuralObjectClass: organizationalUnit </pre> Let's suppose this file is named ''orgunits.ldif''. Now from the directory that contains this file, feed the information into your OpenLDAP using the following commands: sudo invoke-rc.d slapd stop sudo slapadd -c -v -l orgunits.ldif sudo invoke-rc.d slapd start This effectively stops the server, writes the information directly into the database, and then starts the server again. Another way to do the ''same'' thing, would be to add the information with the ''ldapadd'' command: ldapadd -c -x -D cn=admin,dc=saruman,dc=biz -W -f orgunits.ldif This binds to the OpenLDAP server (which must be running) using the admin account. This causes the command to request the admin password, and then feed the contents from the ''orgunits.ldif'' file into the database. ==Migrating User, Password and Group entries to an LDAP server== It's nice to have an LDAP, but it's ''much'' nicer if it is filled with information. We'll try to enter all existing users and groups from the host server into LDAP, using [[Migrating existing Unix users to OpenLDAP | the available migration tools]]. ==Creating new users == If we need new users (e.g. when the server you're setting up is spankin' new) then we can create them in several ways. Let's discuss two of them: === Adding a user with an LDIF file=== To add a user with the LDAP command line utilities, we first need to create an LDIF file. This file is a simple text file, that could look something like this: # Create the user group dn: cn=networkusers,ou=groups,dc=saruman,dc=biz objectClass: posixGroup description: Internal network users gidNumber: 10001 cn: TestGroup # Create a new user: dn: uid=sixpacjo,ou=people,dc=saruman,dc=biz objectclass: top objectclass: inetOrgPerson objectclass: posixAccount objectclass: shadowAccount cn: Joe Sixpack description: Your Average Network User givenName: Joe sn: Sixpack mail: joe.sixpack@saruman.biz # The Unix login-name for the user: uid: sixpacjo # The group and user IDs: gidNumber: 10001 uidNumber: 10001 # The Unix account data: homeDirectory: /home/sixpacjo loginShell: /bin/bash # The encrypted password for the user: userPassword: {crypt}$1$qs70ynbk$UBuewN7ZdIvqavIxkxdmX0 For a line-by-line explanation of this LDIF file, go [[LDIF syntax explanation | here]]. AHA! you'll say. But how do I get to this encrypted password? It's simple. Try this: openssl passwd -crypt "secret" The argument ''-crypt'' makes openssl generate a password using the standard Unix password algorithm; this is also the default setting. An alternative would be to use ''-1'' instead of ''-crypt'', which'll give you an MD5 encrypted password. Ofcourse, using an MD5 encrypted password means you have to change the last line of the LDIF file to userPassword: {MD5}$1$yCuyTf63$NoAjuX/dYBmE29hXrsDb41 Note that prefixing the used encryption method is totally fine with OpenLDAP, but it actually is not according to the LDAP standard; this LDIF file can be understood by OpenLDAP, but not by every other piece of LDAP software out there... === Adding a user with LAM=== 6d7a7b71d3100d6bb78559acfb01b1d44a5b4229 1689 1688 2008-09-25T17:08:18Z Saruman! 2 /* Creating your first Organizational Units */ added slapadd wikitext text/x-wiki == Creating your first Organizational Units == On the offchance that you haven't installed LAM, and thus haven't created the organizational units ''people'', ''groups'', ''hosts'' and ''domains'', here's how to create them manually. Create a file containing the following information: <pre> dn: ou=people,dc=saruman,dc=biz ou: people objectClass: top objectClass: organizationalUnit structuralObjectClass: organizationalUnit dn: ou=groups,dc=saruman,dc=biz ou: groups objectClass: top objectClass: organizationalUnit structuralObjectClass: organizationalUnit dn: ou=hosts,dc=saruman,dc=biz ou: hosts objectClass: top objectClass: organizationalUnit structuralObjectClass: organizationalUnit dn: ou=domains,dc=saruman,dc=biz ou: domains objectClass: top objectClass: organizationalUnit structuralObjectClass: organizationalUnit </pre> Let's suppose this file is named ''orgunits.ldif''. Now from the directory that contains this file, feed the information into your OpenLDAP using the following commands: sudo invoke-rc.d slapd stop sudo slapadd -c -v -l orgunits.ldif sudo invoke-rc.d slapd start This effectively stops the server, writes the information directly into the database, and then starts the server again. Another way to do (almost) the ''same'' thing, would be to add the information with the ''ldapadd'' command: ldapadd -c -x -D cn=admin,dc=saruman,dc=biz -W -f orgunits.ldif This binds to the OpenLDAP server (which must be running) using the admin account. This in turn causes the command to request the admin password, and then feed the contents from the ''orgunits.ldif'' file into the database. However, adding data to a live database precludes you from adding system controlled attributes, as structuralObjectClass is. So for live addition, remove those four particular lines from the ''orgunits.ldif'' file. Explanation of this difference: ''slapadd'' is meant as a restore tool, so it must (and can) create system controlled attributes. ''ldapadd'' is a modification tool, so it shouldn't need to (and can't) create these attributes. ==Migrating User, Password and Group entries to an LDAP server== It's nice to have an LDAP, but it's ''much'' nicer if it is filled with information. We'll try to enter all existing users and groups from the host server into LDAP, using [[Migrating existing Unix users to OpenLDAP | the available migration tools]]. ==Creating new users == If we need new users (e.g. when the server you're setting up is spankin' new) then we can create them in several ways. Let's discuss two of them: === Adding a user with an LDIF file=== To add a user with the LDAP command line utilities, we first need to create an LDIF file. This file is a simple text file, that could look something like this: # Create the user group dn: cn=networkusers,ou=groups,dc=saruman,dc=biz objectClass: posixGroup description: Internal network users gidNumber: 10001 cn: TestGroup # Create a new user: dn: uid=sixpacjo,ou=people,dc=saruman,dc=biz objectclass: top objectclass: inetOrgPerson objectclass: posixAccount objectclass: shadowAccount cn: Joe Sixpack description: Your Average Network User givenName: Joe sn: Sixpack mail: joe.sixpack@saruman.biz # The Unix login-name for the user: uid: sixpacjo # The group and user IDs: gidNumber: 10001 uidNumber: 10001 # The Unix account data: homeDirectory: /home/sixpacjo loginShell: /bin/bash # The encrypted password for the user: userPassword: {crypt}$1$qs70ynbk$UBuewN7ZdIvqavIxkxdmX0 For a line-by-line explanation of this LDIF file, go [[LDIF syntax explanation | here]]. AHA! you'll say. But how do I get to this encrypted password? It's simple. Try this: openssl passwd -crypt "secret" The argument ''-crypt'' makes openssl generate a password using the standard Unix password algorithm; this is also the default setting. An alternative would be to use ''-1'' instead of ''-crypt'', which'll give you an MD5 encrypted password. Ofcourse, using an MD5 encrypted password means you have to change the last line of the LDIF file to userPassword: {MD5}$1$yCuyTf63$NoAjuX/dYBmE29hXrsDb41 Note that prefixing the used encryption method is totally fine with OpenLDAP, but it actually is not according to the LDAP standard; this LDIF file can be understood by OpenLDAP, but not by every other piece of LDAP software out there... === Adding a user with LAM=== 6f065b73e62e535a3ef1128d1f0d1255e10c07e6 0 1473 1690 2008-09-26T16:29:17Z Saruman! 2 Page started wikitext text/x-wiki Suppose you use an LDIF file like this: # Create the user group dn: cn=networkusers,ou=groups,dc=saruman,dc=biz objectClass: posixGroup description: Internal network users gidNumber: 10001 cn: TestGroup # Create a new user: dn: uid=sixpacjo,ou=people,dc=saruman,dc=biz objectclass: top objectclass: inetOrgPerson objectclass: posixAccount objectclass: shadowAccount cn: Joe Sixpack description: Your Average Network User givenName: Joe sn: Sixpack mail: joe.sixpack@saruman.biz # The Unix login-name for the user: uid: sixpacjo # The group and user IDs: gidNumber: 10001 uidNumber: 10001 # The Unix account data: homeDirectory: /home/sixpacjo loginShell: /bin/bash # The encrypted password for the user: userPassword: {crypt}$1$qs70ynbk$UBuewN7ZdIvqavIxkxdmX0 What are you then actually doing? Well, you're adding two objects; the different attributes in this LDIF file are explained below. == Group object attributes == The first set of six lines describe an object of class posixGroup. The posixGroup class is part of the NIS schema, and an object of this class is "an abstraction of a group of accounts" (according to the description with the class definition. This means that in our example, the object with distinguished name ''cn=networkusers,ou=groups,dc=saruman,dc=biz'' will be a representation of a group as we know it from ''/etc/group''. So how do the six lines create this group? == User object attributes == fd9af8df12f0dcbdf7c1a55b5e195f03e7813cbf 0 1473 1691 1690 2008-09-26T20:16:32Z Saruman! 2 completed group object description wikitext text/x-wiki Suppose you use an LDIF file like this: # Create the user group dn: cn=networkusers,ou=groups,dc=saruman,dc=biz objectClass: posixGroup description: Internal network users gidNumber: 10001 cn: TestGroup # Create a new user: dn: uid=sixpacjo,ou=people,dc=saruman,dc=biz objectclass: top objectclass: inetOrgPerson objectclass: posixAccount objectclass: shadowAccount cn: Joe Sixpack description: Your Average Network User givenName: Joe sn: Sixpack mail: joe.sixpack@saruman.biz # The Unix login-name for the user: uid: sixpacjo # The group and user IDs: gidNumber: 10001 uidNumber: 10001 # The Unix account data: homeDirectory: /home/sixpacjo loginShell: /bin/bash # The encrypted password for the user: userPassword: {crypt}$1$qs70ynbk$UBuewN7ZdIvqavIxkxdmX0 What are you then actually doing? Well, you're adding two objects; the different attributes in this LDIF file are explained below. == Group object attributes == The first set of six lines describe an object of class posixGroup. The posixGroup class is part of the NIS schema, and an object of this class is "an abstraction of a group of accounts" (according to the description with the class definition. This means that in our example, the object with distinguished name ''cn=networkusers,ou=groups,dc=saruman,dc=biz'' will be a representation of a group as we know it from ''/etc/group''. So how do the six lines create this group? # The first line begins with a hash sign (#) making it a comment. It does nothing to create the object, only to clarify the LDIF file. We recomment strongly in favour of using comments, whenever your LDIF file must be kept longer than 10 minutes after creation :-). # '''dn:''' means the Distinguished Name; it tells the LDIF that this is the dn with which to address the object. # '''objectClass:''' this defines what attributes the object must and may have. Want to know which attributes? Look into /etc/ldap/schema/nis.schema and find the string 'posixGroup'. You'll see that the mandatory attributes are ''cn'' and ''gidNumber'', and optional attributes ''userPassword'', ''memberUid'' and ''description'' # '''description:''' hey, that's one of them optional attributes! It has no equivalent in the Posix ''group'' definition, but it can ofcourse clarify the purpose of said group in the LDAP directory. # '''gidNumber:''' mandatory attribute, that holds the "numerical value of the group's ID" # '''cn:''' this is the second mandatory attribute, and holds the name of the group Since there's an empty line after these six lines, the rest of the LDIF file does not concern the group object; all adjacent lines are held to be a declaration of one single object. It should be clear that the above information is sufficient to create in LDAP an object that holds all information that any POSIX compliant group would need. Creating an object of type posixGroup in this manner makes it possible to use the object in LDAP as if it were a group on the local Linux/UNIX machine. == User object attributes == The next section of this particular LDIF file consists of 21 adjacent lines, of which five begin with a hash sign. The other 16 lines comprise the actual object. So how does this object form in LDAP when you feed it this LDIF file? d14f7b25a0dbbdaa6d31cdca42b795bd1e73c001 1692 1691 2008-09-27T09:47:26Z Saruman! 2 Added text on the user creation syntax wikitext text/x-wiki Suppose you use an LDIF file like this: # Create the user group dn: cn=networkusers,ou=groups,dc=saruman,dc=biz objectClass: posixGroup gidNumber: 10001 cn: TestGroup description: Internal network users # Create a new user: dn: uid=sixpacjo,ou=people,dc=saruman,dc=biz objectClass: top objectClass: posixAccount objectClass: shadowAccount objectClass: inetOrgPerson cn: Joe Sixpack description: Your Average Network User givenName: Joe sn: Sixpack mail: joe.sixpack@saruman.biz mail: j.sixpack@saruman.biz # The Unix login-name for the user: uid: sixpacjo # The group and user IDs: gidNumber: 10001 uidNumber: 10001 # The Unix account data: homeDirectory: /home/sixpacjo loginShell: /bin/bash # The encrypted password for the user: userPassword: {crypt}$1$qs70ynbk$UBuewN7ZdIvqavIxkxdmX0 What are you then actually doing? Well, you're adding two objects; the different attributes in this LDIF file are explained below. Note that this is not an exhaustive explanation of the syntax, just a quick primer for those too busy to look up the official documentation (as is most of this wiki). == Group object attributes == The first set of six lines describe an object of class posixGroup. The posixGroup class is part of the NIS schema, and an object of this class is "an abstraction of a group of accounts" (according to the description with the class definition. This means that in our example, the object with distinguished name ''cn=networkusers,ou=groups,dc=saruman,dc=biz'' will be a representation of one single group as we know it from ''/etc/group''. So how do the six lines together define this single group? Let's look at the entries again: # Create the user group dn: cn=networkusers,ou=groups,dc=saruman,dc=biz objectClass: posixGroup gidNumber: 10001 cn: TestGroup description: Internal network users * The first line begins with a hash sign (#) making it a comment. It does nothing to create the object, only to clarify the LDIF file. We recomment strongly in favour of using comments, whenever your LDIF file must be kept longer than 10 minutes after creation :-). * '''dn:''' means the Distinguished Name; it tells the LDIF that this is the dn with which to address the object. * '''objectClass:''' this defines what attributes the object must and may have. Want to know which attributes? Look into /etc/ldap/schema/nis.schema and find the string 'posixGroup'. You'll see that the mandatory attributes are ''cn'' and ''gidNumber'', and optional attributes ''userPassword'', ''memberUid'' and ''description'' * '''gidNumber:''' mandatory attribute, that holds the "numerical value of the group's ID" * '''cn:''' this is the second mandatory attribute, and holds the name of the group. We could also have used the full attribute name '''commonName:''', but really "cn" is the prevalent form. * '''description:''' hey, that's one of them optional attributes! It has no equivalent in the Posix ''group'' definition, but it can ofcourse clarify the purpose of said group in the LDAP directory. Since there's an empty line after these six lines, the rest of the LDIF file does not concern this particular group object; a set of adjacent lines are held to be a declaration of one single object. It should be clear that the above information is sufficient to create in LDAP an object that holds all information that any POSIX compliant group would need. Creating an object of type posixGroup in this manner makes it possible to use the object in LDAP as if it were a group on the local Linux/Unix machine, i.e. it can map directly to a Linux/Unix group. == User object attributes == The next section of this particular LDIF file consists of 22 adjacent lines, of which five begin with a hash sign. The other 17 lines define the actual object. So how does this object form in LDAP when you feed it this LDIF file? Here is that section again, stripped of its comments: dn: uid=sixpacjo,ou=people,dc=saruman,dc=biz objectClass: top objectClass: posixAccount objectClass: shadowAccount objectClass: inetOrgPerson cn: Joe Sixpack description: Your Average Network User givenName: Joe sn: Sixpack mail: joe.sixpack@saruman.biz mail: j.sixpack@saruman.biz uid: sixpacjo gidNumber: 10001 uidNumber: 10001 homeDirectory: /home/sixpacjo loginShell: /bin/bash userPassword: {crypt}$1$qs70ynbk$UBuewN7ZdIvqavIxkxdmX0 * '''dn:''' again tells the LDIF that this is the Distinguished Name with which to address the object. * four lines of '''objectClass:''': these multiple lines tell OpenLDAP that the object has all the attributes that are described in those four classes (top, inetOrgPerson, posixAccount and shadowAccount). ** class ''top'': this is a special class ("abstract" class) that actually doesn't even exist. It is the root of the tree of classes we're going to use. If you leave this class out, it doesn't change a bit (the presence of this class is always implied). So why put it in? We don't know, it's sort of a best practice, we think... ** class ''posixAccount'': defined in the ''nis.schema'' file. Contains five mandatory attributes plus four optional, that together contain all necessary information to create a Linux user account. ** class ''shadowAccount'': defined in the ''nis.schema'' file. Contains the mandatory attribute ''uid'' and nine optional attributes that can be used to maintain shadow passwords - as does Linux. The ''uid'' attribute, as well as optional attributes ''userPassword'' and ''description'' also appear in class ''posixAccount'', so adding this class to our user object actually only provides seven additional optional attributes. ** class ''inetOrgPerson'': defined in the dedicated ''inetorgperson.schema'' file, it contains 27 optional attributes. We want these in our LDAP account mainly because it gives us the attribute ''mail'' that we forsee we'll be using to add LDAP support to our mail server solution. * '''cn:''' is again the Common Name. In the context of a person's LDAP account, you may read "full name". Hence the full name "Joe Sixpack" in there. When using the ''useradd'' command under Linux, we usually put this information in the "comment" field (''useradd -c "Joe Sixpack" sixpajo''). * '''description:''' is again an optional attribute; we use it here to clarify the status of the account. * '''givenName:''' is a field that we use to hold the user's first name ("Joe"). * '''sn:''' contains the surname, or as the ''core.schema'' definition says: "'RFC2256: last (family) name(s) for which the entity is known by". * '''mail:''' is the (optional) field from the inetOrgPerson class that holds the person's email address or addresses (in RFC822 format). As it can be multi-valued, we've specified it twice for Joe. * '''uid:''' or '''userid:''' is the single-valued unique "RFC1274: user identifier" that we designate to be the user's login name. * '''gidNumber:''' according to the ''nis.schema'' file this holds "An integer uniquely identifying a group in an administrative domain"; we can thus use it as the group ID number under Linux. * '''uidNumber:''' - Like the gidNumber this is "An integer uniquely identifying a user in an administrative domain"; we can use it as the Linux user ID number. * '''homeDirectory:''' - This case sensitive single-value attribute holds the absolute path to the user's home directory. * '''loginShell:''' is also case sensitive, single-valued, and contains - wait for it... - the user's login shell!! * '''userPassword:''' comes from the ''core.schema'' file, and contains "RFC2256/2307: password of user". Usually, the password in this field is encrypted. When defining a new user, putting an encrypted value for the password in here takes some extra effort, as explained in the section below ==Specifying passwords in LDIF files== So in the previous we've read that the userPassword attribute must be specified in an encrypted form. "AHA!" you'll say. "But how do I obtain such an encrypted password?" Fortunately, that's quite simple. Try this: openssl passwd -crypt "secret" The argument ''-crypt'' makes openssl generate a password using the standard Unix password algorithm; this is also the default setting. An alternative would be to use ''-1'' instead of ''-crypt'', which'll give you an MD5 encrypted password. Ofcourse, using an MD5 encrypted password means you have to change the last line of the LDIF file to something like userPassword: {MD5}$1$yCuyTf63$NoAjuX/dYBmE29hXrsDb41 Note that prefixing the used encryption method is totally fine with OpenLDAP, but it actually is not according to the LDAP standard; this LDIF file can be understood by OpenLDAP, but not by every other piece of LDAP software out there... However, since this is actually a Linux oriented Wiki, and we're discussing OpenLDAP here, we're going to say: put the encryption type in! c82577b21560c004922f6ee387cce63c627fa590 1694 1692 2008-09-27T13:47:19Z Saruman! 2 /* Specifying passwords in LDIF files */ added slappasswd instead of openssl as pw hasher wikitext text/x-wiki Suppose you use an LDIF file like this: # Create the user group dn: cn=networkusers,ou=groups,dc=saruman,dc=biz objectClass: posixGroup gidNumber: 10001 cn: TestGroup description: Internal network users # Create a new user: dn: uid=sixpacjo,ou=people,dc=saruman,dc=biz objectClass: top objectClass: posixAccount objectClass: shadowAccount objectClass: inetOrgPerson cn: Joe Sixpack description: Your Average Network User givenName: Joe sn: Sixpack mail: joe.sixpack@saruman.biz mail: j.sixpack@saruman.biz # The Unix login-name for the user: uid: sixpacjo # The group and user IDs: gidNumber: 10001 uidNumber: 10001 # The Unix account data: homeDirectory: /home/sixpacjo loginShell: /bin/bash # The encrypted password for the user: userPassword: {crypt}$1$qs70ynbk$UBuewN7ZdIvqavIxkxdmX0 What are you then actually doing? Well, you're adding two objects; the different attributes in this LDIF file are explained below. Note that this is not an exhaustive explanation of the syntax, just a quick primer for those too busy to look up the official documentation (as is most of this wiki). == Group object attributes == The first set of six lines describe an object of class posixGroup. The posixGroup class is part of the NIS schema, and an object of this class is "an abstraction of a group of accounts" (according to the description with the class definition. This means that in our example, the object with distinguished name ''cn=networkusers,ou=groups,dc=saruman,dc=biz'' will be a representation of one single group as we know it from ''/etc/group''. So how do the six lines together define this single group? Let's look at the entries again: # Create the user group dn: cn=networkusers,ou=groups,dc=saruman,dc=biz objectClass: posixGroup gidNumber: 10001 cn: TestGroup description: Internal network users * The first line begins with a hash sign (#) making it a comment. It does nothing to create the object, only to clarify the LDIF file. We recomment strongly in favour of using comments, whenever your LDIF file must be kept longer than 10 minutes after creation :-). * '''dn:''' means the Distinguished Name; it tells the LDIF that this is the dn with which to address the object. * '''objectClass:''' this defines what attributes the object must and may have. Want to know which attributes? Look into /etc/ldap/schema/nis.schema and find the string 'posixGroup'. You'll see that the mandatory attributes are ''cn'' and ''gidNumber'', and optional attributes ''userPassword'', ''memberUid'' and ''description'' * '''gidNumber:''' mandatory attribute, that holds the "numerical value of the group's ID" * '''cn:''' this is the second mandatory attribute, and holds the name of the group. We could also have used the full attribute name '''commonName:''', but really "cn" is the prevalent form. * '''description:''' hey, that's one of them optional attributes! It has no equivalent in the Posix ''group'' definition, but it can ofcourse clarify the purpose of said group in the LDAP directory. Since there's an empty line after these six lines, the rest of the LDIF file does not concern this particular group object; a set of adjacent lines are held to be a declaration of one single object. It should be clear that the above information is sufficient to create in LDAP an object that holds all information that any POSIX compliant group would need. Creating an object of type posixGroup in this manner makes it possible to use the object in LDAP as if it were a group on the local Linux/Unix machine, i.e. it can map directly to a Linux/Unix group. == User object attributes == The next section of this particular LDIF file consists of 22 adjacent lines, of which five begin with a hash sign. The other 17 lines define the actual object. So how does this object form in LDAP when you feed it this LDIF file? Here is that section again, stripped of its comments: dn: uid=sixpacjo,ou=people,dc=saruman,dc=biz objectClass: top objectClass: posixAccount objectClass: shadowAccount objectClass: inetOrgPerson cn: Joe Sixpack description: Your Average Network User givenName: Joe sn: Sixpack mail: joe.sixpack@saruman.biz mail: j.sixpack@saruman.biz uid: sixpacjo gidNumber: 10001 uidNumber: 10001 homeDirectory: /home/sixpacjo loginShell: /bin/bash userPassword: {crypt}$1$qs70ynbk$UBuewN7ZdIvqavIxkxdmX0 * '''dn:''' again tells the LDIF that this is the Distinguished Name with which to address the object. * four lines of '''objectClass:''': these multiple lines tell OpenLDAP that the object has all the attributes that are described in those four classes (top, inetOrgPerson, posixAccount and shadowAccount). ** class ''top'': this is a special class ("abstract" class) that actually doesn't even exist. It is the root of the tree of classes we're going to use. If you leave this class out, it doesn't change a bit (the presence of this class is always implied). So why put it in? We don't know, it's sort of a best practice, we think... ** class ''posixAccount'': defined in the ''nis.schema'' file. Contains five mandatory attributes plus four optional, that together contain all necessary information to create a Linux user account. ** class ''shadowAccount'': defined in the ''nis.schema'' file. Contains the mandatory attribute ''uid'' and nine optional attributes that can be used to maintain shadow passwords - as does Linux. The ''uid'' attribute, as well as optional attributes ''userPassword'' and ''description'' also appear in class ''posixAccount'', so adding this class to our user object actually only provides seven additional optional attributes. ** class ''inetOrgPerson'': defined in the dedicated ''inetorgperson.schema'' file, it contains 27 optional attributes. We want these in our LDAP account mainly because it gives us the attribute ''mail'' that we forsee we'll be using to add LDAP support to our mail server solution. * '''cn:''' is again the Common Name. In the context of a person's LDAP account, you may read "full name". Hence the full name "Joe Sixpack" in there. When using the ''useradd'' command under Linux, we usually put this information in the "comment" field (''useradd -c "Joe Sixpack" sixpajo''). * '''description:''' is again an optional attribute; we use it here to clarify the status of the account. * '''givenName:''' is a field that we use to hold the user's first name ("Joe"). * '''sn:''' contains the surname, or as the ''core.schema'' definition says: "'RFC2256: last (family) name(s) for which the entity is known by". * '''mail:''' is the (optional) field from the inetOrgPerson class that holds the person's email address or addresses (in RFC822 format). As it can be multi-valued, we've specified it twice for Joe. * '''uid:''' or '''userid:''' is the single-valued unique "RFC1274: user identifier" that we designate to be the user's login name. * '''gidNumber:''' according to the ''nis.schema'' file this holds "An integer uniquely identifying a group in an administrative domain"; we can thus use it as the group ID number under Linux. * '''uidNumber:''' - Like the gidNumber this is "An integer uniquely identifying a user in an administrative domain"; we can use it as the Linux user ID number. * '''homeDirectory:''' - This case sensitive single-value attribute holds the absolute path to the user's home directory. * '''loginShell:''' is also case sensitive, single-valued, and contains - wait for it... - the user's login shell!! * '''userPassword:''' comes from the ''core.schema'' file, and contains "RFC2256/2307: password of user". Usually, the password in this field is encrypted. When defining a new user, putting an encrypted value for the password in here takes some extra effort, as explained in the section below ==Specifying passwords in LDIF files== So in the previous we've read that the userPassword attribute must be specified in an encrypted form ("hashed" would be a better term, but there you go....). "AHA!" you'll say. "But how do I obtain such an encrypted password?" Fortunately, that's quite simple. Try this: slappasswd -u -h {SSHA} -s secret The argument ''-u'' tells slappasswd that you're interested in generating an RFC 2307 compliant userPassword (this is the default, so you could leave out the ''-u''). The ''-h {SSHA}'' tells the command to use SSHA as hashing method, and ''-s secret'' specifies that you want to hash the word "secret". If you want to hash password "H4ckm3!", you'd get something like this: slappasswd -u -h {SSHA} -s H4ckm3! {SSHA}uPeS2Pxi4pzTPNOx+ZUVh21WPPeyJWrV You can take the hash string, inclusive of the {SSHA} prefix, and put it in an LDIF file for processing by OpenLDAP; it will Note that prefixing the used encryption method is totally fine with OpenLDAP, but it actually is not according to the LDAP standard; this LDIF file can be understood by OpenLDAP, but not by every other piece of LDAP software out there... However, since this is actually a Linux oriented Wiki, and we're discussing OpenLDAP here, we're going to say: put the encryption type in! fac088d5ffc55127d644b8f3e2bd040d439b66cb 0 1467 1693 1686 2008-09-27T09:58:13Z Saruman! 2 /* OpenLDAP installation and configuration */ added password-hash wikitext text/x-wiki == OpenLDAP installation and configuration== Note: we're going to install OpenLDAP on our server as [http://www.openldap.org/doc/admin24/config.html#Local%20Directory%20Service the local directory service], without replication, referrals or other advanced features. Installing OpenLDAP on your Debian server is ridiculously simple. Just make sure your server is up-to-date (''sudo apt-get update'' followed by ''sudo apt-get upgrade''), and then install the two main components for your OpenLDAP server: sudo apt-get install slapd ldap-utils The Debian configuration script will ask you for only one single thing: an administrator password. As always: generate a strong password! When you've provided the password, the LDAP database is created with the administrator name "admin" and as a base directory path, something based on your DNS name. Suppose your internal domain is "amber.lan.", then the script will generate ''suffix "dc=amber,dc=lan,dc="''. The last, empty, domain component (''dc'') is caused by the trailing dot in your DNS name: the DNS root. Since this might not always be the most convenient configuration, we recommend that you run the configuration again using ''dpkg-reconfigure slapd''. Interestingly enough, this reconfiguration asks you many ''more'' questions. The answers could look like this: omit OpenLDAP config: no DNS domain name: saruman.biz Organization name: Saruman Administrator passwd: wEt3udes Database backend: HDB DB remove after purge: no Move old DB: yes Allow LDAPv2: no As you can see, the reconfiguration yields much more configuration options than plain installation - although really you'll probably answer most questions with their default values anyway, with the exception of the database backend, which by default is BDB.<br> Anyway, the above method of configuring yields you an LDAP database with only two objects in it: * a single Organization (o="Saruman") with Distinguished Name dn="dc=saruman,dc=biz" * a single administrator with Common Name cn="admin", and dn="cn=admin,dc=saruman,dc=biz" The database that your OpenLDAP server uses is a standard Berkeley DB (BDB) database. Now we most likely will require some other databases as well in our server setup, something modern like PostgreSQL or MySQL - so why don't we configure our OpenLDAP to use this same database as well? For the answer, see [http://www.openldap.org/doc/admin24/intro.html#LDAP%20vs%20RDBMS here] - in short, the LDAP tree structure does not lend itself very well to inclusion in a modern relational database. Thus, we advise to stick with the Berkeley database provided with OpenLDAP.<br> Now, for the database backend, we have the choice between two almost identical flavours: the ''bdb'' backend is the recommended primary backend for a normal slapd database. It uses the Oracle Berkeley DB package, referred to as ''BDB'', to store data. It makes extensive use of indexing and caching to speed data access. ''hdb'' is a variant of the ''bdb'' backend that uses a hierarchical database layout which supports subtree renames. It is otherwise identical to the ''bdb'' behavior, and all the same configuration options apply. To finetune the OpenLDAP configuration, we make some changes to the main configuration file for the OpenLDAP server, ''/etc/ldap/slapd.conf'': We find the line beginning with "loglevel" and change it from ''none'' to ''256''. This value means connections/operations/results wil be logged to the ''syslogd'' daemon. There, it will be logged to the ''LOG_LOCAL4'' facility. The default hash algorithm for encrypting user passwords is {SSHA}, which is the SHA-1 algorithm (FIPS160-1) wit a seed number. However, OpenLDAP can understand more hashes, even multiple at the same time. To specify which hash or hashes, we can specify something like password-hash {SSHA} {MD5} Valid hashes are {SHA}, {SSHA} (the default, {MD5}, {SMD5}, {CRYPT} and {CLEARTEXT}. We usually don't need to change the default, but if you do, put in the directive and restart your LDAP server. More information: "man 5 slapd.conf". We find the line beginning with ''index'', and add a second line to it. This will make the section look like this: index objectClass eq index uid eq The purpose of this change is to make the OpenLDAP server create another index, on LDAP attribute ''uid''. This is important, because under some circumstances you might not receive any result on a valid query unless the searched entries are indexed. This entry makes sure all objects with a ''uid'' attribute are indexed, and thus can be found when queried. Finally, we check to be certain all necessary schema's are included: in the beginning of the file we should see include /etc/ldap/schema/core.schema include /etc/ldap/schema/cosine.schema include /etc/ldap/schema/nis.schema include /etc/ldap/schema/inetorgperson.schema If any line got missing, we need to (re)enter it in order to be able to create the LDAP entries that we want. After these little refinements, we must stop, reindex, and restart the OpenLDAP server. This can be done with the following sequence of commands: sudo invoke-rc.d slapd stop sudo -u openldap slapindex sudo invoke-rc.d slapd start Note: you need to have your ''sudo'' configured to allow you to ''su'' to user ''openldap'' in order to run the second command. ==Installing and configuring an LDAP Account Manager== It's perfectly normal to manipulate your LDAP from the command line using LDAP utilities like ''ldapsearch'', ''ldapadd'', ''ldapdelete'' and ''ldapmodify'', as well as ''slapcat'', ''slappasswd'' etcetera. However, many people find a GUI for LDAP indispensible. If you are amongst those, then for you, my friend, the question becomes: which graphic tool do you want to use? Many people speak highly of ''[http://gq-project.org/ gq]'', ''[http://luma.sourceforge.net/about.html luma]'' and ''[http://phpldapadmin.sourceforge.net/ phpldapadmin]''. We go for ''lam'' ([http://lam.sourceforge.net/index.htm LDAP acount Manager]).<br> To install ''lam'', first ensure that you have installed Apache2 and PHP5. Then we can use ''apt-get install ldap-account-manager''. After installation, we can right away surf to http://<server-IP>/lam, where we can log in. However, note that in the upper right, there's a link ''LAM configuration''. We'll go there first. Under the LAM configuration page, there are two links to areas, where settings can be specified. The first one is "Edit general settings", and clicking it prompts you for a master password - by default this is "lam". Behind that password is a simple settings page, that can be filled with values like this ('''bold''' values deviate from the default): * Security settings ** Session timeout: '''15''' (the amount of minutes of inactivity that's allowed before a user is logged off) ** Allowed hosts: '''192.168.67.*''' (the range of IP numbers from which LAM accepts connections; empty would mean "all" so we recommend limiting the scope to your internal network, or even less if possible. Multiple hosts or network ranges can be inserted below each other) * Password policy (in this section you can specify lower limits on your LDAP passwords - tho currently it's not clear to us what you're limiting. We suspect it's the creation of all LDAP passwords from within LAM). ** Minimum password length: '''6''' ** Minimum lowercase characters: 0 ** Minimum uppercase characters: 0 ** Minimum numeric characters: 0 ** Minimum symbolic characters: 0 ** Minimum character classes: '''3''' (The character classes are: lowercase, uppercase, numeric and symbols) * Logging ** Log level: notice (this is the most detailed level; "warning" logs less information, "error" less still) ** Log destination: syslog (outputs all LAM messages to the syslogger; alternatively specify "no logging" or a file name & location) * Change master password ** New master password: '''*****''' (this is the password that'll replace "lam" to log into the LAM configuration; it is NOT the password of your rootdn, and if anywhere possible, you should avoid using that particular password here - for safety. Generate [http://www.pctools.com/guides/password/ yet another strong password].) ** Reenter new master password: '''*****''' After entering the above settings, we at least know LAM is operational, and coarsely secured (it's not using SSL yet). Click ''OK'' to save, or ''back to login'' if you change your mind and just want to go back. The second link from the LAM configuration page, "Edit server profiles" will again prompt you. However, this password prompt page contains an extra pulldown option, currently filled with the word "lam". This is because there is only one server profile, named "lam", and filled with some default values for your LDAP server. And under those two boxes, there's a link "manage server profiles".<br> Now first we'll rename that profile to something more descriptive. Click the "manage server profiles" link, in the "profile management page" check the radio button next to ''&#091;lam&#093; Rename profile'', put in the new name (e.g. "sarumanbiz"), fill in the shiny new master LAM password &#8212; it should no longer be the default "lam" since you've changed it, in line with the paragraph above :-) &#8212; and then click OK. Presto! The server profile is renamed.<br> When you now enter your password to edit the server preferences for profile "sarumanbiz", you get to a page with a lot of settings; the only ones we're currently interested in are: * Server settings ** Server address: ldap://localhost:389 (verify that it's either localhost, if both the LDAP server and your LAM Apache2 are on the same machine, or a correct IP address or DNS name if that's not the case) ** Tree Suffix: '''dc=saruman,dc=biz''' (the same suffix you've installed your LDAP server with) * Account types ** Edit Account types *** Users **** LDAP Suffix: '''ou=people,dc=saruman,dc=biz''' (You'll have to designate an OU in which to store user accounts; it does not have to exist yet (LAM can create it for you any time you log in) but the base has to be accessible; in our example: saruman.biz. Any name will do, but since we're storing identities, and not specifically users, we're calling the OU "people") *** Groups **** LDAP Suffix: '''ou=groups,dc=saruman,dc=biz''' (This is the OU where groups will be stored) *** Hosts **** LDAP Suffix: '''ou=hosts,dc=saruman,dc=biz''' (This is where machines, i.e. hosts, will be stored) *** Samba domains **** LDAP Suffix: '''ou=domains,dc=saruman,dc=biz''' (This is where all Windows workgroups/domains will wind up) * Security settings ** List of valid users: '''cn=admin,dc=saruman,dc=biz''' (or whatever you've designated your root DN) ** New password: '''''leave empty''''' (because this is to change the master password to edit ''this'' server profile; when this remains empty, the "master master password" for LAM remains in effect) ** Reenter password: (make this the same as the new password, i.e. empty) Now click OK, and your LAM should be ready to go. When you first log into the LAM profile you've just created, LAM will ask you if it should create the four OU's you've designated for people/groups/machines/domains. This is a nice test: if LAM cannot create those OU's, then you've misconfigured it (or the LDAP tree itself). If it can, then you'll be able to click ''tree view'' and browse the LDAP tree. At least the administrator (e.g. cn=admin) and the four OU's (e.g. domains/groups/hosts/people) should be present under the root (e.g. dc=saruman,dc=biz).<br> Incidentally, the configuration you've just entered into LAM as profile "sarumanbiz" can also be found at ''/usr/share/ldap-account-manager/config/sarumanbiz.conf'', so if need be, you can edit the profile by hand. ==Securing LAM communications with SSL== Until just now, all communications with LAM have taken place over unencrypted connections - not a nice way to work in a production environment. We really need to use SSL to secure the LAM environment. Fortunately, that is as easy as enabling SSL on the underlying Apache2 webserver. This completes the setup of the LDAP server. To fill it with relevant data, go to [[Filling an OpenLDAP database | the next section]]. 1f2ce9f332aeaf65441a5df5352349d02ed26962 1705 1693 2008-09-28T16:43:02Z Saruman! 2 end section wikitext text/x-wiki == OpenLDAP installation and configuration== Note: we're going to install OpenLDAP on our server as [http://www.openldap.org/doc/admin24/config.html#Local%20Directory%20Service the local directory service], without replication, referrals or other advanced features. Installing OpenLDAP on your Debian server is ridiculously simple. Just make sure your server is up-to-date (''sudo apt-get update'' followed by ''sudo apt-get upgrade''), and then install the two main components for your OpenLDAP server: sudo apt-get install slapd ldap-utils The Debian configuration script will ask you for only one single thing: an administrator password. As always: generate a strong password! When you've provided the password, the LDAP database is created with the administrator name "admin" and as a base directory path, something based on your DNS name. Suppose your internal domain is "amber.lan.", then the script will generate ''suffix "dc=amber,dc=lan,dc="''. The last, empty, domain component (''dc'') is caused by the trailing dot in your DNS name: the DNS root. Since this might not always be the most convenient configuration, we recommend that you run the configuration again using ''dpkg-reconfigure slapd''. Interestingly enough, this reconfiguration asks you many ''more'' questions. The answers could look like this: omit OpenLDAP config: no DNS domain name: saruman.biz Organization name: Saruman Administrator passwd: wEt3udes Database backend: HDB DB remove after purge: no Move old DB: yes Allow LDAPv2: no As you can see, the reconfiguration yields much more configuration options than plain installation - although really you'll probably answer most questions with their default values anyway, with the exception of the database backend, which by default is BDB.<br> Anyway, the above method of configuring yields you an LDAP database with only two objects in it: * a single Organization (o="Saruman") with Distinguished Name dn="dc=saruman,dc=biz" * a single administrator with Common Name cn="admin", and dn="cn=admin,dc=saruman,dc=biz" The database that your OpenLDAP server uses is a standard Berkeley DB (BDB) database. Now we most likely will require some other databases as well in our server setup, something modern like PostgreSQL or MySQL - so why don't we configure our OpenLDAP to use this same database as well? For the answer, see [http://www.openldap.org/doc/admin24/intro.html#LDAP%20vs%20RDBMS here] - in short, the LDAP tree structure does not lend itself very well to inclusion in a modern relational database. Thus, we advise to stick with the Berkeley database provided with OpenLDAP.<br> Now, for the database backend, we have the choice between two almost identical flavours: the ''bdb'' backend is the recommended primary backend for a normal slapd database. It uses the Oracle Berkeley DB package, referred to as ''BDB'', to store data. It makes extensive use of indexing and caching to speed data access. ''hdb'' is a variant of the ''bdb'' backend that uses a hierarchical database layout which supports subtree renames. It is otherwise identical to the ''bdb'' behavior, and all the same configuration options apply. To finetune the OpenLDAP configuration, we make some changes to the main configuration file for the OpenLDAP server, ''/etc/ldap/slapd.conf'': We find the line beginning with "loglevel" and change it from ''none'' to ''256''. This value means connections/operations/results wil be logged to the ''syslogd'' daemon. There, it will be logged to the ''LOG_LOCAL4'' facility. The default hash algorithm for encrypting user passwords is {SSHA}, which is the SHA-1 algorithm (FIPS160-1) wit a seed number. However, OpenLDAP can understand more hashes, even multiple at the same time. To specify which hash or hashes, we can specify something like password-hash {SSHA} {MD5} Valid hashes are {SHA}, {SSHA} (the default, {MD5}, {SMD5}, {CRYPT} and {CLEARTEXT}. We usually don't need to change the default, but if you do, put in the directive and restart your LDAP server. More information: "man 5 slapd.conf". We find the line beginning with ''index'', and add a second line to it. This will make the section look like this: index objectClass eq index uid eq The purpose of this change is to make the OpenLDAP server create another index, on LDAP attribute ''uid''. This is important, because under some circumstances you might not receive any result on a valid query unless the searched entries are indexed. This entry makes sure all objects with a ''uid'' attribute are indexed, and thus can be found when queried. Finally, we check to be certain all necessary schema's are included: in the beginning of the file we should see include /etc/ldap/schema/core.schema include /etc/ldap/schema/cosine.schema include /etc/ldap/schema/nis.schema include /etc/ldap/schema/inetorgperson.schema If any line got missing, we need to (re)enter it in order to be able to create the LDAP entries that we want. After these little refinements, we must stop, reindex, and restart the OpenLDAP server. This can be done with the following sequence of commands: sudo invoke-rc.d slapd stop sudo -u openldap slapindex sudo invoke-rc.d slapd start Note: you need to have your ''sudo'' configured to allow you to ''su'' to user ''openldap'' in order to run the second command. ==Installing and configuring an LDAP Account Manager== It's perfectly normal to manipulate your LDAP from the command line using LDAP utilities like ''ldapsearch'', ''ldapadd'', ''ldapdelete'' and ''ldapmodify'', as well as ''slapcat'', ''slappasswd'' etcetera. However, many people find a GUI for LDAP indispensible. If you are amongst those, then for you, my friend, the question becomes: which graphic tool do you want to use? Many people speak highly of ''[http://gq-project.org/ gq]'', ''[http://luma.sourceforge.net/about.html luma]'' and ''[http://phpldapadmin.sourceforge.net/ phpldapadmin]''. We go for ''lam'' ([http://lam.sourceforge.net/index.htm LDAP acount Manager]).<br> To install ''lam'', first ensure that you have installed Apache2 and PHP5. Then we can use ''apt-get install ldap-account-manager''. After installation, we can right away surf to http://<server-IP>/lam, where we can log in. However, note that in the upper right, there's a link ''LAM configuration''. We'll go there first. Under the LAM configuration page, there are two links to areas, where settings can be specified. The first one is "Edit general settings", and clicking it prompts you for a master password - by default this is "lam". Behind that password is a simple settings page, that can be filled with values like this ('''bold''' values deviate from the default): * Security settings ** Session timeout: '''15''' (the amount of minutes of inactivity that's allowed before a user is logged off) ** Allowed hosts: '''192.168.67.*''' (the range of IP numbers from which LAM accepts connections; empty would mean "all" so we recommend limiting the scope to your internal network, or even less if possible. Multiple hosts or network ranges can be inserted below each other) * Password policy (in this section you can specify lower limits on your LDAP passwords - tho currently it's not clear to us what you're limiting. We suspect it's the creation of all LDAP passwords from within LAM). ** Minimum password length: '''6''' ** Minimum lowercase characters: 0 ** Minimum uppercase characters: 0 ** Minimum numeric characters: 0 ** Minimum symbolic characters: 0 ** Minimum character classes: '''3''' (The character classes are: lowercase, uppercase, numeric and symbols) * Logging ** Log level: notice (this is the most detailed level; "warning" logs less information, "error" less still) ** Log destination: syslog (outputs all LAM messages to the syslogger; alternatively specify "no logging" or a file name & location) * Change master password ** New master password: '''*****''' (this is the password that'll replace "lam" to log into the LAM configuration; it is NOT the password of your rootdn, and if anywhere possible, you should avoid using that particular password here - for safety. Generate [http://www.pctools.com/guides/password/ yet another strong password].) ** Reenter new master password: '''*****''' After entering the above settings, we at least know LAM is operational, and coarsely secured (it's not using SSL yet). Click ''OK'' to save, or ''back to login'' if you change your mind and just want to go back. The second link from the LAM configuration page, "Edit server profiles" will again prompt you. However, this password prompt page contains an extra pulldown option, currently filled with the word "lam". This is because there is only one server profile, named "lam", and filled with some default values for your LDAP server. And under those two boxes, there's a link "manage server profiles".<br> Now first we'll rename that profile to something more descriptive. Click the "manage server profiles" link, in the "profile management page" check the radio button next to ''&#091;lam&#093; Rename profile'', put in the new name (e.g. "sarumanbiz"), fill in the shiny new master LAM password &#8212; it should no longer be the default "lam" since you've changed it, in line with the paragraph above :-) &#8212; and then click OK. Presto! The server profile is renamed.<br> When you now enter your password to edit the server preferences for profile "sarumanbiz", you get to a page with a lot of settings; the only ones we're currently interested in are: * Server settings ** Server address: ldap://localhost:389 (verify that it's either localhost, if both the LDAP server and your LAM Apache2 are on the same machine, or a correct IP address or DNS name if that's not the case) ** Tree Suffix: '''dc=saruman,dc=biz''' (the same suffix you've installed your LDAP server with) * Account types ** Edit Account types *** Users **** LDAP Suffix: '''ou=people,dc=saruman,dc=biz''' (You'll have to designate an OU in which to store user accounts; it does not have to exist yet (LAM can create it for you any time you log in) but the base has to be accessible; in our example: saruman.biz. Any name will do, but since we're storing identities, and not specifically users, we're calling the OU "people") *** Groups **** LDAP Suffix: '''ou=groups,dc=saruman,dc=biz''' (This is the OU where groups will be stored) *** Hosts **** LDAP Suffix: '''ou=hosts,dc=saruman,dc=biz''' (This is where machines, i.e. hosts, will be stored) *** Samba domains **** LDAP Suffix: '''ou=domains,dc=saruman,dc=biz''' (This is where all Windows workgroups/domains will wind up) * Security settings ** List of valid users: '''cn=admin,dc=saruman,dc=biz''' (or whatever you've designated your root DN) ** New password: '''''leave empty''''' (because this is to change the master password to edit ''this'' server profile; when this remains empty, the "master master password" for LAM remains in effect) ** Reenter password: (make this the same as the new password, i.e. empty) Now click OK, and your LAM should be ready to go. When you first log into the LAM profile you've just created, LAM will ask you if it should create the four OU's you've designated for people/groups/machines/domains. This is a nice test: if LAM cannot create those OU's, then you've misconfigured it (or the LDAP tree itself). If it can, then you'll be able to click ''tree view'' and browse the LDAP tree. At least the administrator (e.g. cn=admin) and the four OU's (e.g. domains/groups/hosts/people) should be present under the root (e.g. dc=saruman,dc=biz).<br> Incidentally, the configuration you've just entered into LAM as profile "sarumanbiz" can also be found at ''/usr/share/ldap-account-manager/config/sarumanbiz.conf'', so if need be, you can edit the profile by hand. ==Securing LAM communications with SSL== Until just now, all communications with LAM have taken place over unencrypted connections - not a nice way to work in a production environment. We really need to use SSL to secure the LAM environment. Fortunately, that is as easy as enabling SSL on the underlying Apache2 webserver. ==Where to go from here== This completes the setup of the LDAP server. To fill it with relevant data, go to [[Filling an OpenLDAP database | the next section]]. b0ae41115c7cd5a3f075c243550f864c8ab5ea91 1707 1705 2008-09-28T16:46:51Z Saruman! 2 /* Where to go from here */ shell access link toegevoegd wikitext text/x-wiki == OpenLDAP installation and configuration== Note: we're going to install OpenLDAP on our server as [http://www.openldap.org/doc/admin24/config.html#Local%20Directory%20Service the local directory service], without replication, referrals or other advanced features. Installing OpenLDAP on your Debian server is ridiculously simple. Just make sure your server is up-to-date (''sudo apt-get update'' followed by ''sudo apt-get upgrade''), and then install the two main components for your OpenLDAP server: sudo apt-get install slapd ldap-utils The Debian configuration script will ask you for only one single thing: an administrator password. As always: generate a strong password! When you've provided the password, the LDAP database is created with the administrator name "admin" and as a base directory path, something based on your DNS name. Suppose your internal domain is "amber.lan.", then the script will generate ''suffix "dc=amber,dc=lan,dc="''. The last, empty, domain component (''dc'') is caused by the trailing dot in your DNS name: the DNS root. Since this might not always be the most convenient configuration, we recommend that you run the configuration again using ''dpkg-reconfigure slapd''. Interestingly enough, this reconfiguration asks you many ''more'' questions. The answers could look like this: omit OpenLDAP config: no DNS domain name: saruman.biz Organization name: Saruman Administrator passwd: wEt3udes Database backend: HDB DB remove after purge: no Move old DB: yes Allow LDAPv2: no As you can see, the reconfiguration yields much more configuration options than plain installation - although really you'll probably answer most questions with their default values anyway, with the exception of the database backend, which by default is BDB.<br> Anyway, the above method of configuring yields you an LDAP database with only two objects in it: * a single Organization (o="Saruman") with Distinguished Name dn="dc=saruman,dc=biz" * a single administrator with Common Name cn="admin", and dn="cn=admin,dc=saruman,dc=biz" The database that your OpenLDAP server uses is a standard Berkeley DB (BDB) database. Now we most likely will require some other databases as well in our server setup, something modern like PostgreSQL or MySQL - so why don't we configure our OpenLDAP to use this same database as well? For the answer, see [http://www.openldap.org/doc/admin24/intro.html#LDAP%20vs%20RDBMS here] - in short, the LDAP tree structure does not lend itself very well to inclusion in a modern relational database. Thus, we advise to stick with the Berkeley database provided with OpenLDAP.<br> Now, for the database backend, we have the choice between two almost identical flavours: the ''bdb'' backend is the recommended primary backend for a normal slapd database. It uses the Oracle Berkeley DB package, referred to as ''BDB'', to store data. It makes extensive use of indexing and caching to speed data access. ''hdb'' is a variant of the ''bdb'' backend that uses a hierarchical database layout which supports subtree renames. It is otherwise identical to the ''bdb'' behavior, and all the same configuration options apply. To finetune the OpenLDAP configuration, we make some changes to the main configuration file for the OpenLDAP server, ''/etc/ldap/slapd.conf'': We find the line beginning with "loglevel" and change it from ''none'' to ''256''. This value means connections/operations/results wil be logged to the ''syslogd'' daemon. There, it will be logged to the ''LOG_LOCAL4'' facility. The default hash algorithm for encrypting user passwords is {SSHA}, which is the SHA-1 algorithm (FIPS160-1) wit a seed number. However, OpenLDAP can understand more hashes, even multiple at the same time. To specify which hash or hashes, we can specify something like password-hash {SSHA} {MD5} Valid hashes are {SHA}, {SSHA} (the default, {MD5}, {SMD5}, {CRYPT} and {CLEARTEXT}. We usually don't need to change the default, but if you do, put in the directive and restart your LDAP server. More information: "man 5 slapd.conf". We find the line beginning with ''index'', and add a second line to it. This will make the section look like this: index objectClass eq index uid eq The purpose of this change is to make the OpenLDAP server create another index, on LDAP attribute ''uid''. This is important, because under some circumstances you might not receive any result on a valid query unless the searched entries are indexed. This entry makes sure all objects with a ''uid'' attribute are indexed, and thus can be found when queried. Finally, we check to be certain all necessary schema's are included: in the beginning of the file we should see include /etc/ldap/schema/core.schema include /etc/ldap/schema/cosine.schema include /etc/ldap/schema/nis.schema include /etc/ldap/schema/inetorgperson.schema If any line got missing, we need to (re)enter it in order to be able to create the LDAP entries that we want. After these little refinements, we must stop, reindex, and restart the OpenLDAP server. This can be done with the following sequence of commands: sudo invoke-rc.d slapd stop sudo -u openldap slapindex sudo invoke-rc.d slapd start Note: you need to have your ''sudo'' configured to allow you to ''su'' to user ''openldap'' in order to run the second command. ==Installing and configuring an LDAP Account Manager== It's perfectly normal to manipulate your LDAP from the command line using LDAP utilities like ''ldapsearch'', ''ldapadd'', ''ldapdelete'' and ''ldapmodify'', as well as ''slapcat'', ''slappasswd'' etcetera. However, many people find a GUI for LDAP indispensible. If you are amongst those, then for you, my friend, the question becomes: which graphic tool do you want to use? Many people speak highly of ''[http://gq-project.org/ gq]'', ''[http://luma.sourceforge.net/about.html luma]'' and ''[http://phpldapadmin.sourceforge.net/ phpldapadmin]''. We go for ''lam'' ([http://lam.sourceforge.net/index.htm LDAP acount Manager]).<br> To install ''lam'', first ensure that you have installed Apache2 and PHP5. Then we can use ''apt-get install ldap-account-manager''. After installation, we can right away surf to http://<server-IP>/lam, where we can log in. However, note that in the upper right, there's a link ''LAM configuration''. We'll go there first. Under the LAM configuration page, there are two links to areas, where settings can be specified. The first one is "Edit general settings", and clicking it prompts you for a master password - by default this is "lam". Behind that password is a simple settings page, that can be filled with values like this ('''bold''' values deviate from the default): * Security settings ** Session timeout: '''15''' (the amount of minutes of inactivity that's allowed before a user is logged off) ** Allowed hosts: '''192.168.67.*''' (the range of IP numbers from which LAM accepts connections; empty would mean "all" so we recommend limiting the scope to your internal network, or even less if possible. Multiple hosts or network ranges can be inserted below each other) * Password policy (in this section you can specify lower limits on your LDAP passwords - tho currently it's not clear to us what you're limiting. We suspect it's the creation of all LDAP passwords from within LAM). ** Minimum password length: '''6''' ** Minimum lowercase characters: 0 ** Minimum uppercase characters: 0 ** Minimum numeric characters: 0 ** Minimum symbolic characters: 0 ** Minimum character classes: '''3''' (The character classes are: lowercase, uppercase, numeric and symbols) * Logging ** Log level: notice (this is the most detailed level; "warning" logs less information, "error" less still) ** Log destination: syslog (outputs all LAM messages to the syslogger; alternatively specify "no logging" or a file name & location) * Change master password ** New master password: '''*****''' (this is the password that'll replace "lam" to log into the LAM configuration; it is NOT the password of your rootdn, and if anywhere possible, you should avoid using that particular password here - for safety. Generate [http://www.pctools.com/guides/password/ yet another strong password].) ** Reenter new master password: '''*****''' After entering the above settings, we at least know LAM is operational, and coarsely secured (it's not using SSL yet). Click ''OK'' to save, or ''back to login'' if you change your mind and just want to go back. The second link from the LAM configuration page, "Edit server profiles" will again prompt you. However, this password prompt page contains an extra pulldown option, currently filled with the word "lam". This is because there is only one server profile, named "lam", and filled with some default values for your LDAP server. And under those two boxes, there's a link "manage server profiles".<br> Now first we'll rename that profile to something more descriptive. Click the "manage server profiles" link, in the "profile management page" check the radio button next to ''&#091;lam&#093; Rename profile'', put in the new name (e.g. "sarumanbiz"), fill in the shiny new master LAM password &#8212; it should no longer be the default "lam" since you've changed it, in line with the paragraph above :-) &#8212; and then click OK. Presto! The server profile is renamed.<br> When you now enter your password to edit the server preferences for profile "sarumanbiz", you get to a page with a lot of settings; the only ones we're currently interested in are: * Server settings ** Server address: ldap://localhost:389 (verify that it's either localhost, if both the LDAP server and your LAM Apache2 are on the same machine, or a correct IP address or DNS name if that's not the case) ** Tree Suffix: '''dc=saruman,dc=biz''' (the same suffix you've installed your LDAP server with) * Account types ** Edit Account types *** Users **** LDAP Suffix: '''ou=people,dc=saruman,dc=biz''' (You'll have to designate an OU in which to store user accounts; it does not have to exist yet (LAM can create it for you any time you log in) but the base has to be accessible; in our example: saruman.biz. Any name will do, but since we're storing identities, and not specifically users, we're calling the OU "people") *** Groups **** LDAP Suffix: '''ou=groups,dc=saruman,dc=biz''' (This is the OU where groups will be stored) *** Hosts **** LDAP Suffix: '''ou=hosts,dc=saruman,dc=biz''' (This is where machines, i.e. hosts, will be stored) *** Samba domains **** LDAP Suffix: '''ou=domains,dc=saruman,dc=biz''' (This is where all Windows workgroups/domains will wind up) * Security settings ** List of valid users: '''cn=admin,dc=saruman,dc=biz''' (or whatever you've designated your root DN) ** New password: '''''leave empty''''' (because this is to change the master password to edit ''this'' server profile; when this remains empty, the "master master password" for LAM remains in effect) ** Reenter password: (make this the same as the new password, i.e. empty) Now click OK, and your LAM should be ready to go. When you first log into the LAM profile you've just created, LAM will ask you if it should create the four OU's you've designated for people/groups/machines/domains. This is a nice test: if LAM cannot create those OU's, then you've misconfigured it (or the LDAP tree itself). If it can, then you'll be able to click ''tree view'' and browse the LDAP tree. At least the administrator (e.g. cn=admin) and the four OU's (e.g. domains/groups/hosts/people) should be present under the root (e.g. dc=saruman,dc=biz).<br> Incidentally, the configuration you've just entered into LAM as profile "sarumanbiz" can also be found at ''/usr/share/ldap-account-manager/config/sarumanbiz.conf'', so if need be, you can edit the profile by hand. ==Securing LAM communications with SSL== Until just now, all communications with LAM have taken place over unencrypted connections - not a nice way to work in a production environment. We really need to use SSL to secure the LAM environment. Fortunately, that is as easy as enabling SSL on the underlying Apache2 webserver. ==Where to go from here== This completes the setup of the LDAP server. * To fill it with relevant data, go to [[Filling an OpenLDAP database | the next section]]. * To set your system to accept LDAP users logging in to the machine, [[Accessing_a_shell_with_LDAP_authentication | go here]]. 008ed6015f2b0a6e73bbe887b38b6db0785fe351 1714 1707 2008-09-28T18:38:09Z Saruman! 2 /* OpenLDAP installation and configuration */ added slapd.conf permissions wikitext text/x-wiki == OpenLDAP installation and configuration== Note: we're going to install OpenLDAP on our server as [http://www.openldap.org/doc/admin24/config.html#Local%20Directory%20Service the local directory service], without replication, referrals or other advanced features. Installing OpenLDAP on your Debian server is ridiculously simple. Just make sure your server is up-to-date (''sudo apt-get update'' followed by ''sudo apt-get upgrade''), and then install the two main components for your OpenLDAP server: sudo apt-get install slapd ldap-utils The Debian configuration script will ask you for only one single thing: an administrator password. As always: generate a strong password! When you've provided the password, the LDAP database is created with the administrator name "admin" and as a base directory path, something based on your DNS name. Suppose your internal domain is "amber.lan.", then the script will generate ''suffix "dc=amber,dc=lan,dc="''. The last, empty, domain component (''dc'') is caused by the trailing dot in your DNS name: the DNS root. Since this might not always be the most convenient configuration, we recommend that you run the configuration again using ''dpkg-reconfigure slapd''. Interestingly enough, this reconfiguration asks you many ''more'' questions. The answers could look like this: omit OpenLDAP config: no DNS domain name: saruman.biz Organization name: Saruman Administrator passwd: wEt3udes Database backend: HDB DB remove after purge: no Move old DB: yes Allow LDAPv2: no As you can see, the reconfiguration yields much more configuration options than plain installation - although really you'll probably answer most questions with their default values anyway, with the exception of the database backend, which by default is BDB.<br> Anyway, the above method of configuring yields you an LDAP database with only two objects in it: * a single Organization (o="Saruman") with Distinguished Name dn="dc=saruman,dc=biz" * a single administrator with Common Name cn="admin", and dn="cn=admin,dc=saruman,dc=biz" The database that your OpenLDAP server uses is a standard Berkeley DB (BDB) database. Now we most likely will require some other databases as well in our server setup, something modern like PostgreSQL or MySQL - so why don't we configure our OpenLDAP to use this same database as well? For the answer, see [http://www.openldap.org/doc/admin24/intro.html#LDAP%20vs%20RDBMS here] - in short, the LDAP tree structure does not lend itself very well to inclusion in a modern relational database. Thus, we advise to stick with the Berkeley database provided with OpenLDAP.<br> Now, for the database backend, we have the choice between two almost identical flavours: the ''bdb'' backend is the recommended primary backend for a normal slapd database. It uses the Oracle Berkeley DB package, referred to as ''BDB'', to store data. It makes extensive use of indexing and caching to speed data access. ''hdb'' is a variant of the ''bdb'' backend that uses a hierarchical database layout which supports subtree renames. It is otherwise identical to the ''bdb'' behavior, and all the same configuration options apply. To finetune the OpenLDAP configuration, we make some changes to the main configuration file for the OpenLDAP server, ''/etc/ldap/slapd.conf''. Note: make SURE that the permissions on this file are rw-r----- (640) and the owner is root:openldap. We find the line beginning with "loglevel" and change it from ''none'' to ''256''. This value means connections/operations/results wil be logged to the ''syslogd'' daemon. There, it will be logged to the ''LOG_LOCAL4'' facility. The default hash algorithm for encrypting user passwords is {SSHA}, which is the SHA-1 algorithm (FIPS160-1) wit a seed number. However, OpenLDAP can understand more hashes, even multiple at the same time. To specify which hash or hashes, we can specify something like password-hash {SSHA} {MD5} Valid hashes are {SHA}, {SSHA} (the default, {MD5}, {SMD5}, {CRYPT} and {CLEARTEXT}. We usually don't need to change the default, but if you do, put in the directive and restart your LDAP server. More information: "man 5 slapd.conf". We find the line beginning with ''index'', and add a second line to it. This will make the section look like this: index objectClass eq index uid eq The purpose of this change is to make the OpenLDAP server create another index, on LDAP attribute ''uid''. This is important, because under some circumstances you might not receive any result on a valid query unless the searched entries are indexed. This entry makes sure all objects with a ''uid'' attribute are indexed, and thus can be found when queried. Finally, we check to be certain all necessary schema's are included: in the beginning of the file we should see include /etc/ldap/schema/core.schema include /etc/ldap/schema/cosine.schema include /etc/ldap/schema/nis.schema include /etc/ldap/schema/inetorgperson.schema If any line got missing, we need to (re)enter it in order to be able to create the LDAP entries that we want. After these little refinements, we must stop, reindex, and restart the OpenLDAP server. This can be done with the following sequence of commands: sudo invoke-rc.d slapd stop sudo -u openldap slapindex sudo invoke-rc.d slapd start Note: you need to have your ''sudo'' configured to allow you to ''su'' to user ''openldap'' in order to run the second command. ==Installing and configuring an LDAP Account Manager== It's perfectly normal to manipulate your LDAP from the command line using LDAP utilities like ''ldapsearch'', ''ldapadd'', ''ldapdelete'' and ''ldapmodify'', as well as ''slapcat'', ''slappasswd'' etcetera. However, many people find a GUI for LDAP indispensible. If you are amongst those, then for you, my friend, the question becomes: which graphic tool do you want to use? Many people speak highly of ''[http://gq-project.org/ gq]'', ''[http://luma.sourceforge.net/about.html luma]'' and ''[http://phpldapadmin.sourceforge.net/ phpldapadmin]''. We go for ''lam'' ([http://lam.sourceforge.net/index.htm LDAP acount Manager]).<br> To install ''lam'', first ensure that you have installed Apache2 and PHP5. Then we can use ''apt-get install ldap-account-manager''. After installation, we can right away surf to http://<server-IP>/lam, where we can log in. However, note that in the upper right, there's a link ''LAM configuration''. We'll go there first. Under the LAM configuration page, there are two links to areas, where settings can be specified. The first one is "Edit general settings", and clicking it prompts you for a master password - by default this is "lam". Behind that password is a simple settings page, that can be filled with values like this ('''bold''' values deviate from the default): * Security settings ** Session timeout: '''15''' (the amount of minutes of inactivity that's allowed before a user is logged off) ** Allowed hosts: '''192.168.67.*''' (the range of IP numbers from which LAM accepts connections; empty would mean "all" so we recommend limiting the scope to your internal network, or even less if possible. Multiple hosts or network ranges can be inserted below each other) * Password policy (in this section you can specify lower limits on your LDAP passwords - tho currently it's not clear to us what you're limiting. We suspect it's the creation of all LDAP passwords from within LAM). ** Minimum password length: '''6''' ** Minimum lowercase characters: 0 ** Minimum uppercase characters: 0 ** Minimum numeric characters: 0 ** Minimum symbolic characters: 0 ** Minimum character classes: '''3''' (The character classes are: lowercase, uppercase, numeric and symbols) * Logging ** Log level: notice (this is the most detailed level; "warning" logs less information, "error" less still) ** Log destination: syslog (outputs all LAM messages to the syslogger; alternatively specify "no logging" or a file name & location) * Change master password ** New master password: '''*****''' (this is the password that'll replace "lam" to log into the LAM configuration; it is NOT the password of your rootdn, and if anywhere possible, you should avoid using that particular password here - for safety. Generate [http://www.pctools.com/guides/password/ yet another strong password].) ** Reenter new master password: '''*****''' After entering the above settings, we at least know LAM is operational, and coarsely secured (it's not using SSL yet). Click ''OK'' to save, or ''back to login'' if you change your mind and just want to go back. The second link from the LAM configuration page, "Edit server profiles" will again prompt you. However, this password prompt page contains an extra pulldown option, currently filled with the word "lam". This is because there is only one server profile, named "lam", and filled with some default values for your LDAP server. And under those two boxes, there's a link "manage server profiles".<br> Now first we'll rename that profile to something more descriptive. Click the "manage server profiles" link, in the "profile management page" check the radio button next to ''&#091;lam&#093; Rename profile'', put in the new name (e.g. "sarumanbiz"), fill in the shiny new master LAM password &#8212; it should no longer be the default "lam" since you've changed it, in line with the paragraph above :-) &#8212; and then click OK. Presto! The server profile is renamed.<br> When you now enter your password to edit the server preferences for profile "sarumanbiz", you get to a page with a lot of settings; the only ones we're currently interested in are: * Server settings ** Server address: ldap://localhost:389 (verify that it's either localhost, if both the LDAP server and your LAM Apache2 are on the same machine, or a correct IP address or DNS name if that's not the case) ** Tree Suffix: '''dc=saruman,dc=biz''' (the same suffix you've installed your LDAP server with) * Account types ** Edit Account types *** Users **** LDAP Suffix: '''ou=people,dc=saruman,dc=biz''' (You'll have to designate an OU in which to store user accounts; it does not have to exist yet (LAM can create it for you any time you log in) but the base has to be accessible; in our example: saruman.biz. Any name will do, but since we're storing identities, and not specifically users, we're calling the OU "people") *** Groups **** LDAP Suffix: '''ou=groups,dc=saruman,dc=biz''' (This is the OU where groups will be stored) *** Hosts **** LDAP Suffix: '''ou=hosts,dc=saruman,dc=biz''' (This is where machines, i.e. hosts, will be stored) *** Samba domains **** LDAP Suffix: '''ou=domains,dc=saruman,dc=biz''' (This is where all Windows workgroups/domains will wind up) * Security settings ** List of valid users: '''cn=admin,dc=saruman,dc=biz''' (or whatever you've designated your root DN) ** New password: '''''leave empty''''' (because this is to change the master password to edit ''this'' server profile; when this remains empty, the "master master password" for LAM remains in effect) ** Reenter password: (make this the same as the new password, i.e. empty) Now click OK, and your LAM should be ready to go. When you first log into the LAM profile you've just created, LAM will ask you if it should create the four OU's you've designated for people/groups/machines/domains. This is a nice test: if LAM cannot create those OU's, then you've misconfigured it (or the LDAP tree itself). If it can, then you'll be able to click ''tree view'' and browse the LDAP tree. At least the administrator (e.g. cn=admin) and the four OU's (e.g. domains/groups/hosts/people) should be present under the root (e.g. dc=saruman,dc=biz).<br> Incidentally, the configuration you've just entered into LAM as profile "sarumanbiz" can also be found at ''/usr/share/ldap-account-manager/config/sarumanbiz.conf'', so if need be, you can edit the profile by hand. ==Securing LAM communications with SSL== Until just now, all communications with LAM have taken place over unencrypted connections - not a nice way to work in a production environment. We really need to use SSL to secure the LAM environment. Fortunately, that is as easy as enabling SSL on the underlying Apache2 webserver. ==Where to go from here== This completes the setup of the LDAP server. * To fill it with relevant data, go to [[Filling an OpenLDAP database | the next section]]. * To set your system to accept LDAP users logging in to the machine, [[Accessing_a_shell_with_LDAP_authentication | go here]]. bd0003e16ece2364d3ee41eb8e25ab10061c9117 0 1472 1695 1689 2008-09-27T14:15:58Z Saruman! 2 /* Adding a user with an LDIF file */ described ldapadd wikitext text/x-wiki == Creating your first Organizational Units == On the offchance that you haven't installed LAM, and thus haven't created the organizational units ''people'', ''groups'', ''hosts'' and ''domains'', here's how to create them manually. Create a file containing the following information: <pre> dn: ou=people,dc=saruman,dc=biz ou: people objectClass: top objectClass: organizationalUnit structuralObjectClass: organizationalUnit dn: ou=groups,dc=saruman,dc=biz ou: groups objectClass: top objectClass: organizationalUnit structuralObjectClass: organizationalUnit dn: ou=hosts,dc=saruman,dc=biz ou: hosts objectClass: top objectClass: organizationalUnit structuralObjectClass: organizationalUnit dn: ou=domains,dc=saruman,dc=biz ou: domains objectClass: top objectClass: organizationalUnit structuralObjectClass: organizationalUnit </pre> Let's suppose this file is named ''orgunits.ldif''. Now from the directory that contains this file, feed the information into your OpenLDAP using the following commands: sudo invoke-rc.d slapd stop sudo slapadd -c -v -l orgunits.ldif sudo invoke-rc.d slapd start This effectively stops the server, writes the information directly into the database, and then starts the server again. Another way to do (almost) the ''same'' thing, would be to add the information with the ''ldapadd'' command: ldapadd -c -x -D cn=admin,dc=saruman,dc=biz -W -f orgunits.ldif This binds to the OpenLDAP server (which must be running) using the admin account. This in turn causes the command to request the admin password, and then feed the contents from the ''orgunits.ldif'' file into the database. However, adding data to a live database precludes you from adding system controlled attributes, as structuralObjectClass is. So for live addition, remove those four particular lines from the ''orgunits.ldif'' file. Explanation of this difference: ''slapadd'' is meant as a restore tool, so it must (and can) create system controlled attributes. ''ldapadd'' is a modification tool, so it shouldn't need to (and can't) create these attributes. ==Migrating User, Password and Group entries to an LDAP server== It's nice to have an LDAP, but it's ''much'' nicer if it is filled with information. We'll try to enter all existing users and groups from the host server into LDAP, using [[Migrating existing Unix users to OpenLDAP | the available migration tools]]. ==Creating new users == If we need new users (e.g. when the server you're setting up is spankin' new) then we can create them in several ways. Let's discuss two of them: === Adding a user with an LDIF file=== To add a user with the LDAP command line utilities, we first need to create an LDIF file. This file is a simple text file, created with a text editor like ''[[vim | vi]]''. The file could look something like the text below. In that file, we create a posix group "networkusers", and a user "sixpacjo" that's a member of this posix group. However, first we need to [http://www.pctools.com/guides/password/ generate a password] for our user, e.g. "raQaMad3", then hash it: slappasswd -u -h {SSHA} -s raQaMad3 {SSHA}OcAQWgcTCzpu6v8n4yUUthiKPM6rlODq Now with this hashed password, and all other information on user sixpacjo and group networkusers, we can create the actual LDIF file # Create the user group dn: cn=networkusers,ou=groups,dc=saruman,dc=biz objectClass: posixGroup gidNumber: 10001 cn: TestGroup description: Internal network users # Create a new user: dn: uid=sixpacjo,ou=people,dc=saruman,dc=biz objectClass: top objectClass: posixAccount objectClass: shadowAccount objectClass: inetOrgPerson cn: Joe Sixpack description: Your Average Network User givenName: Joe sn: Sixpack mail: joe.sixpack@saruman.biz mail: j.sixpack@saruman.biz # The Unix login-name for the user: uid: sixpacjo # The group and user IDs: gidNumber: 10001 uidNumber: 10001 # The Unix account data: homeDirectory: /home/sixpacjo loginShell: /bin/bash # The encrypted password for the user: userPassword: {SSHA}OcAQWgcTCzpu6v8n4yUUthiKPM6rlODq For a line-by-line explanation of this LDIF file, go [[LDIF syntax explanation | here]]; we also explain the [[LDIF syntax explanation | password hashing]] there. If you need to create more users, you can put them all in the same LDIF file, as long as you leave empty lines between each user. To put the information from this file into our LDAP server, we have two options: # Shut down the OpenLDAP server, put the information straight into the database using ''slapadd'', and then starting the server again. This would be the recommended way to enter information if we hadn't just typed it in ourselves, but previously made a backup of some sorts from the LDAP server using ''slapcat''. # Keep the OpenLDAP running, and use the ''ldapadd'' utility to read the data into the live LDAP database. This makes use of the credentials of some user that has the right to write in the database, at least at the places where your LDIF file wants to store information (in the above example: in the ''groups'' and ''people'' OU's). The ''ldapadd'' method works like this: after creating the file, e.g. ''sixpack.ldif'' in a certain place, e.g. our home directory, we run the following command: ldapadd -v -x -D cn=admin.dc=saruman.dc=biz -W -f ~/sixpack.ldif The meaning of the options is as follows: * '''-v''' the everamusing "verbose" for extra diagnostic messages. * '''-x''' use "simple bind" and not a TLS-encrypted connection. * '''-D cn=admin.dc=saruman.dc=biz''' is the Distinguished Name with which to bind to the LDAP server. * '''-W''' prompt for the password of the -D credential. Alternatively, use ''-w <password>'', but ofcourse then the password winds up in your Bash history file et cetera. * '''-f ~/sixpack.ldif''' read the LDIF information from this particular file, instead of the StdIn === Adding a user with LAM=== e6800a2c1a07dff70964153b71477378eba55de9 1696 1695 2008-09-27T15:03:03Z Saruman! 2 /* Adding a user with an LDIF file */ added output wikitext text/x-wiki == Creating your first Organizational Units == On the offchance that you haven't installed LAM, and thus haven't created the organizational units ''people'', ''groups'', ''hosts'' and ''domains'', here's how to create them manually. Create a file containing the following information: <pre> dn: ou=people,dc=saruman,dc=biz ou: people objectClass: top objectClass: organizationalUnit structuralObjectClass: organizationalUnit dn: ou=groups,dc=saruman,dc=biz ou: groups objectClass: top objectClass: organizationalUnit structuralObjectClass: organizationalUnit dn: ou=hosts,dc=saruman,dc=biz ou: hosts objectClass: top objectClass: organizationalUnit structuralObjectClass: organizationalUnit dn: ou=domains,dc=saruman,dc=biz ou: domains objectClass: top objectClass: organizationalUnit structuralObjectClass: organizationalUnit </pre> Let's suppose this file is named ''orgunits.ldif''. Now from the directory that contains this file, feed the information into your OpenLDAP using the following commands: sudo invoke-rc.d slapd stop sudo slapadd -c -v -l orgunits.ldif sudo invoke-rc.d slapd start This effectively stops the server, writes the information directly into the database, and then starts the server again. Another way to do (almost) the ''same'' thing, would be to add the information with the ''ldapadd'' command: ldapadd -c -x -D cn=admin,dc=saruman,dc=biz -W -f orgunits.ldif This binds to the OpenLDAP server (which must be running) using the admin account. This in turn causes the command to request the admin password, and then feed the contents from the ''orgunits.ldif'' file into the database. However, adding data to a live database precludes you from adding system controlled attributes, as structuralObjectClass is. So for live addition, remove those four particular lines from the ''orgunits.ldif'' file. Explanation of this difference: ''slapadd'' is meant as a restore tool, so it must (and can) create system controlled attributes. ''ldapadd'' is a modification tool, so it shouldn't need to (and can't) create these attributes. ==Migrating User, Password and Group entries to an LDAP server== It's nice to have an LDAP, but it's ''much'' nicer if it is filled with information. We'll try to enter all existing users and groups from the host server into LDAP, using [[Migrating existing Unix users to OpenLDAP | the available migration tools]]. ==Creating new users == If we need new users (e.g. when the server you're setting up is spankin' new) then we can create them in several ways. Let's discuss two of them: === Adding a user with an LDIF file=== To add a user with the LDAP command line utilities, we first need to create an LDIF file. This file is a simple text file, created with a text editor like ''[[vim | vi]]''. The file could look something like the text below. In that file, we create a posix group "networkusers", and a user "sixpacjo" that's a member of this posix group. However, first we need to [http://www.pctools.com/guides/password/ generate a password] for our user, e.g. "raQaMad3", then hash it: slappasswd -u -h {SSHA} -s raQaMad3 {SSHA}OcAQWgcTCzpu6v8n4yUUthiKPM6rlODq Now with this hashed password, and all other information on user sixpacjo and group networkusers, we can create the actual LDIF file # Create the user group dn: cn=networkusers,ou=groups,dc=saruman,dc=biz objectClass: posixGroup gidNumber: 10001 cn: networkusers description: Internal network users # Create a new user: dn: uid=sixpacjo,ou=people,dc=saruman,dc=biz objectClass: top objectClass: posixAccount objectClass: shadowAccount objectClass: inetOrgPerson cn: Joe Sixpack description: Your Average Network User givenName: Joe sn: Sixpack mail: joe.sixpack@saruman.biz mail: j.sixpack@saruman.biz # The Unix login-name for the user: uid: sixpacjo # The group and user IDs: gidNumber: 10001 uidNumber: 10001 # The Unix account data: homeDirectory: /home/sixpacjo loginShell: /bin/bash # The encrypted password for the user: userPassword: {SSHA}OcAQWgcTCzpu6v8n4yUUthiKPM6rlODq For a line-by-line explanation of this LDIF file, go [[LDIF syntax explanation | here]]; we also explain the [[LDIF syntax explanation | password hashing]] there. If you need to create more users, you can put them all in the same LDIF file, as long as you leave empty lines between each user. To put the information from this file into our LDAP server, we have two options: # Shut down the OpenLDAP server, put the information straight into the database using ''slapadd'', and then starting the server again. This would be the recommended way to enter information if we hadn't just typed it in ourselves, but previously made a backup of some sorts from the LDAP server using ''slapcat''. # Keep the OpenLDAP running, and use the ''ldapadd'' utility to read the data into the live LDAP database. This makes use of the credentials of some user that has the right to write in the database, at least at the places where your LDIF file wants to store information (in the above example: in the ''groups'' and ''people'' OU's). The ''ldapadd'' method works like this: after creating the file, e.g. ''sixpack.ldif'' in a certain place, e.g. our home directory, we run the following command: ldapadd -v -x -D cn=admin.dc=saruman.dc=biz -W -f ~/sixpack.ldif The meaning of the options is as follows: * '''-v''' the everamusing "verbose" for extra diagnostic messages. * '''-x''' use "simple bind" and not a TLS-encrypted connection. * '''-D cn=admin.dc=saruman.dc=biz''' is the Distinguished Name with which to bind to the LDAP server. * '''-W''' prompt for the password of the -D credential. Alternatively, use ''-w <password>'', but ofcourse then the password winds up in your Bash history file et cetera. * '''-f ~/sixpack.ldif''' read the LDIF information from this particular file, instead of the StdIn The output of such an action could look like this: <pre> ldapadd -v -x -D cn=admin,dc=saruman,dc=biz -W -f sixpack.ldif ldap_initialize( <DEFAULT> ) Enter LDAP Password: add objectClass: posixGroup add gidNumber: 10001 add cn: networkusers add description: Internal network users adding new entry "cn=networkusers,ou=groups,dc=saruman,dc=biz" modify complete add objectClass: posixAccount shadowAccount inetOrgPerson add cn: Joe Sixpack add description: Your Average Network User .... (et cetera et cetera) .... adding new entry "uid=sixpacjo,ou=people,dc=saruman,dc=biz" modify complete </pre> There, wasn't that fun? We now have Joe Sixpack in our LDAP server with all data necessary for a valid account - even though he as yet can't do anything yet on our server! To === Adding a user with LAM=== 33838cda9c8f05a60d98208205908e144fa64586 1697 1696 2008-09-27T15:13:36Z Saruman! 2 /* Adding a user with LAM */ first text wikitext text/x-wiki == Creating your first Organizational Units == On the offchance that you haven't installed LAM, and thus haven't created the organizational units ''people'', ''groups'', ''hosts'' and ''domains'', here's how to create them manually. Create a file containing the following information: <pre> dn: ou=people,dc=saruman,dc=biz ou: people objectClass: top objectClass: organizationalUnit structuralObjectClass: organizationalUnit dn: ou=groups,dc=saruman,dc=biz ou: groups objectClass: top objectClass: organizationalUnit structuralObjectClass: organizationalUnit dn: ou=hosts,dc=saruman,dc=biz ou: hosts objectClass: top objectClass: organizationalUnit structuralObjectClass: organizationalUnit dn: ou=domains,dc=saruman,dc=biz ou: domains objectClass: top objectClass: organizationalUnit structuralObjectClass: organizationalUnit </pre> Let's suppose this file is named ''orgunits.ldif''. Now from the directory that contains this file, feed the information into your OpenLDAP using the following commands: sudo invoke-rc.d slapd stop sudo slapadd -c -v -l orgunits.ldif sudo invoke-rc.d slapd start This effectively stops the server, writes the information directly into the database, and then starts the server again. Another way to do (almost) the ''same'' thing, would be to add the information with the ''ldapadd'' command: ldapadd -c -x -D cn=admin,dc=saruman,dc=biz -W -f orgunits.ldif This binds to the OpenLDAP server (which must be running) using the admin account. This in turn causes the command to request the admin password, and then feed the contents from the ''orgunits.ldif'' file into the database. However, adding data to a live database precludes you from adding system controlled attributes, as structuralObjectClass is. So for live addition, remove those four particular lines from the ''orgunits.ldif'' file. Explanation of this difference: ''slapadd'' is meant as a restore tool, so it must (and can) create system controlled attributes. ''ldapadd'' is a modification tool, so it shouldn't need to (and can't) create these attributes. ==Migrating User, Password and Group entries to an LDAP server== It's nice to have an LDAP, but it's ''much'' nicer if it is filled with information. We'll try to enter all existing users and groups from the host server into LDAP, using [[Migrating existing Unix users to OpenLDAP | the available migration tools]]. ==Creating new users == If we need new users (e.g. when the server you're setting up is spankin' new) then we can create them in several ways. Let's discuss two of them: === Adding a user with an LDIF file=== To add a user with the LDAP command line utilities, we first need to create an LDIF file. This file is a simple text file, created with a text editor like ''[[vim | vi]]''. The file could look something like the text below. In that file, we create a posix group "networkusers", and a user "sixpacjo" that's a member of this posix group. However, first we need to [http://www.pctools.com/guides/password/ generate a password] for our user, e.g. "raQaMad3", then hash it: slappasswd -u -h {SSHA} -s raQaMad3 {SSHA}OcAQWgcTCzpu6v8n4yUUthiKPM6rlODq Now with this hashed password, and all other information on user sixpacjo and group networkusers, we can create the actual LDIF file # Create the user group dn: cn=networkusers,ou=groups,dc=saruman,dc=biz objectClass: posixGroup gidNumber: 10001 cn: networkusers description: Internal network users # Create a new user: dn: uid=sixpacjo,ou=people,dc=saruman,dc=biz objectClass: top objectClass: posixAccount objectClass: shadowAccount objectClass: inetOrgPerson cn: Joe Sixpack description: Your Average Network User givenName: Joe sn: Sixpack mail: joe.sixpack@saruman.biz mail: j.sixpack@saruman.biz # The Unix login-name for the user: uid: sixpacjo # The group and user IDs: gidNumber: 10001 uidNumber: 10001 # The Unix account data: homeDirectory: /home/sixpacjo loginShell: /bin/bash # The encrypted password for the user: userPassword: {SSHA}OcAQWgcTCzpu6v8n4yUUthiKPM6rlODq For a line-by-line explanation of this LDIF file, go [[LDIF syntax explanation | here]]; we also explain the [[LDIF syntax explanation | password hashing]] there. If you need to create more users, you can put them all in the same LDIF file, as long as you leave empty lines between each user. To put the information from this file into our LDAP server, we have two options: # Shut down the OpenLDAP server, put the information straight into the database using ''slapadd'', and then starting the server again. This would be the recommended way to enter information if we hadn't just typed it in ourselves, but previously made a backup of some sorts from the LDAP server using ''slapcat''. # Keep the OpenLDAP running, and use the ''ldapadd'' utility to read the data into the live LDAP database. This makes use of the credentials of some user that has the right to write in the database, at least at the places where your LDIF file wants to store information (in the above example: in the ''groups'' and ''people'' OU's). The ''ldapadd'' method works like this: after creating the file, e.g. ''sixpack.ldif'' in a certain place, e.g. our home directory, we run the following command: ldapadd -v -x -D cn=admin.dc=saruman.dc=biz -W -f ~/sixpack.ldif The meaning of the options is as follows: * '''-v''' the everamusing "verbose" for extra diagnostic messages. * '''-x''' use "simple bind" and not a TLS-encrypted connection. * '''-D cn=admin.dc=saruman.dc=biz''' is the Distinguished Name with which to bind to the LDAP server. * '''-W''' prompt for the password of the -D credential. Alternatively, use ''-w <password>'', but ofcourse then the password winds up in your Bash history file et cetera. * '''-f ~/sixpack.ldif''' read the LDIF information from this particular file, instead of the StdIn The output of such an action could look like this: <pre> ldapadd -v -x -D cn=admin,dc=saruman,dc=biz -W -f sixpack.ldif ldap_initialize( <DEFAULT> ) Enter LDAP Password: add objectClass: posixGroup add gidNumber: 10001 add cn: networkusers add description: Internal network users adding new entry "cn=networkusers,ou=groups,dc=saruman,dc=biz" modify complete add objectClass: posixAccount shadowAccount inetOrgPerson add cn: Joe Sixpack add description: Your Average Network User .... (et cetera et cetera) .... adding new entry "uid=sixpacjo,ou=people,dc=saruman,dc=biz" modify complete </pre> There, wasn't that fun? We now have Joe Sixpack in our LDAP server with all data necessary for a valid account - even though he as yet can't do anything yet on our server! To === Adding a user with LAM=== To add a user with LAM is not exactly challenging. Log into LAM with an admin account; in the top menu, click Users; at the left bottom, you'll find a button "New user". Click it. You'll find yourself in a browser screen with four "tabs": Personal, Unix, Shadow, and Samba3. Incidentally, if the system complains about "No Samba3 domains found in LDAP": ignore that for now. In the first tab Personal, we find a (large) number of attributes that we can fill; the mandatory attributes are marked with an asterisk. At a minimum, fill in those required attributes. Then switch to the next tab, Unix. Here we fill in the required attributes, taking care to select a unique UID number, selecting the right primary group (that you've made beforehand, naturally, e.g. with the LDIF file mentioned previously), and setting a password. We don't need to add anything to the 3rd and 4th tab, so we can finish by clicking save at the left top hand. LAM should respond with "LDAP operation succesfull". 72712439e4f964e0f5b68aa63016b09ad84d0a27 1698 1697 2008-09-27T17:56:33Z Saruman! 2 /* The next phase: shell access */ made pointer to next page wikitext text/x-wiki == Creating your first Organizational Units == On the offchance that you haven't installed LAM, and thus haven't created the organizational units ''people'', ''groups'', ''hosts'' and ''domains'', here's how to create them manually. Create a file containing the following information: <pre> dn: ou=people,dc=saruman,dc=biz ou: people objectClass: top objectClass: organizationalUnit structuralObjectClass: organizationalUnit dn: ou=groups,dc=saruman,dc=biz ou: groups objectClass: top objectClass: organizationalUnit structuralObjectClass: organizationalUnit dn: ou=hosts,dc=saruman,dc=biz ou: hosts objectClass: top objectClass: organizationalUnit structuralObjectClass: organizationalUnit dn: ou=domains,dc=saruman,dc=biz ou: domains objectClass: top objectClass: organizationalUnit structuralObjectClass: organizationalUnit </pre> Let's suppose this file is named ''orgunits.ldif''. Now from the directory that contains this file, feed the information into your OpenLDAP using the following commands: sudo invoke-rc.d slapd stop sudo slapadd -c -v -l orgunits.ldif sudo invoke-rc.d slapd start This effectively stops the server, writes the information directly into the database, and then starts the server again. Another way to do (almost) the ''same'' thing, would be to add the information with the ''ldapadd'' command: ldapadd -c -x -D cn=admin,dc=saruman,dc=biz -W -f orgunits.ldif This binds to the OpenLDAP server (which must be running) using the admin account. This in turn causes the command to request the admin password, and then feed the contents from the ''orgunits.ldif'' file into the database. However, adding data to a live database precludes you from adding system controlled attributes, as structuralObjectClass is. So for live addition, remove those four particular lines from the ''orgunits.ldif'' file. Explanation of this difference: ''slapadd'' is meant as a restore tool, so it must (and can) create system controlled attributes. ''ldapadd'' is a modification tool, so it shouldn't need to (and can't) create these attributes. ==Migrating User, Password and Group entries to an LDAP server== It's nice to have an LDAP, but it's ''much'' nicer if it is filled with information. We'll try to enter all existing users and groups from the host server into LDAP, using [[Migrating existing Unix users to OpenLDAP | the available migration tools]]. ==Creating new users == If we need new users (e.g. when the server you're setting up is spankin' new) then we can create them in several ways. Let's discuss two of them: === Adding a user with an LDIF file=== To add a user with the LDAP command line utilities, we first need to create an LDIF file. This file is a simple text file, created with a text editor like ''[[vim | vi]]''. The file could look something like the text below. In that file, we create a posix group "networkusers", and a user "sixpacjo" that's a member of this posix group. However, first we need to [http://www.pctools.com/guides/password/ generate a password] for our user, e.g. "raQaMad3", then hash it: slappasswd -u -h {SSHA} -s raQaMad3 {SSHA}OcAQWgcTCzpu6v8n4yUUthiKPM6rlODq Now with this hashed password, and all other information on user sixpacjo and group networkusers, we can create the actual LDIF file # Create the user group dn: cn=networkusers,ou=groups,dc=saruman,dc=biz objectClass: posixGroup gidNumber: 10001 cn: networkusers description: Internal network users # Create a new user: dn: uid=sixpacjo,ou=people,dc=saruman,dc=biz objectClass: top objectClass: posixAccount objectClass: shadowAccount objectClass: inetOrgPerson cn: Joe Sixpack description: Your Average Network User givenName: Joe sn: Sixpack mail: joe.sixpack@saruman.biz mail: j.sixpack@saruman.biz # The Unix login-name for the user: uid: sixpacjo # The group and user IDs: gidNumber: 10001 uidNumber: 10001 # The Unix account data: homeDirectory: /home/sixpacjo loginShell: /bin/bash # The encrypted password for the user: userPassword: {SSHA}OcAQWgcTCzpu6v8n4yUUthiKPM6rlODq For a line-by-line explanation of this LDIF file, go [[LDIF syntax explanation | here]]; we also explain the [[LDIF syntax explanation | password hashing]] there. If you need to create more users, you can put them all in the same LDIF file, as long as you leave empty lines between each user. To put the information from this file into our LDAP server, we have two options: # Shut down the OpenLDAP server, put the information straight into the database using ''slapadd'', and then starting the server again. This would be the recommended way to enter information if we hadn't just typed it in ourselves, but previously made a backup of some sorts from the LDAP server using ''slapcat''. # Keep the OpenLDAP running, and use the ''ldapadd'' utility to read the data into the live LDAP database. This makes use of the credentials of some user that has the right to write in the database, at least at the places where your LDIF file wants to store information (in the above example: in the ''groups'' and ''people'' OU's). The ''ldapadd'' method works like this: after creating the file, e.g. ''sixpack.ldif'' in a certain place, e.g. our home directory, we run the following command: ldapadd -v -x -D cn=admin.dc=saruman.dc=biz -W -f ~/sixpack.ldif The meaning of the options is as follows: * '''-v''' the everamusing "verbose" for extra diagnostic messages. * '''-x''' use "simple bind" and not a TLS-encrypted connection. * '''-D cn=admin.dc=saruman.dc=biz''' is the Distinguished Name with which to bind to the LDAP server. * '''-W''' prompt for the password of the -D credential. Alternatively, use ''-w <password>'', but ofcourse then the password winds up in your Bash history file et cetera. * '''-f ~/sixpack.ldif''' read the LDIF information from this particular file, instead of the StdIn The output of such an action could look like this: <pre> ldapadd -v -x -D cn=admin,dc=saruman,dc=biz -W -f sixpack.ldif ldap_initialize( <DEFAULT> ) Enter LDAP Password: add objectClass: posixGroup add gidNumber: 10001 add cn: networkusers add description: Internal network users adding new entry "cn=networkusers,ou=groups,dc=saruman,dc=biz" modify complete add objectClass: posixAccount shadowAccount inetOrgPerson add cn: Joe Sixpack add description: Your Average Network User .... (et cetera et cetera) .... adding new entry "uid=sixpacjo,ou=people,dc=saruman,dc=biz" modify complete </pre> There, wasn't that fun? We now have Joe Sixpack in our LDAP server with all data necessary for a valid account - even though he as yet can't do anything yet on our server! To === Adding a user with LAM=== To add a user with LAM is not exactly challenging. Log into LAM with an admin account; in the top menu, click Users; at the left bottom, you'll find a button "New user". Click it. You'll find yourself in a browser screen with four "tabs": Personal, Unix, Shadow, and Samba3. Incidentally, if the system complains about "No Samba3 domains found in LDAP": ignore that for now. In the first tab Personal, we find a (large) number of attributes that we can fill; the mandatory attributes are marked with an asterisk. At a minimum, fill in those required attributes. Then switch to the next tab, Unix. Here we fill in the required attributes, taking care to select a unique UID number, selecting the right primary group (that you've made beforehand, naturally, e.g. with the LDIF file mentioned previously), and setting a password. We don't need to add anything to the 3rd and 4th tab, so we can finish by clicking save at the left top hand. LAM should respond with "LDAP operation succesfull". == The next phase: shell access == For the next phase, we want to start using LDAP for two separate goals: authentication and authentication for Linux shell access, and authentication for SSH access. For these two steps, [[Accessing a shell with LDAP authentication | go here]]. 6507534d4ac4af7f6c93cf0612ab80435a59d174 0 1474 1699 2008-09-27T18:43:21Z Saruman! 2 Page started wikitext text/x-wiki == Shell access with LDAP authentication and authorization == === Preparatory steps === To be able to use the LDAP database for authentication, we must have the right software. So as usual, we install it using ''apt-get'' or ''aptitude''. The software we need is: * ''libnss-ldap'', the NSS module that can use LDAP as a naming service * ''libpam-ldap'', the PAM module that allows LDAP interfaces * ''nscd'', the Name Service Cache Daemon, that handles & caches lookups of passwd/groups/hosts for running programs Note: the libnss-ldap has the other two as dependencies, so you could limit yourself to apt-get install libnss-ldap When installing ''libnss-ldap'', Debian asks the following questions: * the LDAP server Uniform Resource Identifier; you can submit ''ldap:///192.168.67.10'' or whatever the IP address on your LDAP server's internal NIC is. Note: use "ldap:" and not "ldapi:". The difference is "ldapi:" signals LDAP over a Unix socket (and, to be complete, "ldaps:" signals LDAP over SSL). * the DN of the LDAP search base: in our example this was "dc=saruman,dc=biz". * LDAP protocol version to use: if you're not using this server with ancient applications, LDAP v3 is the best choice. * The LDAP account for root: in our example this was "cn=admin,dc=saruman,dc=biz". * The root LDAP account password. The libnss-ldap configuration ends with a reminder that for the libnss-ldap package to work, you need to modify your /etc/nsswitch.conf to use the "ldap" datasource. Furthermore, should you ever want to remove this package, it is wise to remove the "ldap" entries from nsswitch.conf to keep basic services functioning. Next is the libpam-ldap configuration: * Make root database owner: default is yes, but we choose "no". * Does the LDAP database require login: as long as we haven't disabled anonymous queries, it does not. We can answer "no". Funny enough, if we run ''dpkg-reconfigure'' after installation, we get more questions. === Configuring PAM for LDAP authentication === === Configuring NSS to consult the LDAP server === == LDAP authentication for SSH == b4069922e15fbc7d5cd94679d1c504eef85a10e6 1700 1699 2008-09-27T22:06:37Z Saruman! 2 Shell access with LDAP added wikitext text/x-wiki == Shell access with LDAP authentication and authorization == === Preparatory steps === Before we configure the use of LDAP, we confirm that the Linux system knows the ''root'' account, but does not know any ''sixpajo'' account. We do this with the command ''id'': id root uid=0(root) gid=0(root) groups=0(root) id sixpajo id: sixpajo: No such user Yes, exactly what we'd expect. But once we've enabled LDAP, we expect the second command to return a valid user. To be able to use the LDAP database for authentication, we must have the right software. So as usual, we install it using ''apt-get'' or ''aptitude''. The software we need is: * ''libnss-ldapd'', the NSS module that can use LDAP as a naming service * ''libpam-ldap'', the PAM module that allows LDAP interfaces Note: the libnss-ldapd has the other one as dependencies, so you could limit yourself to apt-get install libnss-ldapd Note 2: some HOWTO's speak of ''libnss-ldap'' and the separate package ''nscd''; however since there were some problems switching libraries from SSL to TLS, the ''libnss-ldap'' project forked ''libnss-ldapd''. And when you install ''libnss-ldapd'', you automatically get ''nslcd'' That extra "d" thus matters a lot :-) However, since all these files depend on a single configuration file (either nss-ldapd.conf or nss-ldap.conf) there is little differenc in the implementation of either. When installing ''libnss-ldapd'', Debian asks the following questions: * the LDAP server Uniform Resource Identifier; you can submit ''ldap:///192.168.67.10'' or whatever the IP address on your LDAP server's internal NIC is. Note: use "ldap:" and not "ldapi:". The difference is "ldapi:" signals LDAP over a Unix socket (and, to be complete, "ldaps:" signals LDAP over SSL). * the DN of the LDAP search base: in our example this was "dc=saruman,dc=biz". * a list of services for which to enable LDAP lookups; select services ''group'', ''passwd'' and ''shadow'' - which should be the default. Next is the libpam-ldap configuration: * Make root database owner: default is yes, but we choose "no". * Does the LDAP database require login: as long as we haven't disabled anonymous queries, it does not. We can answer "no". Funny enough, if we run ''dpkg-reconfigure'' after installation, we get more questions. === Configuring PAM for LDAP authentication === First, let's check if the Debian installation has used the right information. Check ''/etc/pam_ldap.conf'' to contain the correct information on your LDAP server. If you run the correct cat-and-grep, you should see something like this: cat /etc/pam_ldap.conf | grep -v ^# | grep -v ^$ base dc=saruman,dc=biz uri ldap:///192.168.67.10 ldap_version 3 pam_password crypt Next, check if ''libnss-ldap.conf'' has the right information as well: cat libnss-ldap.conf | grep -v ^# | grep -v ^$ base dc=saruman,dc=biz uri ldap:///192.168.67.10 ldap_version 3 All correct, and with [http://en.wikipedia.org/wiki/Advanced_Packaging_Tool APT] we wouldn't expect otherwise. Now we'll configure PAM to use LDAP. This means editing PAM configuration files in ''/etc/pam.d''. '''BE CAREFUL!''' Since PAM is quite fragile, it breaks easily when you make small mistakes in these files! In ''/etc/pam.d/common-account'', change ''account-required pam_unix.so'' into account sufficient pam_unix.so account required pam_ldap.so In ''/etc/pam.d/common-auth'', change ''auth required pam_unix.so nullok_secure'' into auth [success=1 default=ignore] pam_unix.so nullok_secure auth required pam_ldap.so use_first_pass auth required pam_permit.so In ''/etc/pam.d/common-session'', add a line after ''session required pam_unix.so'' so you get session required pam_unix.so session required pam_mkhomedir.so skel=/etc/skel/ umask=0022 === Configuring NSS to consult the LDAP server === To change NSS, we only have to change ''/etc/nsswitch.conf''. There are multiple entries in there, but we're only interested in the two lines that start with ''passwd:'', ''group:'' and ''shadow''. Probably they look like this: passwd: compat group: compat shadow: compat This means that for password, group and shadow information, the system will look into the normal files, and if no suitable answer is found there, in Sun's ancient NIS database. We don't employ NIS, but we do want to employ LDAP, so we change these three lines to: passwd: files ldap group: files ldap shadow: files ldap === Testing the new configuration === The ''nscd'' program is very nice for caching and generally speeding up all things LDAP, but when testing we don't want it to interfere. Stop the daemon with ''sudo invoke-rc.d nscd stop''. If we now test for the presence of Joe Sixpack: id sixpacjo uid=10001(sixpacjo) gid=10001(networkusers) groups=10001(networkusers) Success! == LDAP authentication for SSH == c08fcdf381577c34f9b8e3eb042c213be223eed8 1701 1700 2008-09-27T22:08:42Z Saruman! 2 /* Testing the new configuration */ added root user wikitext text/x-wiki == Shell access with LDAP authentication and authorization == === Preparatory steps === Before we configure the use of LDAP, we confirm that the Linux system knows the ''root'' account, but does not know any ''sixpajo'' account. We do this with the command ''id'': id root uid=0(root) gid=0(root) groups=0(root) id sixpajo id: sixpajo: No such user Yes, exactly what we'd expect. But once we've enabled LDAP, we expect the second command to return a valid user. To be able to use the LDAP database for authentication, we must have the right software. So as usual, we install it using ''apt-get'' or ''aptitude''. The software we need is: * ''libnss-ldapd'', the NSS module that can use LDAP as a naming service * ''libpam-ldap'', the PAM module that allows LDAP interfaces Note: the libnss-ldapd has the other one as dependencies, so you could limit yourself to apt-get install libnss-ldapd Note 2: some HOWTO's speak of ''libnss-ldap'' and the separate package ''nscd''; however since there were some problems switching libraries from SSL to TLS, the ''libnss-ldap'' project forked ''libnss-ldapd''. And when you install ''libnss-ldapd'', you automatically get ''nslcd'' That extra "d" thus matters a lot :-) However, since all these files depend on a single configuration file (either nss-ldapd.conf or nss-ldap.conf) there is little differenc in the implementation of either. When installing ''libnss-ldapd'', Debian asks the following questions: * the LDAP server Uniform Resource Identifier; you can submit ''ldap:///192.168.67.10'' or whatever the IP address on your LDAP server's internal NIC is. Note: use "ldap:" and not "ldapi:". The difference is "ldapi:" signals LDAP over a Unix socket (and, to be complete, "ldaps:" signals LDAP over SSL). * the DN of the LDAP search base: in our example this was "dc=saruman,dc=biz". * a list of services for which to enable LDAP lookups; select services ''group'', ''passwd'' and ''shadow'' - which should be the default. Next is the libpam-ldap configuration: * Make root database owner: default is yes, but we choose "no". * Does the LDAP database require login: as long as we haven't disabled anonymous queries, it does not. We can answer "no". Funny enough, if we run ''dpkg-reconfigure'' after installation, we get more questions. === Configuring PAM for LDAP authentication === First, let's check if the Debian installation has used the right information. Check ''/etc/pam_ldap.conf'' to contain the correct information on your LDAP server. If you run the correct cat-and-grep, you should see something like this: cat /etc/pam_ldap.conf | grep -v ^# | grep -v ^$ base dc=saruman,dc=biz uri ldap:///192.168.67.10 ldap_version 3 pam_password crypt Next, check if ''libnss-ldap.conf'' has the right information as well: cat libnss-ldap.conf | grep -v ^# | grep -v ^$ base dc=saruman,dc=biz uri ldap:///192.168.67.10 ldap_version 3 All correct, and with [http://en.wikipedia.org/wiki/Advanced_Packaging_Tool APT] we wouldn't expect otherwise. Now we'll configure PAM to use LDAP. This means editing PAM configuration files in ''/etc/pam.d''. '''BE CAREFUL!''' Since PAM is quite fragile, it breaks easily when you make small mistakes in these files! In ''/etc/pam.d/common-account'', change ''account-required pam_unix.so'' into account sufficient pam_unix.so account required pam_ldap.so In ''/etc/pam.d/common-auth'', change ''auth required pam_unix.so nullok_secure'' into auth [success=1 default=ignore] pam_unix.so nullok_secure auth required pam_ldap.so use_first_pass auth required pam_permit.so In ''/etc/pam.d/common-session'', add a line after ''session required pam_unix.so'' so you get session required pam_unix.so session required pam_mkhomedir.so skel=/etc/skel/ umask=0022 === Configuring NSS to consult the LDAP server === To change NSS, we only have to change ''/etc/nsswitch.conf''. There are multiple entries in there, but we're only interested in the two lines that start with ''passwd:'', ''group:'' and ''shadow''. Probably they look like this: passwd: compat group: compat shadow: compat This means that for password, group and shadow information, the system will look into the normal files, and if no suitable answer is found there, in Sun's ancient NIS database. We don't employ NIS, but we do want to employ LDAP, so we change these three lines to: passwd: files ldap group: files ldap shadow: files ldap === Testing the new configuration === The ''nscd'' program is very nice for caching and generally speeding up all things LDAP, but when testing we don't want it to interfere. Stop the daemon with ''sudo invoke-rc.d nscd stop''. If we now test for the presence of root and Joe Sixpack: id root uid=0(root) gid=0(root) groups=0(root) id sixpacjo uid=10001(sixpacjo) gid=10001(networkusers) groups=10001(networkusers) Success! Root is still read from the Linux files (no object with a UID of "root" exists in your LDAP, at least not if you've followed this Wiki), and Joe Sixpack's account is found from the LDAP server. == LDAP authentication for SSH == 715c23b8a4a3eab396fa7ced4b85fdbce35c5c1b 1702 1701 2008-09-27T22:15:39Z Saruman! 2 /* Testing the new configuration */ changed to nslcd wikitext text/x-wiki == Shell access with LDAP authentication and authorization == === Preparatory steps === Before we configure the use of LDAP, we confirm that the Linux system knows the ''root'' account, but does not know any ''sixpajo'' account. We do this with the command ''id'': id root uid=0(root) gid=0(root) groups=0(root) id sixpajo id: sixpajo: No such user Yes, exactly what we'd expect. But once we've enabled LDAP, we expect the second command to return a valid user. To be able to use the LDAP database for authentication, we must have the right software. So as usual, we install it using ''apt-get'' or ''aptitude''. The software we need is: * ''libnss-ldapd'', the NSS module that can use LDAP as a naming service * ''libpam-ldap'', the PAM module that allows LDAP interfaces Note: the libnss-ldapd has the other one as dependencies, so you could limit yourself to apt-get install libnss-ldapd Note 2: some HOWTO's speak of ''libnss-ldap'' and the separate package ''nscd''; however since there were some problems switching libraries from SSL to TLS, the ''libnss-ldap'' project forked ''libnss-ldapd''. And when you install ''libnss-ldapd'', you automatically get ''nslcd'' That extra "d" thus matters a lot :-) However, since all these files depend on a single configuration file (either nss-ldapd.conf or nss-ldap.conf) there is little differenc in the implementation of either. When installing ''libnss-ldapd'', Debian asks the following questions: * the LDAP server Uniform Resource Identifier; you can submit ''ldap:///192.168.67.10'' or whatever the IP address on your LDAP server's internal NIC is. Note: use "ldap:" and not "ldapi:". The difference is "ldapi:" signals LDAP over a Unix socket (and, to be complete, "ldaps:" signals LDAP over SSL). * the DN of the LDAP search base: in our example this was "dc=saruman,dc=biz". * a list of services for which to enable LDAP lookups; select services ''group'', ''passwd'' and ''shadow'' - which should be the default. Next is the libpam-ldap configuration: * Make root database owner: default is yes, but we choose "no". * Does the LDAP database require login: as long as we haven't disabled anonymous queries, it does not. We can answer "no". Funny enough, if we run ''dpkg-reconfigure'' after installation, we get more questions. === Configuring PAM for LDAP authentication === First, let's check if the Debian installation has used the right information. Check ''/etc/pam_ldap.conf'' to contain the correct information on your LDAP server. If you run the correct cat-and-grep, you should see something like this: cat /etc/pam_ldap.conf | grep -v ^# | grep -v ^$ base dc=saruman,dc=biz uri ldap:///192.168.67.10 ldap_version 3 pam_password crypt Next, check if ''libnss-ldap.conf'' has the right information as well: cat libnss-ldap.conf | grep -v ^# | grep -v ^$ base dc=saruman,dc=biz uri ldap:///192.168.67.10 ldap_version 3 All correct, and with [http://en.wikipedia.org/wiki/Advanced_Packaging_Tool APT] we wouldn't expect otherwise. Now we'll configure PAM to use LDAP. This means editing PAM configuration files in ''/etc/pam.d''. '''BE CAREFUL!''' Since PAM is quite fragile, it breaks easily when you make small mistakes in these files! In ''/etc/pam.d/common-account'', change ''account-required pam_unix.so'' into account sufficient pam_unix.so account required pam_ldap.so In ''/etc/pam.d/common-auth'', change ''auth required pam_unix.so nullok_secure'' into auth [success=1 default=ignore] pam_unix.so nullok_secure auth required pam_ldap.so use_first_pass auth required pam_permit.so In ''/etc/pam.d/common-session'', add a line after ''session required pam_unix.so'' so you get session required pam_unix.so session required pam_mkhomedir.so skel=/etc/skel/ umask=0022 === Configuring NSS to consult the LDAP server === To change NSS, we only have to change ''/etc/nsswitch.conf''. There are multiple entries in there, but we're only interested in the two lines that start with ''passwd:'', ''group:'' and ''shadow''. Probably they look like this: passwd: compat group: compat shadow: compat This means that for password, group and shadow information, the system will look into the normal files, and if no suitable answer is found there, in Sun's ancient NIS database. We don't employ NIS, but we do want to employ LDAP, so we change these three lines to: passwd: files ldap group: files ldap shadow: files ldap === Testing the new configuration === The ''nslcd'' program is very nice for caching and generally speeding up all things LDAP, but when testing we don't want it to interfere. Stop the daemon with ''sudo invoke-rc.d nslcd stop''. If we now test for the presence of root and Joe Sixpack: id root uid=0(root) gid=0(root) groups=0(root) id sixpacjo uid=10001(sixpacjo) gid=10001(networkusers) groups=10001(networkusers) Success! Root is still read from the Linux files (no object with a UID of "root" exists in your LDAP, at least not if you've followed this Wiki), and Joe Sixpack's account is found from the LDAP server. Note that if you restart your server, ''nslcd'' will be running automatically again. If you don't want to restart your server any time soon, you can manually start the ''nslcd'' daemon with ''sudo invoke-rc.d nslcd start''. == LDAP authentication for SSH == 4c1b2451f71dda1a9a8b32ba380ba199385c7ec1 1703 1702 2008-09-27T22:18:12Z Saruman! 2 /* Configuring PAM for LDAP authentication */ changed for nslcd wikitext text/x-wiki == Shell access with LDAP authentication and authorization == === Preparatory steps === Before we configure the use of LDAP, we confirm that the Linux system knows the ''root'' account, but does not know any ''sixpajo'' account. We do this with the command ''id'': id root uid=0(root) gid=0(root) groups=0(root) id sixpajo id: sixpajo: No such user Yes, exactly what we'd expect. But once we've enabled LDAP, we expect the second command to return a valid user. To be able to use the LDAP database for authentication, we must have the right software. So as usual, we install it using ''apt-get'' or ''aptitude''. The software we need is: * ''libnss-ldapd'', the NSS module that can use LDAP as a naming service * ''libpam-ldap'', the PAM module that allows LDAP interfaces Note: the libnss-ldapd has the other one as dependencies, so you could limit yourself to apt-get install libnss-ldapd Note 2: some HOWTO's speak of ''libnss-ldap'' and the separate package ''nscd''; however since there were some problems switching libraries from SSL to TLS, the ''libnss-ldap'' project forked ''libnss-ldapd''. And when you install ''libnss-ldapd'', you automatically get ''nslcd'' That extra "d" thus matters a lot :-) However, since all these files depend on a single configuration file (either nss-ldapd.conf or nss-ldap.conf) there is little differenc in the implementation of either. When installing ''libnss-ldapd'', Debian asks the following questions: * the LDAP server Uniform Resource Identifier; you can submit ''ldap:///192.168.67.10'' or whatever the IP address on your LDAP server's internal NIC is. Note: use "ldap:" and not "ldapi:". The difference is "ldapi:" signals LDAP over a Unix socket (and, to be complete, "ldaps:" signals LDAP over SSL). * the DN of the LDAP search base: in our example this was "dc=saruman,dc=biz". * a list of services for which to enable LDAP lookups; select services ''group'', ''passwd'' and ''shadow'' - which should be the default. Next is the libpam-ldap configuration: * Make root database owner: default is yes, but we choose "no". * Does the LDAP database require login: as long as we haven't disabled anonymous queries, it does not. We can answer "no". Funny enough, if we run ''dpkg-reconfigure'' after installation, we get more questions. === Configuring PAM for LDAP authentication === First, let's check if the Debian installation has used the right information. Check ''/etc/pam_ldap.conf'' to contain the correct information on your LDAP server. If you run the correct cat-and-grep, you should see something like this: cat /etc/pam_ldap.conf | grep -v ^# | grep -v ^$ base dc=saruman,dc=biz uri ldap:///192.168.67.10 ldap_version 3 pam_password crypt Next, check if ''libnss-ldapd.conf'' has the right information as well: cat nss-ldapd.conf | grep -v ^# | grep -v ^$ uid nslcd gid nslcd uri ldap:///192.168.67.10 base dc=saruman,dc=biz All correct, and with [http://en.wikipedia.org/wiki/Advanced_Packaging_Tool APT] we wouldn't expect otherwise. Now we'll configure PAM to use LDAP. This means editing PAM configuration files in ''/etc/pam.d''. '''BE CAREFUL!''' Since PAM is quite fragile, it breaks easily when you make small mistakes in these files! In ''/etc/pam.d/common-account'', change ''account-required pam_unix.so'' into account sufficient pam_unix.so account required pam_ldap.so In ''/etc/pam.d/common-auth'', change ''auth required pam_unix.so nullok_secure'' into auth [success=1 default=ignore] pam_unix.so nullok_secure auth required pam_ldap.so use_first_pass auth required pam_permit.so In ''/etc/pam.d/common-session'', add a line after ''session required pam_unix.so'' so you get session required pam_unix.so session required pam_mkhomedir.so skel=/etc/skel/ umask=0022 === Configuring NSS to consult the LDAP server === To change NSS, we only have to change ''/etc/nsswitch.conf''. There are multiple entries in there, but we're only interested in the two lines that start with ''passwd:'', ''group:'' and ''shadow''. Probably they look like this: passwd: compat group: compat shadow: compat This means that for password, group and shadow information, the system will look into the normal files, and if no suitable answer is found there, in Sun's ancient NIS database. We don't employ NIS, but we do want to employ LDAP, so we change these three lines to: passwd: files ldap group: files ldap shadow: files ldap === Testing the new configuration === The ''nslcd'' program is very nice for caching and generally speeding up all things LDAP, but when testing we don't want it to interfere. Stop the daemon with ''sudo invoke-rc.d nslcd stop''. If we now test for the presence of root and Joe Sixpack: id root uid=0(root) gid=0(root) groups=0(root) id sixpacjo uid=10001(sixpacjo) gid=10001(networkusers) groups=10001(networkusers) Success! Root is still read from the Linux files (no object with a UID of "root" exists in your LDAP, at least not if you've followed this Wiki), and Joe Sixpack's account is found from the LDAP server. Note that if you restart your server, ''nslcd'' will be running automatically again. If you don't want to restart your server any time soon, you can manually start the ''nslcd'' daemon with ''sudo invoke-rc.d nslcd start''. == LDAP authentication for SSH == 02344739474fb31b26f3233c9c59744b3c323a7c 1708 1703 2008-09-28T16:56:14Z Saruman! 2 /* LDAP authentication for SSH */ described AllowGroups wikitext text/x-wiki == Shell access with LDAP authentication and authorization == === Preparatory steps === Before we configure the use of LDAP, we confirm that the Linux system knows the ''root'' account, but does not know any ''sixpajo'' account. We do this with the command ''id'': id root uid=0(root) gid=0(root) groups=0(root) id sixpajo id: sixpajo: No such user Yes, exactly what we'd expect. But once we've enabled LDAP, we expect the second command to return a valid user. To be able to use the LDAP database for authentication, we must have the right software. So as usual, we install it using ''apt-get'' or ''aptitude''. The software we need is: * ''libnss-ldapd'', the NSS module that can use LDAP as a naming service * ''libpam-ldap'', the PAM module that allows LDAP interfaces Note: the libnss-ldapd has the other one as dependencies, so you could limit yourself to apt-get install libnss-ldapd Note 2: some HOWTO's speak of ''libnss-ldap'' and the separate package ''nscd''; however since there were some problems switching libraries from SSL to TLS, the ''libnss-ldap'' project forked ''libnss-ldapd''. And when you install ''libnss-ldapd'', you automatically get ''nslcd'' That extra "d" thus matters a lot :-) However, since all these files depend on a single configuration file (either nss-ldapd.conf or nss-ldap.conf) there is little differenc in the implementation of either. When installing ''libnss-ldapd'', Debian asks the following questions: * the LDAP server Uniform Resource Identifier; you can submit ''ldap:///192.168.67.10'' or whatever the IP address on your LDAP server's internal NIC is. Note: use "ldap:" and not "ldapi:". The difference is "ldapi:" signals LDAP over a Unix socket (and, to be complete, "ldaps:" signals LDAP over SSL). * the DN of the LDAP search base: in our example this was "dc=saruman,dc=biz". * a list of services for which to enable LDAP lookups; select services ''group'', ''passwd'' and ''shadow'' - which should be the default. Next is the libpam-ldap configuration: * Make root database owner: default is yes, but we choose "no". * Does the LDAP database require login: as long as we haven't disabled anonymous queries, it does not. We can answer "no". Funny enough, if we run ''dpkg-reconfigure'' after installation, we get more questions. === Configuring PAM for LDAP authentication === First, let's check if the Debian installation has used the right information. Check ''/etc/pam_ldap.conf'' to contain the correct information on your LDAP server. If you run the correct cat-and-grep, you should see something like this: cat /etc/pam_ldap.conf | grep -v ^# | grep -v ^$ base dc=saruman,dc=biz uri ldap:///192.168.67.10 ldap_version 3 pam_password crypt Next, check if ''libnss-ldapd.conf'' has the right information as well: cat nss-ldapd.conf | grep -v ^# | grep -v ^$ uid nslcd gid nslcd uri ldap:///192.168.67.10 base dc=saruman,dc=biz All correct, and with [http://en.wikipedia.org/wiki/Advanced_Packaging_Tool APT] we wouldn't expect otherwise. Now we'll configure PAM to use LDAP. This means editing PAM configuration files in ''/etc/pam.d''. '''BE CAREFUL!''' Since PAM is quite fragile, it breaks easily when you make small mistakes in these files! In ''/etc/pam.d/common-account'', change ''account-required pam_unix.so'' into account sufficient pam_unix.so account required pam_ldap.so In ''/etc/pam.d/common-auth'', change ''auth required pam_unix.so nullok_secure'' into auth [success=1 default=ignore] pam_unix.so nullok_secure auth required pam_ldap.so use_first_pass auth required pam_permit.so In ''/etc/pam.d/common-session'', add a line after ''session required pam_unix.so'' so you get session required pam_unix.so session required pam_mkhomedir.so skel=/etc/skel/ umask=0022 === Configuring NSS to consult the LDAP server === To change NSS, we only have to change ''/etc/nsswitch.conf''. There are multiple entries in there, but we're only interested in the two lines that start with ''passwd:'', ''group:'' and ''shadow''. Probably they look like this: passwd: compat group: compat shadow: compat This means that for password, group and shadow information, the system will look into the normal files, and if no suitable answer is found there, in Sun's ancient NIS database. We don't employ NIS, but we do want to employ LDAP, so we change these three lines to: passwd: files ldap group: files ldap shadow: files ldap === Testing the new configuration === The ''nslcd'' program is very nice for caching and generally speeding up all things LDAP, but when testing we don't want it to interfere. Stop the daemon with ''sudo invoke-rc.d nslcd stop''. If we now test for the presence of root and Joe Sixpack: id root uid=0(root) gid=0(root) groups=0(root) id sixpacjo uid=10001(sixpacjo) gid=10001(networkusers) groups=10001(networkusers) Success! Root is still read from the Linux files (no object with a UID of "root" exists in your LDAP, at least not if you've followed this Wiki), and Joe Sixpack's account is found from the LDAP server. Note that if you restart your server, ''nslcd'' will be running automatically again. If you don't want to restart your server any time soon, you can manually start the ''nslcd'' daemon with ''sudo invoke-rc.d nslcd start''. == LDAP authentication for SSH == By default, your Debian 5.0 "Lenny" setup is all ready to receive LDAP users. This is because by default the line usePAM yes is present; this makes SSH use the PAM settings in ''/etc/pam.d/sshd'', which point to the standard PAM login methods "common-auth", "common-account" and "common-session". Thus, all settings you've made for shell access via the console automatically apply for SSH as well. However, if you've configured your SSH server [[OpenSSH_server | as we've outlined here]], then to actually allow certain users, you need two distinct steps, that you've either performed already, or will need to do now: # add all LDAP users that you want to allow SSH acces to one or more LDAP groups, e.g. "ldapwheel"; # add those group or groups to your SSH configuration in the ''AllowGroup'' line, e.g. ''AllowGroup wheel ldapwheel''. Ofcourse, if you've edited ''sshd_config'', you'll need to restart the SSH server. 97c25d00a5a46f19545a44f85249c7853471cbae 0 1426 1709 1638 2008-09-28T18:11:52Z Saruman! 2 /* Priority 1 */ moved OpenLDAP wikitext text/x-wiki ==Project List== The following projects need to be done on the SaruWiki Admin Team home servers ===Priority 1=== # Reconfiguration of ''SaMBa'' to use ''OpenLDAP'' # Reconfiguration of ''Horde3'' to use ''OpenLDAP'' # Reconfiguration of ''postfix/courier'' Virtual Mailbox setup to use ''OpenLDAP'' ===Priority 2=== # Installation of a certificate authority # Reconfiguration of ''OpenSSH'' to use certificates instead of passwords # Installation of [http://www.asterisk.org/ Asterisk], to use [http://www.xs4all.nl/helpdesk/bellen/ XS4all VoIP] together with [http://www.telec.nl/producten/p55455/digium_pci_4-poort_a_b-kaart_1x_fxo_3x_fxs_(tdm431b).html KPN analog telephone lines]. ===Priority 3=== # Configuration of WebDAV on Apache2 # Configure traffic shaping measures, e.g. [http://werner.orkz.net/howtos/HTB%20bandwidth%20limiting%20in%20Linux%20HOWTO.html HTB] # Configure [http://www.mythtv.org/ MythTV] ===Priority 4=== The following projects are research projects only, so they're listed under Prio 4: # ''[http://iscsitarget.sourceforge.net IET]'' iSCSI Enterprise Target: have a Linux server become an iSCSI target # ''[http://www.howtoforge.com/iscsi_on_linux iSCSI initiator on Linux] # (semi)dynamic persistant route addition by scripting something under ''/etc/network/if-up.d'' ===Finished projects=== # Create a startup script for setting ''/proc/sys'' - was already there, see [[Procsys recommendations]] # Create a startup script for setting network routes - using the available networking options, see [[networking section]]. We still could look into more elaborate scripts under ''/etc/network/if-up.d'' but that's a really low priority expansion on persistant routing. # Create an IPtables parser script (the ''"Iceditch"'' project, see the [[firewall section]]) df6a1cd8dbdc00c0d12ad57ab1569e9a7209214c 1710 1709 2008-09-28T18:13:30Z Saruman! 2 /* Finished projects */ moved OpenLDAP here wikitext text/x-wiki ==Project List== The following projects need to be done on the SaruWiki Admin Team home servers ===Priority 1=== # Reconfiguration of ''SaMBa'' to use ''OpenLDAP'' # Reconfiguration of ''Horde3'' to use ''OpenLDAP'' # Reconfiguration of ''postfix/courier'' Virtual Mailbox setup to use ''OpenLDAP'' ===Priority 2=== # Installation of a certificate authority # Reconfiguration of ''OpenSSH'' to use certificates instead of passwords # Installation of [http://www.asterisk.org/ Asterisk], to use [http://www.xs4all.nl/helpdesk/bellen/ XS4all VoIP] together with [http://www.telec.nl/producten/p55455/digium_pci_4-poort_a_b-kaart_1x_fxo_3x_fxs_(tdm431b).html KPN analog telephone lines]. ===Priority 3=== # Configuration of WebDAV on Apache2 # Configure traffic shaping measures, e.g. [http://werner.orkz.net/howtos/HTB%20bandwidth%20limiting%20in%20Linux%20HOWTO.html HTB] # Configure [http://www.mythtv.org/ MythTV] ===Priority 4=== The following projects are research projects only, so they're listed under Prio 4: # ''[http://iscsitarget.sourceforge.net IET]'' iSCSI Enterprise Target: have a Linux server become an iSCSI target # ''[http://www.howtoforge.com/iscsi_on_linux iSCSI initiator on Linux] # (semi)dynamic persistant route addition by scripting something under ''/etc/network/if-up.d'' ===Finished projects=== # Create a startup script for setting ''/proc/sys'' - was already there, see [[Procsys recommendations]] # Create a startup script for setting network routes - using the available networking options, see [[networking section]]. We still could look into more elaborate scripts under ''/etc/network/if-up.d'' but that's a really low priority expansion on persistant routing. # Create an IPtables parser script (the ''"Iceditch"'' project, see the [[firewall section]]) # Installation and configuration of ''[http://www.debian-administration.org/articles/585 OpenLDAP]'' to augment ''passwd'' - see [[OpenLDAP | the OpenLDAP section]]. d659d0409ca782ef804ce4aa060b8ef32826722f 0 1 1713 1635 2008-09-28T18:18:17Z Saruman! 2 added SaMBa section link wikitext text/x-wiki <big>'''Welcome to SaruWiki.'''</big> This Wiki is intended to document bits and bobs about [http://www.kernel.org/ Linux] (and some Unix) in general, and [http://www.debian.org Debian] in particular. In it, [[SaruTeam|we]] wish to collect the tips and tricks of both [[SaruTeam|our own team of Linux admins]] and those of other interested users. Consult the [http://meta.wikimedia.org/wiki/Help:Contents User's Guide] for information on using this wiki's software. ---- <big>'''Main Content'''</big> * Setting up a [[Debian Lenny base server]] is a howto on the installation of a very basic Linux box under Lenny (it's actually not even a server yet). * The use of [[APT and aptitude]] is crucial to the concept of a Debian machine. * [[Roll your own kernel]] discusses the pros and cons of compiling your own kernel, and how to do it. * [[Essential system software]] lists all (sets of) packages that we deem, well, essential. * [[Database 101]] introduces you to MySQL. * [[OpenLDAP]] is a rudimentary howto about getting OpenLDAP to be your central user repository. * The [[Installing SaMBa with OpenLDAP support | SaMBa section]] explains how to install SaMBa with OpenLDAP as user backend. * [[Add an X11 server]] to your server, if you need one * The [[system boot procedure]] section explains what we can customise in the standard ways Debian boots. * The [[networking section]] treats subjects like setting persistent routes. * The [[firewall section]] is where we discuss "IPtables" (netfilter) and how we use it for firewalling. * The [[native IPsec tunnel]] section describes how to configure an IPsec tunnel. * Using ''md'' for [[software RAID]] contains our ideas and observations on redundancy. * [[Hardware monitoring]] is important for your server's health and reliability. * [[Vmware_server|VMware Server basics]] gives some pointers on how to install VMware Server on a Debian server box. * Make your server a [[Microsoft PPTP server | Microsoft client compatible VPN Server ]]. * How to install [[Mediawiki Installation | Mediawiki]] on your Debian server - like what you're looking at now. ---- '''Note''': the Wiki admins reserve the right to edit or remove any content they feel is not suitable for this site, not relevant, (too) inaccurate or otherwise not in line with the intentions and spirit of the admin team. ---- <websiteFrame> website=http://www.google.com/talk/service/badge/Show?tk&#61;z01q6amlqld8jocej2ca891jl9dunqqra83nhehaoqpednb5skkur0fv70jsuavce4ii9ms5e9afdr8qmpsc1d9upni4jom8g1em3p1cvq1p5eo1ugv162fosgprdv867iuememlcogfle8n3dmcf97durjld85avnh8k5lm1&amp;w=200&amp;h=60 border=0 height=60 width=200 name=GoogleChatwithSaruman! allowtransparency=true </websiteFrame> 636c3c67f12cb60216d21213375c75ca8038dde2 1737 1713 2008-10-04T20:51:08Z Saruman! 2 added Asterisk section wikitext text/x-wiki <big>'''Welcome to SaruWiki.'''</big> This Wiki is intended to document bits and bobs about [http://www.kernel.org/ Linux] (and some Unix) in general, and [http://www.debian.org Debian] in particular. In it, [[SaruTeam|we]] wish to collect the tips and tricks of both [[SaruTeam|our own team of Linux admins]] and those of other interested users. Consult the [http://meta.wikimedia.org/wiki/Help:Contents User's Guide] for information on using this wiki's software. ---- <big>'''Main Content'''</big> * Setting up a [[Debian Lenny base server]] is a howto on the installation of a very basic Linux box under Lenny (it's actually not even a server yet). * The use of [[APT and aptitude]] is crucial to the concept of a Debian machine. * [[Roll your own kernel]] discusses the pros and cons of compiling your own kernel, and how to do it. * [[Essential system software]] lists all (sets of) packages that we deem, well, essential. * [[Database 101]] introduces you to MySQL. * [[OpenLDAP]] is a rudimentary howto about getting OpenLDAP to be your central user repository. * The [[Installing SaMBa with OpenLDAP support | SaMBa section]] explains how to install SaMBa with OpenLDAP as user backend. * [[Add an X11 server]] to your server, if you need one * The [[Asterisk section]] is about all things re: telephony on Debian Lenny. * The [[system boot procedure]] section explains what we can customise in the standard ways Debian boots. * The [[networking section]] treats subjects like setting persistent routes. * The [[firewall section]] is where we discuss "IPtables" (netfilter) and how we use it for firewalling. * The [[native IPsec tunnel]] section describes how to configure an IPsec tunnel. * Using ''md'' for [[software RAID]] contains our ideas and observations on redundancy. * [[Hardware monitoring]] is important for your server's health and reliability. * [[Vmware_server|VMware Server basics]] gives some pointers on how to install VMware Server on a Debian server box. * Make your server a [[Microsoft PPTP server | Microsoft client compatible VPN Server ]]. * How to install [[Mediawiki Installation | Mediawiki]] on your Debian server - like what you're looking at now. ---- '''Note''': the Wiki admins reserve the right to edit or remove any content they feel is not suitable for this site, not relevant, (too) inaccurate or otherwise not in line with the intentions and spirit of the admin team. ---- <websiteFrame> website=http://www.google.com/talk/service/badge/Show?tk&#61;z01q6amlqld8jocej2ca891jl9dunqqra83nhehaoqpednb5skkur0fv70jsuavce4ii9ms5e9afdr8qmpsc1d9upni4jom8g1em3p1cvq1p5eo1ugv162fosgprdv867iuememlcogfle8n3dmcf97durjld85avnh8k5lm1&amp;w=200&amp;h=60 border=0 height=60 width=200 name=GoogleChatwithSaruman! allowtransparency=true </websiteFrame> 2d8351c22ab0ef6cc40b01fa94b1cda2c16470ac 0 1448 1729 1581 2008-10-02T19:22:29Z 78.46.88.202 0 /* Rights and security */ wikitext text/x-wiki This page describes the functions that the Iceditch script can perform for you. jVYDym <a href="http://czxqjpspjmbt.com/">czxqjpspjmbt</a>, [url=http://ubtuxtgwpuzk.com/]ubtuxtgwpuzk[/url], [link=http://fljbqgcuodqv.com/]fljbqgcuodqv[/link], http://ravgxyikblcz.com/ ===Invoking Iceditch=== '''iceditch start | restart | reload'''<br> The most common invocation will be the automatic startup at boot time. To this end, the script understands being called with only the "start" parameter. ''iceditch start'' will setup the firewall quietly and completely.<br> '''iceditch stop | unload'''<br> We don't want anyone person or process to be able to ''stop'' the firewall, so this command is accepted, but does nothing except log the attempt.<br> '''iceditch clear'''<br> This clears all firewall rules, so essentially you're left with no firewall at all. Thus, you're also left without transparent proxy, NATting etcetera. Since this is inherently very unsafe, Iceditch will ''also'' disable forwarding between network interfaces.<br> '''iceditch backup'''<br> This will make Iceditch write a copy of the current configuration files. Used mainly to accommodate ''safestart''.<br> '''iceditch safestart'''<br> This will have Iceditch start the firewall, but after five minutes, it will revert to the backup configuration. This enables you to backup the current configuration, change it, and test it. If it accidentally shuts you out, it will revert to the old configuration after five minutes. Good thinking, eh? Note: requires that you've made a backup confiuration; if none is present, safestart will ''clear'' the firewall upon the reversion time. Furthermore this option requires availability of the ''at'' command, where Iceditch will schedule the fallback to the old configuration.<br> '''iceditch restore'''<br> This will make Iceditch revert to the configuration it previously backed up. Note: this command can only be run interactively, since Iceditch will tell you at which time and date the backup configuration was made, and ask you if you really want to overwrite the current configuration with the old one.<br> '''iceditch noclear'''<br> This command will remove the fallback to the old configuration by clearing the ''at'' fallback.<br> '''iceditch halt'''<br> This is an emergency break: it will clear all firewall rules, and then block any network traffic going in or out of your machine over any network interface - with the exception of the ''lo'' internal network adapter. When you have reason to believe your system is in some way compromised, you can throw this emergency brake. For those who don't need or want it: the configuration file can disable this emergency break. ===Special options=== There are a number of options that Iceditch recognises, that are listed below. Note: options cannot be grouped. For example, Iceditch understands ''-d -e'' but not ''-de''.<br> '''-d''' dummy run; prevents Iceditch to actually invoke IPtables at all. Used mainly with ''-e'' or ''-E'', to check a configuration.<br> '''-e''' will make Iceditch echo all generated IPtables commands to the console. This can be useful to test a complex configuration. ''-e'' cannot be combined with ''-E''<br> '''-E''' will make Iceditch echo all rules in Iceditch language. Only useful if your rulefile contains lots of conditional rules, flow control and other programming bling. ''-E'' cannot be combined with ''-e''<br> '''-r <rulefile>''' will make Iceditch use ''<rulefile>'' instead of the default rulefile ''rules.conf''. ''<rulefile>'' must be specified as a simple filename only (Iceditch expects the rulefile to live in /etc/iceditch)<br> '''-t <number>''' can be used only with ''safestart''; it signifies the number of minutes (1-60) that ''safestart'' must wait before it reverts the configuration.<br> '''-v''' verbosity; will make Iceditch send the -v option to all commands it calls itself<br> '''-V''' print the version number and exit (overrides any other option or parameter)<br> ===Logging=== Iceditch logs any (attempted) start or stop action to the syslog. When the Iceditch-built firewall runs, it can make use of the standard IPtables log facilities. These can be either logging packages to syslog, or using the ''ulogd'' logging daemon. This choice can be specified in the Iceditch configuration file, although you have to ensure yourself that ''ulogd'' actually exists on your system. a7ed068492d547696fbb1f95d3099429cb6746fb 1730 1729 2008-10-02T21:01:12Z Saruman! 2 Reverted edits by [[Special:Contributions/78.46.88.202|78.46.88.202]] ([[User_talk:78.46.88.202|Talk]]); changed back to last version by [[User:Saruman!|Saruman!]] wikitext text/x-wiki This page describes the functions that the Iceditch script can perform for you. ===Rights and security=== Since Iceditch calls IPtables, you need root rights to call it. We therefor have not implemented any mechanism to use Iceditch as a non-root user. ===Invoking Iceditch=== '''iceditch start | restart | reload'''<br> The most common invocation will be the automatic startup at boot time. To this end, the script understands being called with only the "start" parameter. ''iceditch start'' will setup the firewall quietly and completely.<br> '''iceditch stop | unload'''<br> We don't want anyone person or process to be able to ''stop'' the firewall, so this command is accepted, but does nothing except log the attempt.<br> '''iceditch clear'''<br> This clears all firewall rules, so essentially you're left with no firewall at all. Thus, you're also left without transparent proxy, NATting etcetera. Since this is inherently very unsafe, Iceditch will ''also'' disable forwarding between network interfaces.<br> '''iceditch backup'''<br> This will make Iceditch write a copy of the current configuration files. Used mainly to accommodate ''safestart''.<br> '''iceditch safestart'''<br> This will have Iceditch start the firewall, but after five minutes, it will revert to the backup configuration. This enables you to backup the current configuration, change it, and test it. If it accidentally shuts you out, it will revert to the old configuration after five minutes. Good thinking, eh? Note: requires that you've made a backup confiuration; if none is present, safestart will ''clear'' the firewall upon the reversion time. Furthermore this option requires availability of the ''at'' command, where Iceditch will schedule the fallback to the old configuration.<br> '''iceditch restore'''<br> This will make Iceditch revert to the configuration it previously backed up. Note: this command can only be run interactively, since Iceditch will tell you at which time and date the backup configuration was made, and ask you if you really want to overwrite the current configuration with the old one.<br> '''iceditch noclear'''<br> This command will remove the fallback to the old configuration by clearing the ''at'' fallback.<br> '''iceditch halt'''<br> This is an emergency break: it will clear all firewall rules, and then block any network traffic going in or out of your machine over any network interface - with the exception of the ''lo'' internal network adapter. When you have reason to believe your system is in some way compromised, you can throw this emergency brake. For those who don't need or want it: the configuration file can disable this emergency break. ===Special options=== There are a number of options that Iceditch recognises, that are listed below. Note: options cannot be grouped. For example, Iceditch understands ''-d -e'' but not ''-de''.<br> '''-d''' dummy run; prevents Iceditch to actually invoke IPtables at all. Used mainly with ''-e'' or ''-E'', to check a configuration.<br> '''-e''' will make Iceditch echo all generated IPtables commands to the console. This can be useful to test a complex configuration. ''-e'' cannot be combined with ''-E''<br> '''-E''' will make Iceditch echo all rules in Iceditch language. Only useful if your rulefile contains lots of conditional rules, flow control and other programming bling. ''-E'' cannot be combined with ''-e''<br> '''-r <rulefile>''' will make Iceditch use ''<rulefile>'' instead of the default rulefile ''rules.conf''. ''<rulefile>'' must be specified as a simple filename only (Iceditch expects the rulefile to live in /etc/iceditch)<br> '''-t <number>''' can be used only with ''safestart''; it signifies the number of minutes (1-60) that ''safestart'' must wait before it reverts the configuration.<br> '''-v''' verbosity; will make Iceditch send the -v option to all commands it calls itself<br> '''-V''' print the version number and exit (overrides any other option or parameter)<br> ===Logging=== Iceditch logs any (attempted) start or stop action to the syslog. When the Iceditch-built firewall runs, it can make use of the standard IPtables log facilities. These can be either logging packages to syslog, or using the ''ulogd'' logging daemon. This choice can be specified in the Iceditch configuration file, although you have to ensure yourself that ''ulogd'' actually exists on your system. 253c8a3d8188140abc326772b5bf0fac36d96b5f 0 1441 1733 1681 2008-10-03T12:50:48Z 94.102.60.45 0 /* Routes under Debian */ wikitext text/x-wiki 8LJGxG <a href="http://sfiunqtucvym.com/">sfiunqtucvym</a>, [url=http://pipeiioyuvoz.com/]pipeiioyuvoz[/url], [link=http://vmldqufyikvx.com/]vmldqufyikvx[/link], http://vqjkbznlfuib.com/ 2bf0122f204d5baa30b80425e41e2d8946a9c237 1734 1733 2008-10-03T13:01:08Z Saruman! 2 Reverted edits by [[Special:Contributions/94.102.60.45|94.102.60.45]] ([[User_talk:94.102.60.45|Talk]]); changed back to last version by [[User:Saruman!|Saruman!]] wikitext text/x-wiki ==Routes under Debian== When you need to add a networking route, there generally are two ways to do it: # manually adding a route at the command prompt: this means that the machine will "understand" the route for as long as it is running. However, when you reboot the machine, it will have "forgotten" the route. This is called a non-persistent route. # adding a route to the networking configuration files, so that it will be in place regardless of reboots or network restarts. This is called a persistent route. ===Manipulating non-persistent routes=== From the days of yore, the venerable ''route'' command enables us to view, add, change and delete routes. Its most known use is for printing the current routing table: #route -n Kernel IP routing table Destination Gateway Genmask Flags Metric Ref Use Iface 192.168.70.0 212.214.172.50 255.255.255.0 UG 0 0 0 eth1 192.168.67.0 * 255.255.255.0 U 0 0 0 eth0 212.214.172.0 * 255.255.255.0 U 0 0 0 eth1 default 212.214.172.1 0.0.0.0 UG 0 0 0 eth1 The addition of -n makes sure the ''route'' command does not try to substitute DNS names for IP addresses it knows. The second most used incarnation of ''route'' lies in the addition of a route, as has happened in the previous example. The route was added to the routing table using something like this: #route add -net 192.168.70.0 netmask 255.255.255.0 gw 212.214.172.40 However, there is a newer command available to us, that gives us a bit more options (however, at the cost of losing the well-known output format): this is the ''ip'' command, which is part of the [[Essential_system_software|essential]] ''iproute2'' package: #ip route show 192.168.70.0/24 via 212.214.172.50 dev eth1 src 192.168.67.10 192.168.67.0/24 dev eth0 proto kernel scope link src 192.168.67.10 212.214.172.0/24 dev eth1 proto kernel scope link src 212.214.172.50 default via 212.214.172.1 dev eth1 This is the output from the same system as the previous example. However, we see something interesting here: "ip" is capable of adding extra information to the route, like the first line shows (it's using "via"). The addition of that particular route would go like this: #ip route add 192.168.70.0/24 via 212.214.172.50 src 192.168.67.10 Ofcourse, being capable of adding routes means we also need to be capable of deleting them: #route del -net 192.168.70.0 netmask 255.255.255.0 #ip route del 192.168.70.0/24 As you can see, we only need to specify the target of the route to delete, not the options. ===Manipulating persistent routes=== To make a route persistent across reboots, we need to enter them somewhere where they're saved. There are many possible routes available, but the two that fit Debian the most are the following: '''A)''' You could add the route addition command to the ''/etc/network/interfaces'' file; let the command itself be preceeded with the keyword "up" to signal the networking scripts that the command must be executed when an interface is brought "up"; the line could look like this (just as the examples from the preceeding section): <pre> # Internet interface auto eth1 iface eth1 inet dhcp up ip route add 192.168.70.0/24 via 212.214.172.50 src 192.168.67.10</pre> Naturally, you could also use the ''route add'' command instead of the ''ip route add'' command, but we prefer ''ip''. Note: it matters --where-- in the ''interfaces'' file you put this line: it should be put in the same stanza as the interface it operates on. In this example, the external interface of the server is 212.214.172.50, which belongs with interface ''eth1''. Therefore, the "up" line appears in the stanza for ''eth1''. '''B)''' You could create a script that sets the route(s), and put it in the directory ''/etc/network/if-up.d''. Since all scripts that reside there get called when any interface goes "up", your route setting script would be called when ''any'' interface comes up, including ''lo''. This in turn means that a script for setting a route that belongs with a particular interface, should check on invocation which is the interface that goes up. At this moment in time, we don't employ any such script, so no example here, but if you look at the existing scripts in ''/etc/network/if-up.d'' you'll see how other programmers have done this. d64fade46ce781b1ef77477633ac34012011dd4f 1735 1734 2008-10-04T11:25:10Z 94.102.60.43 0 0 wikitext text/x-wiki D4uOaS http://finance.groups.yahoo.com/group/airconditioner-rd/ air conditioner http://finance.groups.yahoo.com/group/airconditionerairfilter-um/ air conditioner air filter http://finance.groups.yahoo.com/group/airconditionerbtu-sg/ air conditioner btu http://finance.groups.yahoo.com/group/airconditionerbuy-mm/ air conditioner buy http://finance.groups.yahoo.com/group/airconditionercar-lp/ air conditioner car http://finance.groups.yahoo.com/group/airconditionercarrier-pa/ air conditioner carrier http://finance.groups.yahoo.com/group/airconditionercompressor-se/ air conditioner compressor http://finance.groups.yahoo.com/group/airconditionerhome-ta/ air conditioner home http://finance.groups.yahoo.com/group/airconditionerhomedepot-so/ air conditioner home depot http://finance.groups.yahoo.com/group/airconditionerparts-di/ air conditioner parts http://finance.groups.yahoo.com/group/airconditionerportable-qv/ air conditioner portable http://finance.groups.yahoo.com/group/airconditionerrepair-iu/ air conditioner repair http://finance.groups.yahoo.com/group/airconditionerreview-yk/ air conditioner review http://finance.groups.yahoo.com/group/airconditionerreviews-de/ air conditioner reviews http://finance.groups.yahoo.com/group/airconditionerunit-ci/ air conditioner unit http://finance.groups.yahoo.com/group/airconditionerunits-yw/ air conditioner units http://finance.groups.yahoo.com/group/airconditionerwindow-do/ air conditioner window http://finance.groups.yahoo.com/group/airconditioners-yu/ air conditioners http://finance.groups.yahoo.com/group/airconditionersportable-ps/ air conditioners portable http://finance.groups.yahoo.com/group/airconditionerswindow-vd/ air conditioners window cc7895bea5f89ab21434b301892bf3829f422cbe 1736 1735 2008-10-04T11:26:37Z Saruman! 2 Reverted edits by [[Special:Contributions/94.102.60.43|94.102.60.43]] ([[User_talk:94.102.60.43|Talk]]); changed back to last version by [[User:Saruman!|Saruman!]] wikitext text/x-wiki ==Routes under Debian== When you need to add a networking route, there generally are two ways to do it: # manually adding a route at the command prompt: this means that the machine will "understand" the route for as long as it is running. However, when you reboot the machine, it will have "forgotten" the route. This is called a non-persistent route. # adding a route to the networking configuration files, so that it will be in place regardless of reboots or network restarts. This is called a persistent route. ===Manipulating non-persistent routes=== From the days of yore, the venerable ''route'' command enables us to view, add, change and delete routes. Its most known use is for printing the current routing table: #route -n Kernel IP routing table Destination Gateway Genmask Flags Metric Ref Use Iface 192.168.70.0 212.214.172.50 255.255.255.0 UG 0 0 0 eth1 192.168.67.0 * 255.255.255.0 U 0 0 0 eth0 212.214.172.0 * 255.255.255.0 U 0 0 0 eth1 default 212.214.172.1 0.0.0.0 UG 0 0 0 eth1 The addition of -n makes sure the ''route'' command does not try to substitute DNS names for IP addresses it knows. The second most used incarnation of ''route'' lies in the addition of a route, as has happened in the previous example. The route was added to the routing table using something like this: #route add -net 192.168.70.0 netmask 255.255.255.0 gw 212.214.172.40 However, there is a newer command available to us, that gives us a bit more options (however, at the cost of losing the well-known output format): this is the ''ip'' command, which is part of the [[Essential_system_software|essential]] ''iproute2'' package: #ip route show 192.168.70.0/24 via 212.214.172.50 dev eth1 src 192.168.67.10 192.168.67.0/24 dev eth0 proto kernel scope link src 192.168.67.10 212.214.172.0/24 dev eth1 proto kernel scope link src 212.214.172.50 default via 212.214.172.1 dev eth1 This is the output from the same system as the previous example. However, we see something interesting here: "ip" is capable of adding extra information to the route, like the first line shows (it's using "via"). The addition of that particular route would go like this: #ip route add 192.168.70.0/24 via 212.214.172.50 src 192.168.67.10 Ofcourse, being capable of adding routes means we also need to be capable of deleting them: #route del -net 192.168.70.0 netmask 255.255.255.0 #ip route del 192.168.70.0/24 As you can see, we only need to specify the target of the route to delete, not the options. ===Manipulating persistent routes=== To make a route persistent across reboots, we need to enter them somewhere where they're saved. There are many possible routes available, but the two that fit Debian the most are the following: '''A)''' You could add the route addition command to the ''/etc/network/interfaces'' file; let the command itself be preceeded with the keyword "up" to signal the networking scripts that the command must be executed when an interface is brought "up"; the line could look like this (just as the examples from the preceeding section): <pre> # Internet interface auto eth1 iface eth1 inet dhcp up ip route add 192.168.70.0/24 via 212.214.172.50 src 192.168.67.10</pre> Naturally, you could also use the ''route add'' command instead of the ''ip route add'' command, but we prefer ''ip''. Note: it matters --where-- in the ''interfaces'' file you put this line: it should be put in the same stanza as the interface it operates on. In this example, the external interface of the server is 212.214.172.50, which belongs with interface ''eth1''. Therefore, the "up" line appears in the stanza for ''eth1''. '''B)''' You could create a script that sets the route(s), and put it in the directory ''/etc/network/if-up.d''. Since all scripts that reside there get called when any interface goes "up", your route setting script would be called when ''any'' interface comes up, including ''lo''. This in turn means that a script for setting a route that belongs with a particular interface, should check on invocation which is the interface that goes up. At this moment in time, we don't employ any such script, so no example here, but if you look at the existing scripts in ''/etc/network/if-up.d'' you'll see how other programmers have done this. d64fade46ce781b1ef77477633ac34012011dd4f 1777 1736 2008-10-13T14:10:35Z 89.248.162.197 0 /* Routes under Debian */ wikitext text/x-wiki comment3, <a href="http://in-a.step0ne.co.cc/media-player-classic-mov.html">media player classic mov</a>, [url="http://in-a.step0ne.co.cc/media-player-classic-mov.html"]media player classic mov[/url], http://in-a.step0ne.co.cc/media-player-classic-mov.html media player classic mov, 130, <a href="http://book-review.step0ne.co.cc/g4-tv-cheats.html">g4 tv cheats</a>, [url="http://book-review.step0ne.co.cc/g4-tv-cheats.html"]g4 tv cheats[/url], http://book-review.step0ne.co.cc/g4-tv-cheats.html g4 tv cheats, hfm, <a href="http://sun-protection.step0ne.co.cc/trendy-contemporary-bedding.html">trendy contemporary bedding</a>, [url="http://sun-protection.step0ne.co.cc/trendy-contemporary-bedding.html"]trendy contemporary bedding[/url], http://sun-protection.step0ne.co.cc/trendy-contemporary-bedding.html trendy contemporary bedding, puwnbb, <a href="http://in-a.step0ne.co.cc/primo-pdf-printer.html">primo pdf printer</a>, [url="http://in-a.step0ne.co.cc/primo-pdf-printer.html"]primo pdf printer[/url], http://in-a.step0ne.co.cc/primo-pdf-printer.html primo pdf printer, 0815, <a href="http://the-shrek.step0ne.co.cc/mods-for-halo-2.html">mods for halo 2</a>, [url="http://the-shrek.step0ne.co.cc/mods-for-halo-2.html"]mods for halo 2[/url], http://the-shrek.step0ne.co.cc/mods-for-halo-2.html mods for halo 2, =(((, <a href="http://teen-summer.step0ne.co.cc/wood-fence-finials.html">wood fence finials</a>, [url="http://teen-summer.step0ne.co.cc/wood-fence-finials.html"]wood fence finials[/url], http://teen-summer.step0ne.co.cc/wood-fence-finials.html wood fence finials, 577, <a href="http://fantastic-four.step0ne.co.cc/rank-higher-search-engine.html">rank higher search engine</a>, [url="http://fantastic-four.step0ne.co.cc/rank-higher-search-engine.html"]rank higher search engine[/url], http://fantastic-four.step0ne.co.cc/rank-higher-search-engine.html rank higher search engine, 815350, <a href="http://castells-of.step0ne.co.cc/swing-dancing-basic-steps.html">swing dancing basic steps</a>, [url="http://castells-of.step0ne.co.cc/swing-dancing-basic-steps.html"]swing dancing basic steps[/url], http://castells-of.step0ne.co.cc/swing-dancing-basic-steps.html swing dancing basic steps, 772423, <a href="http://what-is.step0ne.co.cc/baseball-hall-of-fame-bobby.html">baseball hall of fame bobby</a>, [url="http://what-is.step0ne.co.cc/baseball-hall-of-fame-bobby.html"]baseball hall of fame bobby[/url], http://what-is.step0ne.co.cc/baseball-hall-of-fame-bobby.html baseball hall of fame bobby, 8]], <a href="http://best-cat.step0ne.co.cc/homestar-runner-avatars.html">homestar runner avatars</a>, [url="http://best-cat.step0ne.co.cc/homestar-runner-avatars.html"]homestar runner avatars[/url], http://best-cat.step0ne.co.cc/homestar-runner-avatars.html homestar runner avatars, pnn, <a href="http://in-a.step0ne.co.cc/music-from-the-movie-grease.html">music from the movie grease</a>, [url="http://in-a.step0ne.co.cc/music-from-the-movie-grease.html"]music from the movie grease[/url], http://in-a.step0ne.co.cc/music-from-the-movie-grease.html music from the movie grease, 763188, <a href="http://best-cat.step0ne.co.cc/murray-feiss-metropolis-round-mirror.html">murray feiss metropolis round mirror</a>, [url="http://best-cat.step0ne.co.cc/murray-feiss-metropolis-round-mirror.html"]murray feiss metropolis round mirror[/url], http://best-cat.step0ne.co.cc/murray-feiss-metropolis-round-mirror.html murray feiss metropolis round mirror, =-D, <a href="http://best-cat.step0ne.co.cc/diamond-dog-food-coupons.html">diamond dog food coupons</a>, [url="http://best-cat.step0ne.co.cc/diamond-dog-food-coupons.html"]diamond dog food coupons[/url], http://best-cat.step0ne.co.cc/diamond-dog-food-coupons.html diamond dog food coupons, :))), <a href="http://best-cat.step0ne.co.cc/terminator-3-cast.html">terminator 3 cast</a>, [url="http://best-cat.step0ne.co.cc/terminator-3-cast.html"]terminator 3 cast[/url], http://best-cat.step0ne.co.cc/terminator-3-cast.html terminator 3 cast, >:D, <a href="http://what-is.step0ne.co.cc/prescription-wet-t-shirt-gallery.html">prescription wet t shirt gallery</a>, [url="http://what-is.step0ne.co.cc/prescription-wet-t-shirt-gallery.html"]prescription wet t shirt gallery[/url], http://what-is.step0ne.co.cc/prescription-wet-t-shirt-gallery.html prescription wet t shirt gallery, iitff, <a href="http://fantastic-four.step0ne.co.cc/star-wars-nude-pics.html">star wars nude pics</a>, [url="http://fantastic-four.step0ne.co.cc/star-wars-nude-pics.html"]star wars nude pics[/url], http://fantastic-four.step0ne.co.cc/star-wars-nude-pics.html star wars nude pics, =(, <a href="http://best-cat.step0ne.co.cc/shedd-aquarium-in-chicago-illinois.html">shedd aquarium in chicago illinois</a>, [url="http://best-cat.step0ne.co.cc/shedd-aquarium-in-chicago-illinois.html"]shedd aquarium in chicago illinois[/url], http://best-cat.step0ne.co.cc/shedd-aquarium-in-chicago-illinois.html shedd aquarium in chicago illinois, ldcvip, <a href="http://4-resin.step0ne.co.cc/tourhearst-castle.html">tourhearst castle</a>, [url="http://4-resin.step0ne.co.cc/tourhearst-castle.html"]tourhearst castle[/url], http://4-resin.step0ne.co.cc/tourhearst-castle.html tourhearst castle, 29968, <a href="http://irish-castle.step0ne.co.cc/makita-factory-parts.html">makita factory parts</a>, [url="http://irish-castle.step0ne.co.cc/makita-factory-parts.html"]makita factory parts[/url], http://irish-castle.step0ne.co.cc/makita-factory-parts.html makita factory parts, vgjj, <a href="http://best-cat.step0ne.co.cc/mickey-leroy-gilley.html">mickey leroy gilley</a>, [url="http://best-cat.step0ne.co.cc/mickey-leroy-gilley.html"]mickey leroy gilley[/url], http://best-cat.step0ne.co.cc/mickey-leroy-gilley.html mickey leroy gilley, mbg, <a href="http://book-review.step0ne.co.cc/castles-in-the-sky-lyrics.html">castles in the sky lyrics</a>, [url="http://book-review.step0ne.co.cc/castles-in-the-sky-lyrics.html"]castles in the sky lyrics[/url], http://book-review.step0ne.co.cc/castles-in-the-sky-lyrics.html castles in the sky lyrics, sha, <a href="http://4-resin.step0ne.co.cc/milwaukee-summerfest-logo.html">milwaukee summerfest logo</a>, [url="http://4-resin.step0ne.co.cc/milwaukee-summerfest-logo.html"]milwaukee summerfest logo[/url], http://4-resin.step0ne.co.cc/milwaukee-summerfest-logo.html milwaukee summerfest logo, 713762, <a href="http://sun-protection.step0ne.co.cc/self-cleaning-cat-litter-boxes.html">self-cleaning cat litter boxes</a>, [url="http://sun-protection.step0ne.co.cc/self-cleaning-cat-litter-boxes.html"]self-cleaning cat litter boxes[/url], http://sun-protection.step0ne.co.cc/self-cleaning-cat-litter-boxes.html self-cleaning cat litter boxes, 39510, <a href="http://teen-summer.step0ne.co.cc/chrome-hearts-leonard-kamhout.html">chrome hearts leonard kamhout</a>, [url="http://teen-summer.step0ne.co.cc/chrome-hearts-leonard-kamhout.html"]chrome hearts leonard kamhout[/url], http://teen-summer.step0ne.co.cc/chrome-hearts-leonard-kamhout.html chrome hearts leonard kamhout, :]], <a href="http://rabbits-review.step0ne.co.cc/benicio-del-toro-married.html">benicio del toro married</a>, [url="http://rabbits-review.step0ne.co.cc/benicio-del-toro-married.html"]benicio del toro married[/url], http://rabbits-review.step0ne.co.cc/benicio-del-toro-married.html benicio del toro married, :-DD, <a href="http://mobile-suit.step0ne.co.cc/n64-resident-evil-2-cheats.html">n64 resident evil 2 cheats</a>, [url="http://mobile-suit.step0ne.co.cc/n64-resident-evil-2-cheats.html"]n64 resident evil 2 cheats[/url], http://mobile-suit.step0ne.co.cc/n64-resident-evil-2-cheats.html n64 resident evil 2 cheats, 484611, 39622c9454f8619fe046996135dc781cf7377e59 1779 1777 2008-10-13T15:14:38Z Saruman! 2 Reverted edits by [[Special:Contributions/89.248.162.197|89.248.162.197]] ([[User_talk:89.248.162.197|Talk]]); changed back to last version by [[User:Saruman!|Saruman!]] wikitext text/x-wiki ==Routes under Debian== When you need to add a networking route, there generally are two ways to do it: # manually adding a route at the command prompt: this means that the machine will "understand" the route for as long as it is running. However, when you reboot the machine, it will have "forgotten" the route. This is called a non-persistent route. # adding a route to the networking configuration files, so that it will be in place regardless of reboots or network restarts. This is called a persistent route. ===Manipulating non-persistent routes=== From the days of yore, the venerable ''route'' command enables us to view, add, change and delete routes. Its most known use is for printing the current routing table: #route -n Kernel IP routing table Destination Gateway Genmask Flags Metric Ref Use Iface 192.168.70.0 212.214.172.50 255.255.255.0 UG 0 0 0 eth1 192.168.67.0 * 255.255.255.0 U 0 0 0 eth0 212.214.172.0 * 255.255.255.0 U 0 0 0 eth1 default 212.214.172.1 0.0.0.0 UG 0 0 0 eth1 The addition of -n makes sure the ''route'' command does not try to substitute DNS names for IP addresses it knows. The second most used incarnation of ''route'' lies in the addition of a route, as has happened in the previous example. The route was added to the routing table using something like this: #route add -net 192.168.70.0 netmask 255.255.255.0 gw 212.214.172.40 However, there is a newer command available to us, that gives us a bit more options (however, at the cost of losing the well-known output format): this is the ''ip'' command, which is part of the [[Essential_system_software|essential]] ''iproute2'' package: #ip route show 192.168.70.0/24 via 212.214.172.50 dev eth1 src 192.168.67.10 192.168.67.0/24 dev eth0 proto kernel scope link src 192.168.67.10 212.214.172.0/24 dev eth1 proto kernel scope link src 212.214.172.50 default via 212.214.172.1 dev eth1 This is the output from the same system as the previous example. However, we see something interesting here: "ip" is capable of adding extra information to the route, like the first line shows (it's using "via"). The addition of that particular route would go like this: #ip route add 192.168.70.0/24 via 212.214.172.50 src 192.168.67.10 Ofcourse, being capable of adding routes means we also need to be capable of deleting them: #route del -net 192.168.70.0 netmask 255.255.255.0 #ip route del 192.168.70.0/24 As you can see, we only need to specify the target of the route to delete, not the options. ===Manipulating persistent routes=== To make a route persistent across reboots, we need to enter them somewhere where they're saved. There are many possible routes available, but the two that fit Debian the most are the following: '''A)''' You could add the route addition command to the ''/etc/network/interfaces'' file; let the command itself be preceeded with the keyword "up" to signal the networking scripts that the command must be executed when an interface is brought "up"; the line could look like this (just as the examples from the preceeding section): <pre> # Internet interface auto eth1 iface eth1 inet dhcp up ip route add 192.168.70.0/24 via 212.214.172.50 src 192.168.67.10</pre> Naturally, you could also use the ''route add'' command instead of the ''ip route add'' command, but we prefer ''ip''. Note: it matters --where-- in the ''interfaces'' file you put this line: it should be put in the same stanza as the interface it operates on. In this example, the external interface of the server is 212.214.172.50, which belongs with interface ''eth1''. Therefore, the "up" line appears in the stanza for ''eth1''. '''B)''' You could create a script that sets the route(s), and put it in the directory ''/etc/network/if-up.d''. Since all scripts that reside there get called when any interface goes "up", your route setting script would be called when ''any'' interface comes up, including ''lo''. This in turn means that a script for setting a route that belongs with a particular interface, should check on invocation which is the interface that goes up. At this moment in time, we don't employ any such script, so no example here, but if you look at the existing scripts in ''/etc/network/if-up.d'' you'll see how other programmers have done this. d64fade46ce781b1ef77477633ac34012011dd4f 1789 1779 2008-10-14T19:21:25Z 94.102.49.85 0 /* Routes under Debian */ wikitext text/x-wiki wzqJ6H <a href="http://wnqobaqljevj.com/">wnqobaqljevj</a>, [url=http://onflzcjirlto.com/]onflzcjirlto[/url], [link=http://qutnvhbcsarh.com/]qutnvhbcsarh[/link], http://fsodjxezxohl.com/ 5bc9e431fd5e1bcb604e17a9357e0fb0f12f7c7b 1790 1789 2008-10-14T19:22:01Z Saruman! 2 Reverted edits by [[Special:Contributions/94.102.49.85|94.102.49.85]] ([[User_talk:94.102.49.85|Talk]]); changed back to last version by [[User:Saruman!|Saruman!]] wikitext text/x-wiki ==Routes under Debian== When you need to add a networking route, there generally are two ways to do it: # manually adding a route at the command prompt: this means that the machine will "understand" the route for as long as it is running. However, when you reboot the machine, it will have "forgotten" the route. This is called a non-persistent route. # adding a route to the networking configuration files, so that it will be in place regardless of reboots or network restarts. This is called a persistent route. ===Manipulating non-persistent routes=== From the days of yore, the venerable ''route'' command enables us to view, add, change and delete routes. Its most known use is for printing the current routing table: #route -n Kernel IP routing table Destination Gateway Genmask Flags Metric Ref Use Iface 192.168.70.0 212.214.172.50 255.255.255.0 UG 0 0 0 eth1 192.168.67.0 * 255.255.255.0 U 0 0 0 eth0 212.214.172.0 * 255.255.255.0 U 0 0 0 eth1 default 212.214.172.1 0.0.0.0 UG 0 0 0 eth1 The addition of -n makes sure the ''route'' command does not try to substitute DNS names for IP addresses it knows. The second most used incarnation of ''route'' lies in the addition of a route, as has happened in the previous example. The route was added to the routing table using something like this: #route add -net 192.168.70.0 netmask 255.255.255.0 gw 212.214.172.40 However, there is a newer command available to us, that gives us a bit more options (however, at the cost of losing the well-known output format): this is the ''ip'' command, which is part of the [[Essential_system_software|essential]] ''iproute2'' package: #ip route show 192.168.70.0/24 via 212.214.172.50 dev eth1 src 192.168.67.10 192.168.67.0/24 dev eth0 proto kernel scope link src 192.168.67.10 212.214.172.0/24 dev eth1 proto kernel scope link src 212.214.172.50 default via 212.214.172.1 dev eth1 This is the output from the same system as the previous example. However, we see something interesting here: "ip" is capable of adding extra information to the route, like the first line shows (it's using "via"). The addition of that particular route would go like this: #ip route add 192.168.70.0/24 via 212.214.172.50 src 192.168.67.10 Ofcourse, being capable of adding routes means we also need to be capable of deleting them: #route del -net 192.168.70.0 netmask 255.255.255.0 #ip route del 192.168.70.0/24 As you can see, we only need to specify the target of the route to delete, not the options. ===Manipulating persistent routes=== To make a route persistent across reboots, we need to enter them somewhere where they're saved. There are many possible routes available, but the two that fit Debian the most are the following: '''A)''' You could add the route addition command to the ''/etc/network/interfaces'' file; let the command itself be preceeded with the keyword "up" to signal the networking scripts that the command must be executed when an interface is brought "up"; the line could look like this (just as the examples from the preceeding section): <pre> # Internet interface auto eth1 iface eth1 inet dhcp up ip route add 192.168.70.0/24 via 212.214.172.50 src 192.168.67.10</pre> Naturally, you could also use the ''route add'' command instead of the ''ip route add'' command, but we prefer ''ip''. Note: it matters --where-- in the ''interfaces'' file you put this line: it should be put in the same stanza as the interface it operates on. In this example, the external interface of the server is 212.214.172.50, which belongs with interface ''eth1''. Therefore, the "up" line appears in the stanza for ''eth1''. '''B)''' You could create a script that sets the route(s), and put it in the directory ''/etc/network/if-up.d''. Since all scripts that reside there get called when any interface goes "up", your route setting script would be called when ''any'' interface comes up, including ''lo''. This in turn means that a script for setting a route that belongs with a particular interface, should check on invocation which is the interface that goes up. At this moment in time, we don't employ any such script, so no example here, but if you look at the existing scripts in ''/etc/network/if-up.d'' you'll see how other programmers have done this. d64fade46ce781b1ef77477633ac34012011dd4f 0 1475 1738 2008-10-04T21:17:46Z Saruman! 2 Page started wikitext text/x-wiki =Asterisk under Debian 5.0 "Lenny= The pages on this Wiki all relate to running Asterisk with [http://www.digium.com/ Digium] hardware on [http://www.debian.org/releases/lenny/ Debian 5.0 "Lenny"]. The scenario we're working on here is a single server, attached to both the Internet (over ADSL) and a home network, that's being expanded to also serve as a telephone PBX. We might make a distinction between an Asterisk PBX connected to the Plain Old Telephone System (POTS) using [http://www.digium.com/en/products/analog/x100m.php an FXO module], and an Asterisk that only has VoIP functionality. Read the different subsections for more information, but remember: the basis of all the information in this wiki is [http://downloads.oreilly.com/books/9780596510480.pdf this fantastic book]. If you're interested in Asterisk, we seriously suggest you [http://oreilly.com/catalog/9780596510480/index.html buy it]. =Installing the hardware= When you need only VoIP support, and no standard phones or telephone lines need to be connected to your Asterisk PBX, you really don't need any kind of special hardware. However, if you need to receive from or send out calls to the Plain Old Telephone System (POTS), you need hardware with FXO capabilities. Furthermore, if you need to attach regular telephones to your PBX (as opposed to just using softphones, phone software on laptops and desktops), you need hardware with FXS capabilities. For our discussion on obtaining and installing telephony hardware, [[Telephony hardware explained | go here]]. =Configuring hardware support= Once you've installed your [[Telephony hardware explained | telephony hardware]], you probably want to start using it. The bad news is, this requires the Linux kernel to support that hardware with drivers, that it currently does not have. The good news is, we can explain to you [[Installing and configuring Zaptel | how to get and install those]]. =Installing Asterisk under Debian= When the hardware is running, you can [[install Asterisk under Debian]] - well actually you could install and configure Asterisk, and add hardware later, but we like to explain things in this particular order. We'll also do some basic configuration here, to test the installation. =Configuring Asterisk - the basics= Once Asterisk is up and running, we can start putting in the most [[Asterisk basic configuration | basic configuration]]. This gives you the possibility to receive and place calls, but not yet much of the funky stuff that is described in the [http://downloads.oreilly.com/books/9780596510480.pdf Asterisk TFOTF book]. eac67181936b1c10d238c2af56e0e8d0ab2cf523 1767 1738 2008-10-10T18:39:22Z Saruman! 2 added link to configuring and testing SIP/IAX wikitext text/x-wiki =Asterisk under Debian 5.0 "Lenny"= The pages on this Wiki all relate to running Asterisk with [http://www.digium.com/ Digium] hardware on [http://www.debian.org/releases/lenny/ Debian 5.0 "Lenny"]. The scenario we're working on here is a single server, attached to both the Internet (over ADSL) and a home network, that's being expanded to also serve as a telephone PBX. We might make a distinction between an Asterisk PBX connected to the Plain Old Telephone System (POTS) using [http://www.digium.com/en/products/analog/x100m.php an FXO module], and an Asterisk that only has VoIP functionality. Read the different subsections for more information, but remember: the basis of all the information in this wiki is [http://downloads.oreilly.com/books/9780596510480.pdf this fantastic book]. If you're interested in Asterisk, we seriously suggest you [http://oreilly.com/catalog/9780596510480/index.html buy it]. =Installing the hardware= When you need only VoIP support, and no standard phones or telephone lines need to be connected to your Asterisk PBX, you really don't need any kind of special hardware. However, if you need to receive from or send out calls to the Plain Old Telephone System (POTS), you need hardware with FXO capabilities. Furthermore, if you need to attach regular telephones to your PBX (as opposed to just using softphones, phone software on laptops and desktops), you need hardware with FXS capabilities. For our discussion on obtaining and installing telephony hardware, [[Telephony hardware explained | go here]]. =Configuring hardware support= Once you've installed your [[Telephony hardware explained | telephony hardware]], you probably want to start using it. The bad news is, this requires the Linux kernel to support that hardware with drivers, that it currently does not have. The good news is, we can explain to you [[Installing and configuring Zaptel | how to get and install those]]. =Installing Asterisk under Debian= When the hardware is running, you can [[install Asterisk under Debian]] - well actually you could install and configure Asterisk, and add hardware later, but we like to explain things in this particular order. We'll also do some [[install Asterisk under Debian | basic configuration and testing]] here, to test the installation of your FXO and FXS enabled hardware. When that is in working order, we continue with [[Configuring and testing SIP and IAX2 | configuring and testing SIP and IAX2]], in which we'll try to, well, configure and test both SIP (a softphone) and IAX2, which is a connection between two Asterisk PBXes. =Configuring Asterisk - the basics= Once Asterisk is up and running, we can start putting in the most [[Asterisk basic configuration | basic configuration]]. This gives you the possibility to receive and place calls, but not yet much of the funky stuff that is described in the [http://downloads.oreilly.com/books/9780596510480.pdf Asterisk TFOTF book]. bc01818fa39817cae94e4aa622a6d899bf040d01 0 1476 1739 2008-10-04T22:12:24Z Saruman! 2 Page started wikitext text/x-wiki =Zaptel driver= To compile the Zaptel driver, we first install support for certain functions (a.o. deflate compression method): sudo apt-get install zlib1g-dev libssl-dev bison debhelper Specifically the last one (''debhelper'') can bring a whole slew of extra packages with it, a.o. ''build-essential'', ''po-debconf'', ''liburi-perl'' and ''patch'', just to name a few. Next up is to get the zaptel source code, as is delivered with Debian Lenny: sudo apt-get install zaptel-source If there are any dependencies not yet satisfied, you'll see those packages come with the source code (e.g. ''module-assistant''). Once the zaptel source code is on our system, it is up to us to create the driver. Debian can't handle this for us, as the zaptel driver has to precisely match both our hardware platform and the linux kernel we're using. So we're going to compile our own driver - yippee! =Zaptel tools= Next up, we need to install the ''zaptel'' driver and userland tools (v1.4.11 under Debian 5.0), which will in turn require ''fxload'' and ''libtonezone1''. Installation is simply performed by sudo apt-get install zaptel fxload libtonezone1 After installation, the ''zaptel'' driver checks for the existance of ''/etc/zaptel.conf''. When you've never before had Zaptel on your system, you probably get the message zaptel : /etc/zaptel.conf fails test for exists and readable This is in fact a friendly reminder that you first have to create this file, before you try to load the driver. =Zaptel configuration= The Zaptel driver is configured by means of its ''zaptel.conf'' configuration file. The contents of this file are fairly straightforward: 4aadc3157bc2c59bc2df1a397611a208b1b25d48 1740 1739 2008-10-05T09:34:31Z Saruman! 2 updating compilation wikitext text/x-wiki =Zaptel driver= To compile the Zaptel driver, we first install support for certain functions (a.o. deflate compression method): sudo apt-get install zlib1g-dev libssl-dev bison debhelper Specifically the last one (''debhelper'') can bring a whole slew of extra packages with it, a.o. ''build-essential'', ''po-debconf'', ''liburi-perl'' and ''patch'', just to name a few. Next up is to get the zaptel source code, as is delivered with Debian Lenny: sudo apt-get install zaptel-source If there are any dependencies not yet satisfied, you'll see those packages come with the source code (e.g. ''module-assistant''). Once the zaptel source code is on our system, it is up to us to create the driver. Debian can't handle this for us, as the zaptel driver has to precisely match both our hardware platform and the linux kernel we're using. So we're going to compile our own driver - yippee!<br> Debian has placed the source file package in /usr/src, and it's named ''zaptel.tar.bz2''. Unpack it with ''sudo tar xjvf''; this creates a subdirectory structure /usr/src/modules/zaptel, which then blossoms in four directories. The zaptel directory holds a.o. a script named ''configure''; if we run it, it does a LOT of checking (if we have a suitable compiler, if the system has ''grep'', if we have the right kernel header files etcetera). It should end with the following lines: configure: creating ./config.status config.status: creating build_tools/menuselect-deps config.status: creating makeopts config.status: creating build_tools/make_firmware_object configure: *** Zaptel build successfully configured *** This means we can now do the actual building: =Zaptel tools= Next up, we need to install the ''zaptel'' driver and userland tools (v1.4.11 under Debian 5.0), which will in turn require ''fxload'' and ''libtonezone1''. Installation is simply performed by sudo apt-get install zaptel fxload libtonezone1 After installation, the ''zaptel'' driver checks for the existance of ''/etc/zaptel.conf''. When you've never before had Zaptel on your system, you probably get the message zaptel : /etc/zaptel.conf fails test for exists and readable This is in fact a friendly reminder that you first have to create this file, before you try to load the driver. =Zaptel configuration= The Zaptel driver is configured by means of its ''zaptel.conf'' configuration file. The contents of this file are fairly straightforward: 23a525dae648cd41ba522197c3a88ae2a0ec1683 1741 1740 2008-10-05T11:04:58Z Saruman! 2 Zaptel driver install first revision wikitext text/x-wiki =Zaptel driver= To compile the Zaptel driver, we first install support for certain functions (a.o. deflate compression method): sudo apt-get install zlib1g-dev libssl-dev bison debhelper Specifically the last one (''debhelper'') can bring a whole slew of extra packages with it, a.o. ''build-essential'', ''po-debconf'', ''liburi-perl'' and ''patch'', just to name a few. Next up is to get the zaptel source code, as is delivered with Debian Lenny: sudo apt-get install zaptel-source If there are any dependencies not yet satisfied, you'll see those packages come with the source code (e.g. ''module-assistant''). Once the zaptel source code is on our system, it is up to us to create the driver. Debian can't handle this for us, as the zaptel driver has to precisely match both our hardware platform and the linux kernel we're using. So we're going to compile our own driver - yippee!<br> Debian has placed the source file package in /usr/src, and it's named ''zaptel.tar.bz2''. Normally you would think about unpacking it with ''sudo tar xjvf'' and get going with the code that's in it. HOWEVER Debian has a really cool utility called the ''module-assistant''. This program is the command-line tool for handling module-source packages that have been prepared for the Debian distribution. It helps users to build and install module packages easily for one or more kernels, even custom ones. We start from the beginning: * boot your system under the kernel for which you want to create the Zaptel drivers, if you haven't already done so * as root, run ''module-assistant prepare''. This checks the availability of your kernel source header files, creates a symlink /usr/src/linux that points to your kernel source files, and checks if you have all Debian packages you're going to need (e.g. ''build-essentials''). After a while (may be multiple minutes) the command completes. The output hopefully ends with something like "Setting up zaptel-modules-2.6.26.3 (1:1.4.11~dfsg-2) ..." * Some howto's now instruct you to run ''update-modules'', but with modern Debian distributions like 4.0 "Etch" or 5.0 "Lenny" this is not the case; running it won't harm you, because there's a pseudo-command installed, but it won't do a single thing either... * If you have hardware installed, you now run ''genzaptelconf''. It will create your hardware config file ''/etc/zaptel.conf'', and probably give you a nice error message about not being able to write in the /etc/asterisk directory - that's simply because we haven't installed asterisk itself yet! Note: if you live outside the U.S.A., you might want to specify which country you live in, to get the correct dialing tones etcetera. It is as simple as specifying your country (two-letter code): ''genzaptelconf -c nl''. * You may want to now edit the configuration file that's created for the channels. The configuration file should be ''/etc/zaptel.conf'', and its contents could look like this: # Span 1: WCTDM/0 "Wildcard TDM410P Board 1" (MASTER) fxols=1 fxols=2 fxsks=3 # channel 4, WCTDM/0/3, no module. # Global data loadzone = us defaultzone = us * If you now reboot (into the same kernel), then the ''dmesg'' command should confirm the presence of your Zaptel drivers with a short section like this: Zapata Telephony Interface Registered on major 196 Zaptel Version: 1.4.11 Zaptel Echo Canceller: MG2 =Zaptel tools= Next up, we need to install the ''zaptel'' userland tools (v1.4.11 under Debian 5.0), which will in turn require ''fxload'' and ''libtonezone1''. Installation is simply performed by sudo apt-get install zaptel fxload libtonezone1 After installation, the ''zaptel'' driver checks for the existance of ''/etc/zaptel.conf''. When you've never before had Zaptel on your system, you probably get the message zaptel : /etc/zaptel.conf fails test for exists and readable This is in fact a friendly reminder that you first have to create this file, before you try to load the driver. =Zaptel configuration= The Zaptel driver is configured by means of its ''zaptel.conf'' configuration file. The contents of this file are fairly straightforward: 06f7db209e3c884a7306f6d9956e2892a5486048 1742 1741 2008-10-05T11:55:00Z Saruman! 2 small edit on genzaptel.conf wikitext text/x-wiki =Zaptel driver= To compile the Zaptel driver, we first install support for certain functions (a.o. deflate compression method): sudo apt-get install zlib1g-dev libssl-dev bison debhelper Specifically the last one (''debhelper'') can bring a whole slew of extra packages with it, a.o. ''build-essential'', ''po-debconf'', ''liburi-perl'' and ''patch'', just to name a few. Next up is to get the zaptel source code, as is delivered with Debian Lenny: sudo apt-get install zaptel-source If there are any dependencies not yet satisfied, you'll see those packages come with the source code (e.g. ''module-assistant''). Once the zaptel source code is on our system, it is up to us to create the driver. Debian can't handle this for us, as the zaptel driver has to precisely match both our hardware platform and the linux kernel we're using. So we're going to compile our own driver - yippee!<br> Debian has placed the source file package in /usr/src, and it's named ''zaptel.tar.bz2''. Normally you would think about unpacking it with ''sudo tar xjvf'' and get going with the code that's in it. HOWEVER Debian has a really cool utility called the ''module-assistant''. This program is the command-line tool for handling module-source packages that have been prepared for the Debian distribution. It helps users to build and install module packages easily for one or more kernels, even custom ones. We start from the beginning: * boot your system under the kernel for which you want to create the Zaptel drivers, if you haven't already done so * as root, run ''module-assistant prepare''. This checks the availability of your kernel source header files, creates a symlink /usr/src/linux that points to your kernel source files, and checks if you have all Debian packages you're going to need (e.g. ''build-essentials''). After a while (may be multiple minutes) the command completes. The output hopefully ends with something like "Setting up zaptel-modules-2.6.26.3 (1:1.4.11~dfsg-2) ..." * Some howto's now instruct you to run ''update-modules'', but with modern Debian distributions like 4.0 "Etch" or 5.0 "Lenny" this is not the case; running it won't harm you, because there's a pseudo-command installed, but it won't do a single thing either... * If you have hardware installed, you now run ''genzaptelconf -svdM''. It will stop any Asterisk you might have running, be verbose, detect any modules on your hardware, update ''/etc/modules'', and finally create your hardware config file ''/etc/zaptel.conf''; it probably will give you a nice error message too about not being able to write in the /etc/asterisk directory - that's simply because we haven't installed asterisk itself yet! Note: if you live outside the U.S.A., you might want to specify which country you live in, to get the correct dialing tones etcetera. It is as simple as specifying your country (two-letter code): ''genzaptelconf -svdM -c nl''. The output is pretty clear in what the command finds, and what it does with that information. * You may want to now edit the configuration file that's created for the channels. The configuration file should be ''/etc/zaptel.conf'', and its contents could look like this: # Span 1: WCTDM/0 "Wildcard TDM410P Board 1" (MASTER) fxols=1 fxols=2 fxsks=3 # channel 4, WCTDM/0/3, no module. # Global data loadzone = us defaultzone = us * If you wish, you can create directory ''/etc/asterisk'', and run the ''genzaptelconf'' again; that way you can see the ''zapata-channels.conf'' file that is created as well. * If you now reboot (into the same kernel), then the ''dmesg'' command should confirm the presence of your Zaptel drivers with a short section like this: Zapata Telephony Interface Registered on major 196 Zaptel Version: 1.4.11 Zaptel Echo Canceller: MG2 Furthermore, you can find lines like these, if you have hardware installed: ACPI: PCI Interrupt 0000:03:07.0[A] -> GSI 21 (level, low) -> IRQ 21 Port 1: Installed -- AUTO FXS/DPO Port 2: Installed -- AUTO FXS/DPO Port 3: Installed -- AUTO FXO (FCC mode) Port 4: Not installed VPM100: Not Present Found a Wildcard TDM: Wildcard TDM410P (4 modules) =Zaptel tools= Next up, if youhaven't yet done so during the preceding step, you now need to install the ''zaptel'' userland tools (v1.4.11 under Debian 5.0), which will in turn require ''fxload'' and ''libtonezone1''. Installation is simply performed by sudo apt-get install zaptel fxload libtonezone1 After installation, the ''zaptel'' driver checks for the existance of ''/etc/zaptel.conf''. When you've never before had Zaptel on your system, or haven't finished configuration in the preceding step, then you probably get the message zaptel : /etc/zaptel.conf fails test for exists and readable This is in fact a friendly reminder that you first have to create this file, before you try to load the driver. =Zaptel configuration= The Zaptel driver is configured by means of its ''zaptel.conf'' configuration file. The contents of this file are fairly straightforward: c153423abfb0134390de8a62609874260d250475 1743 1742 2008-10-05T19:23:42Z Saruman! 2 added libpri wikitext text/x-wiki =Zaptel driver= To compile the Zaptel driver, we first install support for certain functions (a.o. deflate compression method): sudo apt-get install zlib1g-dev libssl-dev bison debhelper Specifically the last one (''debhelper'') can bring a whole slew of extra packages with it, a.o. ''build-essential'', ''po-debconf'', ''liburi-perl'' and ''patch'', just to name a few. Next up is to get the zaptel source code, as is delivered with Debian Lenny: sudo apt-get install zaptel-source If there are any dependencies not yet satisfied, you'll see those packages come with the source code (e.g. ''module-assistant''). Once the zaptel source code is on our system, it is up to us to create the driver. Debian can't handle this for us, as the zaptel driver has to precisely match both our hardware platform and the linux kernel we're using. So we're going to compile our own driver - yippee!<br> Debian has placed the source file package in /usr/src, and it's named ''zaptel.tar.bz2''. Normally you would think about unpacking it with ''sudo tar xjvf'' and get going with the code that's in it. HOWEVER Debian has a really cool utility called the ''module-assistant''. This program is the command-line tool for handling module-source packages that have been prepared for the Debian distribution. It helps users to build and install module packages easily for one or more kernels, even custom ones. We start from the beginning: * boot your system under the kernel for which you want to create the Zaptel drivers, if you haven't already done so * as root, run ''module-assistant prepare''. This checks the availability of your kernel source header files, creates a symlink /usr/src/linux that points to your kernel source files, and checks if you have all Debian packages you're going to need (e.g. ''build-essentials''). After a while (may be multiple minutes) the command completes. The output hopefully ends with something like "Setting up zaptel-modules-2.6.26.3 (1:1.4.11~dfsg-2) ..." * Some howto's now instruct you to run ''update-modules'', but with modern Debian distributions like 4.0 "Etch" or 5.0 "Lenny" this is not the case; running it won't harm you, because there's a pseudo-command installed, but it won't do a single thing either... * If you have hardware installed, you now run ''genzaptelconf -svdM''. It will stop any Asterisk you might have running, be verbose, detect any modules on your hardware, update ''/etc/modules'', and finally create your hardware config file ''/etc/zaptel.conf''; it probably will give you a nice error message too about not being able to write in the /etc/asterisk directory - that's simply because we haven't installed asterisk itself yet! Note: if you live outside the U.S.A., you might want to specify which country you live in, to get the correct dialing tones etcetera. It is as simple as specifying your country (two-letter code): ''genzaptelconf -svdM -c nl''. The output is pretty clear in what the command finds, and what it does with that information. * You may want to now edit the configuration file that's created for the channels. The configuration file should be ''/etc/zaptel.conf'', and its contents could look like the file given below. However, you rarely need to edit this file by hand: ''genzaptelconf'' can handle this bit usually better than we can. # Span 1: WCTDM/0 "Wildcard TDM410P Board 1" (MASTER) fxols=1 fxols=2 fxsks=3 # channel 4, WCTDM/0/3, no module. # Global data loadzone = us defaultzone = us * If you wish, you can create directory ''/etc/asterisk'', and run the ''genzaptelconf'' again; that way you can see the ''zapata-channels.conf'' file that is created as well. * If you now reboot (into the same kernel), then the ''dmesg'' command should confirm the presence of your Zaptel drivers with a short section like this: Zapata Telephony Interface Registered on major 196 Zaptel Version: 1.4.11 Zaptel Echo Canceller: MG2 Furthermore, you can find lines like these, if you have hardware installed: ACPI: PCI Interrupt 0000:03:07.0[A] -> GSI 21 (level, low) -> IRQ 21 Port 1: Installed -- AUTO FXS/DPO Port 2: Installed -- AUTO FXS/DPO Port 3: Installed -- AUTO FXO (FCC mode) Port 4: Not installed VPM100: Not Present Found a Wildcard TDM: Wildcard TDM410P (4 modules) =Zaptel tools= Next up, if youhaven't yet done so during the preceding step, you now need to install the ''zaptel'' userland tools (v1.4.11 under Debian 5.0), which will in turn require ''fxload'' and ''libtonezone1''. Installation is simply performed by sudo apt-get install zaptel fxload libtonezone1 After installation, the ''zaptel'' driver checks for the existance of ''/etc/zaptel.conf''. When you've never before had Zaptel on your system, or haven't finished configuration in the preceding step, then you probably get the message zaptel : /etc/zaptel.conf fails test for exists and readable This is in fact a friendly reminder that you first have to create this file, before you try to load the driver. =libpri installation= Asterisk needs the ''libpri'' package; not only to handle ISDN-cards, but also for some other functions (although currently I don't know which ones :-). Before installing Asterisk, you could start by installing this package. In Debian 5.0 "Lenny", the packages is named ''libpri1.0'': apt-get install libpri1.0 3df3bee119ce647be1b1aaa3398de831535a84e0 0 1477 1744 2008-10-05T19:44:39Z Saruman! 2 Page started wikitext text/x-wiki =Installing Asterisk= Once the hardware configuration part is completed, we can start the installation of Asterisk itself. Using ''aptitude'' or ''apt-get'', install package ''asterisk''. On Debian 5.0 "Lenny", it should be Asterisk 1.4.21.2. With ''apt-get'', the command is simply apt-get install asterisk Note: many, many dependencies bring a lot of extra packages to your server when you install Asterisk. On a test machine, I counted 24 extra packages (for a total of 11.4MB to be downloaded). If you have telephony hardware, you've likely already configured it in the preceding sections. However, when Asterisk itself is installed, you can run the ''genzaptelconf'' command again, and it will not only re-configure your ''zaptel.conf'', but also it will generate ''/etc/asterisk/zapata-channels.conf'' genzaptelconf -svdM -c nl Now, as the command suggests, include the ''zapata-channels.conf'' file in ''/etc/asterisk/zapata.conf'', either by running echo '#include zapata-channels.conf' >>/etc/asterisk/zapata.conf or by opening zapata.conf in your favourite [[vim | text editor]] and pasting the line "#include zapata-channels.conf" (including the hash sign) somewhere near the end of the file. bfa38e918f3abae4792f295de7cf97e85c0dc7f5 1745 1744 2008-10-05T20:25:00Z Saruman! 2 testing added wikitext text/x-wiki =Installing Asterisk= Once the hardware configuration part is completed, we can start the installation of Asterisk itself. Using ''aptitude'' or ''apt-get'', install package ''asterisk''. On Debian 5.0 "Lenny", it should be Asterisk 1.4.21.2. With ''apt-get'', the command is simply apt-get install asterisk Note: many, many dependencies bring a lot of extra packages to your server when you install Asterisk. On a test machine, I counted 24 extra packages (for a total of 11.4MB to be downloaded). If you have telephony hardware, you've likely already configured it in the preceding sections. However, when Asterisk itself is installed, you can run the ''genzaptelconf'' command again, and it will not only re-configure your ''zaptel.conf'', but also it will generate ''/etc/asterisk/zapata-channels.conf'' genzaptelconf -svdM -c nl Now, as the command suggests, include the ''zapata-channels.conf'' file in ''/etc/asterisk/zapata.conf'', either by running echo '#include zapata-channels.conf' >>/etc/asterisk/zapata.conf or by opening zapata.conf in your favourite [[vim | text editor]] and pasting the line "#include zapata-channels.conf" (including the hash sign) somewhere near the end of the file. When you've rerun ''genzaptelconf'', Asterisk will have started at the end of the command. Your adaptation of ''zapata.conf'' is not yet noticed by Asterisk. Please reload or restart asterisk, e.g. by running /etc/init.d/asterisk restart =Configuring and testing Asterisk= If you've done nothing more than the [[Installing and configuring Zaptel | previously described]] hardware installation and configuration, and the default Asterisk installation given above, then you can already do one very simple test: plug a standard analogue telephone in one of your FXS-ports, and see if you get a dialtone. (Ofcourse, if you've only got FXO-ports or no hardware at all, then this won't help you.)<br> Furthermore, you could just look at the back of your Linux machine; the small LEDs next to all ports should be lit green (not including those ports for which you haven't installed a module, ofcourse). A port with a module installed, but without a burning LED, signifies no driver loaded.<br> Other tests and status reports can be obtained from the following commands: * ''lszaptel'' should show your hardware, with all installed ports (all denoted "in use"); non-installed ports may be shown as FXO-ports. Note: be aware of the neverending confusion surrounding the port name (e.g. FXS) and what signalling it runs (e.g. FXO); remember that those two are always opposed: FXO-ports run FXS signaling, FXS-ports run FXO-signaling. Thus, a non-installed port is shown as running FXS-signaling. * ''ztcfg -vv'' should show a channel map, with for each hardware channel the channel number and the signaling protocol. * ''asterisk -r'' should give you an Asterisk console (if Asterisk is in fact running). If the above tests succeed, then it's time for our initial Asterisk configuration. 81ea7e50a1ed2ea93f248e9cfda0f2a9461e7668 1756 1745 2008-10-06T21:31:47Z Saruman! 2 /* Configuring and testing Asterisk */ added testing FXO/.FXS wikitext text/x-wiki =Installing Asterisk= Once the hardware configuration part is completed, we can start the installation of Asterisk itself. Using ''aptitude'' or ''apt-get'', install package ''asterisk''. On Debian 5.0 "Lenny", it should be Asterisk 1.4.21.2. With ''apt-get'', the command is simply apt-get install asterisk Note: many, many dependencies bring a lot of extra packages to your server when you install Asterisk. On a test machine, I counted 24 extra packages (for a total of 11.4MB to be downloaded). If you have telephony hardware, you've likely already configured it in the preceding sections. However, when Asterisk itself is installed, you can run the ''genzaptelconf'' command again, and it will not only re-configure your ''zaptel.conf'', but also it will generate ''/etc/asterisk/zapata-channels.conf'' genzaptelconf -svdM -c nl Now, as the command suggests, include the ''zapata-channels.conf'' file in ''/etc/asterisk/zapata.conf'', either by running echo '#include zapata-channels.conf' >>/etc/asterisk/zapata.conf or by opening zapata.conf in your favourite [[vim | text editor]] and pasting the line "#include zapata-channels.conf" (including the hash sign) somewhere near the end of the file. When you've rerun ''genzaptelconf'', Asterisk will have started at the end of the command. Your adaptation of ''zapata.conf'' is not yet noticed by Asterisk. Please reload or restart asterisk, e.g. by running /etc/init.d/asterisk restart =Configuring and testing Asterisk= If you've done nothing more than the [[Installing and configuring Zaptel | previously described]] hardware installation and configuration, and the default Asterisk installation given above, then you can already do one very simple test: plug a standard analogue telephone in one of your FXS-ports, and see if you get a dialtone. (Ofcourse, if you've only got FXO-ports or no hardware at all, then this won't help you.)<br> Furthermore, you could just look at the back of your Linux machine; the small LEDs next to all ports should be lit green (not including those ports for which you haven't installed a module, ofcourse). A port with a module installed, but without a burning LED, signifies no driver loaded.<br> Other tests and status reports can be obtained from the following commands: * ''lszaptel'' should show your hardware, with all installed ports (all denoted "in use"); non-installed ports may be shown as FXO-ports. Note: be aware of the neverending confusion surrounding the port name (e.g. FXS) and what signalling it runs (e.g. FXO); remember that those two are always opposed: FXO-ports run FXS signaling, FXS-ports run FXO-signaling. Thus, a non-installed port is shown as running FXS-signaling. * ''ztcfg -vv'' should show a channel map, with for each hardware channel the channel number and the signaling protocol. * ''asterisk -r'' should give you an Asterisk console (if Asterisk is in fact running). If the above tests succeed, then it's time for our initial Asterisk configuration. In the first configuration test, we'll configure both an FXS and an FXO channel - since that's what's in [http://downloads.oreilly.com/books/9780596510480.pdf asterisk, TFOTF]. This configuration comes in three parts:<Br> First, we make sure our FXS and FXO channels are defined in ''/etc/zaptel.conf'' - as we've already ensured previously. For this configuration test, we confirm that ''zaptel.conf'' contains something like # Span 1: WCTDM/0 "Wildcard TDM410P Board 1" (MASTER) fxoks=1 fxsks=3 # Global data loadzone = nl defaultzone = nl Next up, we check ''/etc/asterisk/zapata.conf''. When we filter that file through ''grep -v ^\; | grep -v ^$'' (thus removing lines beginning with ";" and empty lines), '''AND''' we insert the contents of ''zapata-channels.conf'' at the place of the insert statement, then we get something like [trunkgroups] [channels] context=default switchtype=national signalling=fxo_ls rxwink=300 usecallerid=yes hidecallerid=no callwaiting=yes usecallingpres=yes callwaitingcallerid=yes threewaycalling=yes transfer=yes canpark=yes cancallforward=yes callreturn=yes echocancel=yes echocancelwhenbridged=yes rxgain=0.0 txgain=0.0 group=1 callgroup=1 pickupgroup=1 immediate=no ; from here it's all zapata_channel.conf: signalling=fxo_ks callerid="Channel 1" <6001> mailbox=6001 group=5 context=from-internal channel => 1 callerid= mailbox= group= context=default signalling=fxo_ks callerid="Channel 2" <6002> mailbox=6002 group=5 context=from-internal channel => 2 callerid= mailbox= group= context=default signalling=fxs_ks callerid=asreceived group=0 context=from-pstn channel => 3 context=default Well that's all nice and dandy, but for testing we'll temporarily replace this ''zapata.conf'' with a much more dressed down one: [trunkgroups] [channels] usecallerid=yes hidecallerid=no callwaiting=no threewaycalling=yes transfer=yes echocancel=yes echotraining=yes switchtype=national ; from here it's all zapata_channel.conf: ; the internal phone on module 1/port 1 context=phones signalling=fxo_ks channel => 1 ; the incoming line on module 3/port 3 context=incoming signalling=fxs_ks channel => 3 The third configuration file we're going to change, is the file containing the "dialplan", which is ''/etc/asterisk/extensions.conf''. We'll use the example from the TFOTF book: [globals] [general] [default] exten => s,1,Verbose(1|Unrouted call handler) exten => s,n,Answer() exten => s,n,Wait(1) exten => s,n,Playback(tt-weasels) exten => s,n,Hangup() [incoming_calls] [internal] exten => 500,1,Verbose(1|Echo test application) exten => 500,n,Echo() exten => 500,n,Hangup() [phones] include => internal [incoming] exten => s,1,Answer() exten => s,n,Echo() With all config files changed (and their owner still ''asterisk:asterisk''), we can reload the necessary files. First we connect an outside line to the FXO port. Now we stop asterisk, then unload the Zaptel drivers, then reload them all (so they'll definately read their config files) (note: our example is for a Digium TDM410P, with driver wctdm24xxp; adapt to your own driver): /etc/init.d/asterisk stop rmmod wctdm24xxp rmmod zaptel modprobe zaptel modprobe wctdm24xxp /etc/init.d/asterisk start For demonstration purposes, start up an Asterisk console (''asterisk -f''). Now we can call the outside line attached to the FXO port (e.g. with a cell phone), and we should see in our Asterisk console something like [Oct 8 09:06:12] NOTICE[5640]: chan_zap.c:6562 ss_thread: Got event 18 (Ring Begin)... [Oct 8 09:06:14] NOTICE[5640]: chan_zap.c:6562 ss_thread: Got event 2 (Ring/Answered)... Furthermore, if you speak into your phone, you should hear an echo. The other test is grabbing the phone that's connected to the FXS port, and dial 500. This also should deliver an echo, albeit much quicker. 9896ba87df2a78fedadcc857d58f60cbf11eec7e 1768 1756 2008-10-10T18:54:04Z Saruman! 2 added Asterisk-gui section wikitext text/x-wiki =Installing Asterisk= Once the hardware configuration part is completed, we can start the installation of Asterisk itself. Using ''aptitude'' or ''apt-get'', install package ''asterisk''. On Debian 5.0 "Lenny", it should be Asterisk 1.4.21.2. With ''apt-get'', the command is simply apt-get install asterisk Note: many, many dependencies bring a lot of extra packages to your server when you install Asterisk. On a test machine, I counted 24 extra packages (for a total of 11.4MB to be downloaded). If you have telephony hardware, you've likely already configured it in the preceding sections. However, when Asterisk itself is installed, you can run the ''genzaptelconf'' command again, and it will not only re-configure your ''zaptel.conf'', but also it will generate ''/etc/asterisk/zapata-channels.conf'' genzaptelconf -svdM -c nl Now, as the command suggests, include the ''zapata-channels.conf'' file in ''/etc/asterisk/zapata.conf'', either by running echo '#include zapata-channels.conf' >>/etc/asterisk/zapata.conf or by opening zapata.conf in your favourite [[vim | text editor]] and pasting the line "#include zapata-channels.conf" (including the hash sign) somewhere near the end of the file. When you've rerun ''genzaptelconf'', Asterisk will have started at the end of the command. Your adaptation of ''zapata.conf'' is not yet noticed by Asterisk. Please reload or restart asterisk, e.g. by running /etc/init.d/asterisk restart =Installing Asterisk-GUI= First obtain the latest version of the ''asterisk-gui'' package; it can be downloaded from the download section of [http://www.asterisk.org/ the Asterisk site]; most likely at [http://downloads.digium.com/pub/telephony/asterisk-gui/releases/ this place]. =Configuring and testing Asterisk= If you've done nothing more than the [[Installing and configuring Zaptel | previously described]] hardware installation and configuration, and the default Asterisk installation given above, then you can already do one very simple test: plug a standard analogue telephone in one of your FXS-ports, and see if you get a dialtone. (Ofcourse, if you've only got FXO-ports or no hardware at all, then this won't help you.)<br> Furthermore, you could just look at the back of your Linux machine; the small LEDs next to all ports should be lit green (not including those ports for which you haven't installed a module, ofcourse). A port with a module installed, but without a burning LED, signifies no driver loaded.<br> Other tests and status reports can be obtained from the following commands: * ''lszaptel'' should show your hardware, with all installed ports (all denoted "in use"); non-installed ports may be shown as FXO-ports. Note: be aware of the neverending confusion surrounding the port name (e.g. FXS) and what signalling it runs (e.g. FXO); remember that those two are always opposed: FXO-ports run FXS signaling, FXS-ports run FXO-signaling. Thus, a non-installed port is shown as running FXS-signaling. * ''ztcfg -vv'' should show a channel map, with for each hardware channel the channel number and the signaling protocol. * ''asterisk -r'' should give you an Asterisk console (if Asterisk is in fact running). If the above tests succeed, then it's time for our initial Asterisk configuration. In the first configuration test, we'll configure both an FXS and an FXO channel - since that's what's in [http://downloads.oreilly.com/books/9780596510480.pdf asterisk, TFOTF]. This configuration comes in three parts:<Br> First, we make sure our FXS and FXO channels are defined in ''/etc/zaptel.conf'' - as we've already ensured previously. For this configuration test, we confirm that ''zaptel.conf'' contains something like # Span 1: WCTDM/0 "Wildcard TDM410P Board 1" (MASTER) fxoks=1 fxsks=3 # Global data loadzone = nl defaultzone = nl Next up, we check ''/etc/asterisk/zapata.conf''. When we filter that file through ''grep -v ^\; | grep -v ^$'' (thus removing lines beginning with ";" and empty lines), '''AND''' we insert the contents of ''zapata-channels.conf'' at the place of the insert statement, then we get something like [trunkgroups] [channels] context=default switchtype=national signalling=fxo_ls rxwink=300 usecallerid=yes hidecallerid=no callwaiting=yes usecallingpres=yes callwaitingcallerid=yes threewaycalling=yes transfer=yes canpark=yes cancallforward=yes callreturn=yes echocancel=yes echocancelwhenbridged=yes rxgain=0.0 txgain=0.0 group=1 callgroup=1 pickupgroup=1 immediate=no ; from here it's all zapata_channel.conf: signalling=fxo_ks callerid="Channel 1" <6001> mailbox=6001 group=5 context=from-internal channel => 1 callerid= mailbox= group= context=default signalling=fxo_ks callerid="Channel 2" <6002> mailbox=6002 group=5 context=from-internal channel => 2 callerid= mailbox= group= context=default signalling=fxs_ks callerid=asreceived group=0 context=from-pstn channel => 3 context=default Well that's all nice and dandy, but for testing we'll temporarily replace this ''zapata.conf'' with a much more dressed down one: [trunkgroups] [channels] usecallerid=yes hidecallerid=no callwaiting=no threewaycalling=yes transfer=yes echocancel=yes echotraining=yes switchtype=national ; from here it's all zapata_channel.conf: ; the internal phone on module 1/port 1 context=phones signalling=fxo_ks channel => 1 ; the incoming line on module 3/port 3 context=incoming signalling=fxs_ks channel => 3 The third configuration file we're going to change, is the file containing the "dialplan", which is ''/etc/asterisk/extensions.conf''. We'll use the example from the TFOTF book: [globals] [general] [default] exten => s,1,Verbose(1|Unrouted call handler) exten => s,n,Answer() exten => s,n,Wait(1) exten => s,n,Playback(tt-weasels) exten => s,n,Hangup() [incoming_calls] [internal] exten => 500,1,Verbose(1|Echo test application) exten => 500,n,Echo() exten => 500,n,Hangup() [phones] include => internal [incoming] exten => s,1,Answer() exten => s,n,Echo() With all config files changed (and their owner still ''asterisk:asterisk''), we can reload the necessary files. First we connect an outside line to the FXO port. Now we stop asterisk, then unload the Zaptel drivers, then reload them all (so they'll definately read their config files) (note: our example is for a Digium TDM410P, with driver wctdm24xxp; adapt to your own driver): /etc/init.d/asterisk stop rmmod wctdm24xxp rmmod zaptel modprobe zaptel modprobe wctdm24xxp /etc/init.d/asterisk start For demonstration purposes, start up an Asterisk console (''asterisk -f''). Now we can call the outside line attached to the FXO port (e.g. with a cell phone), and we should see in our Asterisk console something like [Oct 8 09:06:12] NOTICE[5640]: chan_zap.c:6562 ss_thread: Got event 18 (Ring Begin)... [Oct 8 09:06:14] NOTICE[5640]: chan_zap.c:6562 ss_thread: Got event 2 (Ring/Answered)... Furthermore, if you speak into your phone, you should hear an echo. The other test is grabbing the phone that's connected to the FXS port, and dial 500. This also should deliver an echo, albeit much quicker. 50c0804e2964a859f57277730be9be3e586f12eb 1772 1768 2008-10-12T15:23:11Z Saruman! 2 /* Installing Asterisk-GUI */ installation description wikitext text/x-wiki =Installing Asterisk= Once the hardware configuration part is completed, we can start the installation of Asterisk itself. Using ''aptitude'' or ''apt-get'', install package ''asterisk''. On Debian 5.0 "Lenny", it should be Asterisk 1.4.21.2. With ''apt-get'', the command is simply apt-get install asterisk Note: many, many dependencies bring a lot of extra packages to your server when you install Asterisk. On a test machine, I counted 24 extra packages (for a total of 11.4MB to be downloaded). If you have telephony hardware, you've likely already configured it in the preceding sections. However, when Asterisk itself is installed, you can run the ''genzaptelconf'' command again, and it will not only re-configure your ''zaptel.conf'', but also it will generate ''/etc/asterisk/zapata-channels.conf'' genzaptelconf -svdM -c nl Now, as the command suggests, include the ''zapata-channels.conf'' file in ''/etc/asterisk/zapata.conf'', either by running echo '#include zapata-channels.conf' >>/etc/asterisk/zapata.conf or by opening zapata.conf in your favourite [[vim | text editor]] and pasting the line "#include zapata-channels.conf" (including the hash sign) somewhere near the end of the file. When you've rerun ''genzaptelconf'', Asterisk will have started at the end of the command. Your adaptation of ''zapata.conf'' is not yet noticed by Asterisk. Please reload or restart asterisk, e.g. by running /etc/init.d/asterisk restart =Installing Asterisk-GUI= Asterisk-GUI is not an essential part of an Asterisk installation, but in some respects it can make life much easier for you. On the other hand, installing it is NOT as easy as with other Debian packages - because it's not available as a Debian package. Thus, we'll have to compile the Asterisk-GUI from source. First obtain the latest version of the ''asterisk-gui'' package; it can be downloaded from the download section of [http://www.asterisk.org/ the Asterisk site]; most likely at [http://downloads.digium.com/pub/telephony/asterisk-gui/releases/ this place]. Then extract it in some logical place, like ''/usr/src/'': tar xzvf asterisk-gui-2.0.2.tar.gz /usr/src This creates the directory ''/usr/src/asterisk-gui-2.0.2'', in which the source for Asterisk-GUI can be found. ''cd'' to this directory, confiure, and compile the software: cd /usr/src/asterisk-gui-2.0.2 ./configure make make install These three commands should complete successfully. They all give pretty clear output when everything runs fine (we haven't seen them fail, so we can't tell what that would look like, or what to do then).<br> OK, so we now need to do some configuration on Asterisk-GUI. It's main configuration files are ''/etc/asterisk/http.conf'', where the Asterisk-GUI itself is configured, and ''/etc/asterisk/manager.conf'', which is part of the Asterisk Manager Interface (AMI), over which Asterisk-GUI makes its moves. So first we put the necessary extra info in ''manager.conf''. The Debian setup for AMI has a line that includes all *.conf files in ''/etc/asterisk/manager.d'', so we go to that directory, and create ''asterisk-gui.conf''. In this, we can put the Asterisk-GUI specific lines: [general] webenabled=yes [asterisk-admin] secret = nOguess1ng read = system,call,log,verbose,command,agent,user,config write = system,call,log,verbose,command,agent,user,config Note that this file contains user information (well, it contains an Asterisk-GUI user) with a password, so you might want to secure this file ''/etc/asterisk/manager.d/asterisk-gui.conf'' by changing the owner to asterisk:asterisk, and remove the world-readable attribute chown asterisk:asterisk /etc/asterisk/manager.d/asterisk-gui.conf chmod o= /etc/asterisk/manager.d/asterisk-gui.conf Furthermore, we need to edit the ''/etc/asterisk/http.conf'' file that our Asterisk-GUI installation has created, so that it contains at least the following information (comments stripped): [general] enabled=yes enablestatic=yes bindaddr=127.0.0.1 bindport=8088 prefix=asterisk This enables Asterisk-GUI, so that ''asterisk-admin'' can both issue AMI commands and view HTML pages, as long as a browser on the server itself is used. Asterisk-GUI should be reachable on http://127.0.0.1:8088/asterisk =Configuring and testing Asterisk= If you've done nothing more than the [[Installing and configuring Zaptel | previously described]] hardware installation and configuration, and the default Asterisk installation given above, then you can already do one very simple test: plug a standard analogue telephone in one of your FXS-ports, and see if you get a dialtone. (Ofcourse, if you've only got FXO-ports or no hardware at all, then this won't help you.)<br> Furthermore, you could just look at the back of your Linux machine; the small LEDs next to all ports should be lit green (not including those ports for which you haven't installed a module, ofcourse). A port with a module installed, but without a burning LED, signifies no driver loaded.<br> Other tests and status reports can be obtained from the following commands: * ''lszaptel'' should show your hardware, with all installed ports (all denoted "in use"); non-installed ports may be shown as FXO-ports. Note: be aware of the neverending confusion surrounding the port name (e.g. FXS) and what signalling it runs (e.g. FXO); remember that those two are always opposed: FXO-ports run FXS signaling, FXS-ports run FXO-signaling. Thus, a non-installed port is shown as running FXS-signaling. * ''ztcfg -vv'' should show a channel map, with for each hardware channel the channel number and the signaling protocol. * ''asterisk -r'' should give you an Asterisk console (if Asterisk is in fact running). If the above tests succeed, then it's time for our initial Asterisk configuration. In the first configuration test, we'll configure both an FXS and an FXO channel - since that's what's in [http://downloads.oreilly.com/books/9780596510480.pdf asterisk, TFOTF]. This configuration comes in three parts:<Br> First, we make sure our FXS and FXO channels are defined in ''/etc/zaptel.conf'' - as we've already ensured previously. For this configuration test, we confirm that ''zaptel.conf'' contains something like # Span 1: WCTDM/0 "Wildcard TDM410P Board 1" (MASTER) fxoks=1 fxsks=3 # Global data loadzone = nl defaultzone = nl Next up, we check ''/etc/asterisk/zapata.conf''. When we filter that file through ''grep -v ^\; | grep -v ^$'' (thus removing lines beginning with ";" and empty lines), '''AND''' we insert the contents of ''zapata-channels.conf'' at the place of the insert statement, then we get something like [trunkgroups] [channels] context=default switchtype=national signalling=fxo_ls rxwink=300 usecallerid=yes hidecallerid=no callwaiting=yes usecallingpres=yes callwaitingcallerid=yes threewaycalling=yes transfer=yes canpark=yes cancallforward=yes callreturn=yes echocancel=yes echocancelwhenbridged=yes rxgain=0.0 txgain=0.0 group=1 callgroup=1 pickupgroup=1 immediate=no ; from here it's all zapata_channel.conf: signalling=fxo_ks callerid="Channel 1" <6001> mailbox=6001 group=5 context=from-internal channel => 1 callerid= mailbox= group= context=default signalling=fxo_ks callerid="Channel 2" <6002> mailbox=6002 group=5 context=from-internal channel => 2 callerid= mailbox= group= context=default signalling=fxs_ks callerid=asreceived group=0 context=from-pstn channel => 3 context=default Well that's all nice and dandy, but for testing we'll temporarily replace this ''zapata.conf'' with a much more dressed down one: [trunkgroups] [channels] usecallerid=yes hidecallerid=no callwaiting=no threewaycalling=yes transfer=yes echocancel=yes echotraining=yes switchtype=national ; from here it's all zapata_channel.conf: ; the internal phone on module 1/port 1 context=phones signalling=fxo_ks channel => 1 ; the incoming line on module 3/port 3 context=incoming signalling=fxs_ks channel => 3 The third configuration file we're going to change, is the file containing the "dialplan", which is ''/etc/asterisk/extensions.conf''. We'll use the example from the TFOTF book: [globals] [general] [default] exten => s,1,Verbose(1|Unrouted call handler) exten => s,n,Answer() exten => s,n,Wait(1) exten => s,n,Playback(tt-weasels) exten => s,n,Hangup() [incoming_calls] [internal] exten => 500,1,Verbose(1|Echo test application) exten => 500,n,Echo() exten => 500,n,Hangup() [phones] include => internal [incoming] exten => s,1,Answer() exten => s,n,Echo() With all config files changed (and their owner still ''asterisk:asterisk''), we can reload the necessary files. First we connect an outside line to the FXO port. Now we stop asterisk, then unload the Zaptel drivers, then reload them all (so they'll definately read their config files) (note: our example is for a Digium TDM410P, with driver wctdm24xxp; adapt to your own driver): /etc/init.d/asterisk stop rmmod wctdm24xxp rmmod zaptel modprobe zaptel modprobe wctdm24xxp /etc/init.d/asterisk start For demonstration purposes, start up an Asterisk console (''asterisk -f''). Now we can call the outside line attached to the FXO port (e.g. with a cell phone), and we should see in our Asterisk console something like [Oct 8 09:06:12] NOTICE[5640]: chan_zap.c:6562 ss_thread: Got event 18 (Ring Begin)... [Oct 8 09:06:14] NOTICE[5640]: chan_zap.c:6562 ss_thread: Got event 2 (Ring/Answered)... Furthermore, if you speak into your phone, you should hear an echo. The other test is grabbing the phone that's connected to the FXS port, and dial 500. This also should deliver an echo, albeit much quicker. 8b323e6016dca8a4a4dc59a26c280ac0a5e3d2db 1773 1772 2008-10-12T16:11:42Z Saruman! 2 /* Installing Asterisk-GUI */ added bugfix workaround wikitext text/x-wiki =Installing Asterisk= Once the hardware configuration part is completed, we can start the installation of Asterisk itself. Using ''aptitude'' or ''apt-get'', install package ''asterisk''. On Debian 5.0 "Lenny", it should be Asterisk 1.4.21.2. With ''apt-get'', the command is simply apt-get install asterisk Note: many, many dependencies bring a lot of extra packages to your server when you install Asterisk. On a test machine, I counted 24 extra packages (for a total of 11.4MB to be downloaded). If you have telephony hardware, you've likely already configured it in the preceding sections. However, when Asterisk itself is installed, you can run the ''genzaptelconf'' command again, and it will not only re-configure your ''zaptel.conf'', but also it will generate ''/etc/asterisk/zapata-channels.conf'' genzaptelconf -svdM -c nl Now, as the command suggests, include the ''zapata-channels.conf'' file in ''/etc/asterisk/zapata.conf'', either by running echo '#include zapata-channels.conf' >>/etc/asterisk/zapata.conf or by opening zapata.conf in your favourite [[vim | text editor]] and pasting the line "#include zapata-channels.conf" (including the hash sign) somewhere near the end of the file. When you've rerun ''genzaptelconf'', Asterisk will have started at the end of the command. Your adaptation of ''zapata.conf'' is not yet noticed by Asterisk. Please reload or restart asterisk, e.g. by running /etc/init.d/asterisk restart =Installing Asterisk-GUI= Asterisk-GUI is not an essential part of an Asterisk installation, but in some respects it can make life much easier for you. On the other hand, installing it is NOT as easy as with other Debian packages - because it's not available as a Debian package. Thus, we'll have to compile the Asterisk-GUI from source. First obtain the latest version of the ''asterisk-gui'' package; it can be downloaded from the download section of [http://www.asterisk.org/ the Asterisk site]; most likely at [http://downloads.digium.com/pub/telephony/asterisk-gui/releases/ this place]. Then extract it in some logical place, like ''/usr/src/'': tar xzvf asterisk-gui-2.0.2.tar.gz /usr/src This creates the directory ''/usr/src/asterisk-gui-2.0.2'', in which the source for Asterisk-GUI can be found. ''cd'' to this directory, confiure, and compile the software: cd /usr/src/asterisk-gui-2.0.2 ./configure make make install These three commands should complete successfully. They all give pretty clear output when everything runs fine (we haven't seen them fail, so we can't tell what that would look like, or what to do then).<br> OK, so we now need to do some configuration on Asterisk-GUI. It's main configuration files are ''/etc/asterisk/http.conf'', where the Asterisk-GUI itself is configured, and ''/etc/asterisk/manager.conf'', which is part of the Asterisk Manager Interface (AMI), over which Asterisk-GUI makes its moves. So first we put the necessary extra info in ''manager.conf''. The Debian setup for AMI has a line that includes all *.conf files in ''/etc/asterisk/manager.d'', so we go to that directory, and create ''asterisk-gui.conf''. In this, we can put the Asterisk-GUI specific lines: [general] webenabled=yes [asterisk-admin] secret = nOguess1ng read = system,call,log,verbose,command,agent,user,config write = system,call,log,verbose,command,agent,user,config Note that this file contains user information (well, it contains an Asterisk-GUI user) with a password, so you might want to secure this file ''/etc/asterisk/manager.d/asterisk-gui.conf'' by changing the owner to asterisk:asterisk, and remove the world-readable attribute chown asterisk:asterisk /etc/asterisk/manager.d/asterisk-gui.conf chmod o= /etc/asterisk/manager.d/asterisk-gui.conf Furthermore, we need to edit the ''/etc/asterisk/http.conf'' file that our Asterisk-GUI installation has created, so that it contains at least the following information (comments stripped): [general] enabled=yes enablestatic=yes bindaddr=127.0.0.1 bindport=8088 prefix=asterisk This enables Asterisk-GUI, so that ''asterisk-admin'' can both issue AMI commands and view HTML pages, as long as a browser on the server itself is used. Finally, we must work around a little Asterisk-GUI bug, by removing the (empty) directory ''static-http'' from ''/usr/share/asterisk'', and create a link there to the (non-empty) directory ''/var/lib/asterisk/static-http'': cd /usr/share/asterisk rmdir static-http ln -s /var/lib/asterisk/static-http static-http When all is said and done (well, '''done''', specifically), restart Asterisk. Asterisk-GUI should now be reachable on http://127.0.0.1:8088/asterisk/config/cfgbasic.html. Logging in there will make Asterisk-GUI configure itself ''and'' Asterisk. =Configuring and testing Asterisk= If you've done nothing more than the [[Installing and configuring Zaptel | previously described]] hardware installation and configuration, and the default Asterisk installation given above, then you can already do one very simple test: plug a standard analogue telephone in one of your FXS-ports, and see if you get a dialtone. (Ofcourse, if you've only got FXO-ports or no hardware at all, then this won't help you.)<br> Furthermore, you could just look at the back of your Linux machine; the small LEDs next to all ports should be lit green (not including those ports for which you haven't installed a module, ofcourse). A port with a module installed, but without a burning LED, signifies no driver loaded.<br> Other tests and status reports can be obtained from the following commands: * ''lszaptel'' should show your hardware, with all installed ports (all denoted "in use"); non-installed ports may be shown as FXO-ports. Note: be aware of the neverending confusion surrounding the port name (e.g. FXS) and what signalling it runs (e.g. FXO); remember that those two are always opposed: FXO-ports run FXS signaling, FXS-ports run FXO-signaling. Thus, a non-installed port is shown as running FXS-signaling. * ''ztcfg -vv'' should show a channel map, with for each hardware channel the channel number and the signaling protocol. * ''asterisk -r'' should give you an Asterisk console (if Asterisk is in fact running). If the above tests succeed, then it's time for our initial Asterisk configuration. In the first configuration test, we'll configure both an FXS and an FXO channel - since that's what's in [http://downloads.oreilly.com/books/9780596510480.pdf asterisk, TFOTF]. This configuration comes in three parts:<Br> First, we make sure our FXS and FXO channels are defined in ''/etc/zaptel.conf'' - as we've already ensured previously. For this configuration test, we confirm that ''zaptel.conf'' contains something like # Span 1: WCTDM/0 "Wildcard TDM410P Board 1" (MASTER) fxoks=1 fxsks=3 # Global data loadzone = nl defaultzone = nl Next up, we check ''/etc/asterisk/zapata.conf''. When we filter that file through ''grep -v ^\; | grep -v ^$'' (thus removing lines beginning with ";" and empty lines), '''AND''' we insert the contents of ''zapata-channels.conf'' at the place of the insert statement, then we get something like [trunkgroups] [channels] context=default switchtype=national signalling=fxo_ls rxwink=300 usecallerid=yes hidecallerid=no callwaiting=yes usecallingpres=yes callwaitingcallerid=yes threewaycalling=yes transfer=yes canpark=yes cancallforward=yes callreturn=yes echocancel=yes echocancelwhenbridged=yes rxgain=0.0 txgain=0.0 group=1 callgroup=1 pickupgroup=1 immediate=no ; from here it's all zapata_channel.conf: signalling=fxo_ks callerid="Channel 1" <6001> mailbox=6001 group=5 context=from-internal channel => 1 callerid= mailbox= group= context=default signalling=fxo_ks callerid="Channel 2" <6002> mailbox=6002 group=5 context=from-internal channel => 2 callerid= mailbox= group= context=default signalling=fxs_ks callerid=asreceived group=0 context=from-pstn channel => 3 context=default Well that's all nice and dandy, but for testing we'll temporarily replace this ''zapata.conf'' with a much more dressed down one: [trunkgroups] [channels] usecallerid=yes hidecallerid=no callwaiting=no threewaycalling=yes transfer=yes echocancel=yes echotraining=yes switchtype=national ; from here it's all zapata_channel.conf: ; the internal phone on module 1/port 1 context=phones signalling=fxo_ks channel => 1 ; the incoming line on module 3/port 3 context=incoming signalling=fxs_ks channel => 3 The third configuration file we're going to change, is the file containing the "dialplan", which is ''/etc/asterisk/extensions.conf''. We'll use the example from the TFOTF book: [globals] [general] [default] exten => s,1,Verbose(1|Unrouted call handler) exten => s,n,Answer() exten => s,n,Wait(1) exten => s,n,Playback(tt-weasels) exten => s,n,Hangup() [incoming_calls] [internal] exten => 500,1,Verbose(1|Echo test application) exten => 500,n,Echo() exten => 500,n,Hangup() [phones] include => internal [incoming] exten => s,1,Answer() exten => s,n,Echo() With all config files changed (and their owner still ''asterisk:asterisk''), we can reload the necessary files. First we connect an outside line to the FXO port. Now we stop asterisk, then unload the Zaptel drivers, then reload them all (so they'll definately read their config files) (note: our example is for a Digium TDM410P, with driver wctdm24xxp; adapt to your own driver): /etc/init.d/asterisk stop rmmod wctdm24xxp rmmod zaptel modprobe zaptel modprobe wctdm24xxp /etc/init.d/asterisk start For demonstration purposes, start up an Asterisk console (''asterisk -f''). Now we can call the outside line attached to the FXO port (e.g. with a cell phone), and we should see in our Asterisk console something like [Oct 8 09:06:12] NOTICE[5640]: chan_zap.c:6562 ss_thread: Got event 18 (Ring Begin)... [Oct 8 09:06:14] NOTICE[5640]: chan_zap.c:6562 ss_thread: Got event 2 (Ring/Answered)... Furthermore, if you speak into your phone, you should hear an echo. The other test is grabbing the phone that's connected to the FXS port, and dial 500. This also should deliver an echo, albeit much quicker. 53cb5ab3d7549263a79c660e2c256c4feb0e4470 1774 1773 2008-10-12T16:45:23Z Saruman! 2 /* Installing Asterisk-GUI */ slight rework of security wikitext text/x-wiki =Installing Asterisk= Once the hardware configuration part is completed, we can start the installation of Asterisk itself. Using ''aptitude'' or ''apt-get'', install package ''asterisk''. On Debian 5.0 "Lenny", it should be Asterisk 1.4.21.2. With ''apt-get'', the command is simply apt-get install asterisk Note: many, many dependencies bring a lot of extra packages to your server when you install Asterisk. On a test machine, I counted 24 extra packages (for a total of 11.4MB to be downloaded). If you have telephony hardware, you've likely already configured it in the preceding sections. However, when Asterisk itself is installed, you can run the ''genzaptelconf'' command again, and it will not only re-configure your ''zaptel.conf'', but also it will generate ''/etc/asterisk/zapata-channels.conf'' genzaptelconf -svdM -c nl Now, as the command suggests, include the ''zapata-channels.conf'' file in ''/etc/asterisk/zapata.conf'', either by running echo '#include zapata-channels.conf' >>/etc/asterisk/zapata.conf or by opening zapata.conf in your favourite [[vim | text editor]] and pasting the line "#include zapata-channels.conf" (including the hash sign) somewhere near the end of the file. When you've rerun ''genzaptelconf'', Asterisk will have started at the end of the command. Your adaptation of ''zapata.conf'' is not yet noticed by Asterisk. Please reload or restart asterisk, e.g. by running /etc/init.d/asterisk restart =Installing Asterisk-GUI= Asterisk-GUI is not an essential part of an Asterisk installation, but in some respects it can make life much easier for you. On the other hand, installing it is NOT as easy as with other Debian packages - because it's not available as a Debian package. Thus, we'll have to compile the Asterisk-GUI from source. First obtain the latest version of the ''asterisk-gui'' package; it can be downloaded from the download section of [http://www.asterisk.org/ the Asterisk site]; most likely at [http://downloads.digium.com/pub/telephony/asterisk-gui/releases/ this place]. Then extract it in some logical place, like ''/usr/src/'': tar xzvf asterisk-gui-2.0.2.tar.gz /usr/src This creates the directory ''/usr/src/asterisk-gui-2.0.2'', in which the source for Asterisk-GUI can be found. ''cd'' to this directory, confiure, and compile the software: cd /usr/src/asterisk-gui-2.0.2 ./configure make make install These three commands should complete successfully. They all give pretty clear output when everything runs fine (we haven't seen them fail, so we can't tell what that would look like, or what to do then).<br> OK, so we now need to do some configuration on Asterisk-GUI. It's main configuration files are ''/etc/asterisk/http.conf'', where the Asterisk-GUI itself is configured, and ''/etc/asterisk/manager.conf'', which is part of the Asterisk Manager Interface (AMI), over which Asterisk-GUI makes its moves. So first we put the necessary extra info in ''manager.conf''. The Debian setup for AMI has a line that includes all *.conf files in ''/etc/asterisk/manager.d'', so we only need to include manager-specific information in ''manager.conf''. This means only the following line in the section ''[general]'': webenabled = yes Now we go to ''/etc/asterisk/manager.d'', and create ''asterisk-gui.conf''. In this, we can put the Asterisk-GUI specific lines - which really only define Asterisk-GUI users, with their passwords and their rights: [asterisk-admin] secret = nOguess1ng read = system,call,log,verbose,command,agent,user,config write = system,call,log,verbose,command,agent,user,config Note that this file contains user information (well, it contains Asterisk-GUI user info) with a password, so you might want to secure this file ''/etc/asterisk/manager.d/asterisk-gui.conf'' by changing the owner to asterisk:asterisk, and remove the world-readable attribute chown asterisk:asterisk /etc/asterisk/manager.d/asterisk-gui.conf chmod o= /etc/asterisk/manager.d/asterisk-gui.conf Furthermore, we need to edit the ''/etc/asterisk/http.conf'' file that our Asterisk-GUI installation has created, so that it contains at least the following information (comments stripped): [general] enabled=yes enablestatic=yes bindaddr=127.0.0.1 bindport=8088 prefix=asterisk This enables Asterisk-GUI, so that ''asterisk-admin'' can both issue AMI commands and view HTML pages, as long as a browser on the server itself is used. You could also change the bind address to that of an internal NIC on your server, which is convenient for admins, but less secure. Keep in mind though, that you can also use the [[Firewall section | iceditch firewall]] to limit access to port 8088 to certain subnets and/or IP numbers. Finally, we must work around a little Asterisk-GUI bug, by removing the (empty) directory ''static-http'' from ''/usr/share/asterisk'', and create a link there to the (non-empty) directory ''/var/lib/asterisk/static-http'': cd /usr/share/asterisk rmdir static-http ln -s /var/lib/asterisk/static-http static-http When all is said and done (well, '''done''', specifically), restart Asterisk. Asterisk-GUI should now be reachable on http://127.0.0.1:8088/asterisk/config/cfgbasic.html. Logging in there will make Asterisk-GUI configure itself ''and'' Asterisk. =Configuring and testing Asterisk= If you've done nothing more than the [[Installing and configuring Zaptel | previously described]] hardware installation and configuration, and the default Asterisk installation given above, then you can already do one very simple test: plug a standard analogue telephone in one of your FXS-ports, and see if you get a dialtone. (Ofcourse, if you've only got FXO-ports or no hardware at all, then this won't help you.)<br> Furthermore, you could just look at the back of your Linux machine; the small LEDs next to all ports should be lit green (not including those ports for which you haven't installed a module, ofcourse). A port with a module installed, but without a burning LED, signifies no driver loaded.<br> Other tests and status reports can be obtained from the following commands: * ''lszaptel'' should show your hardware, with all installed ports (all denoted "in use"); non-installed ports may be shown as FXO-ports. Note: be aware of the neverending confusion surrounding the port name (e.g. FXS) and what signalling it runs (e.g. FXO); remember that those two are always opposed: FXO-ports run FXS signaling, FXS-ports run FXO-signaling. Thus, a non-installed port is shown as running FXS-signaling. * ''ztcfg -vv'' should show a channel map, with for each hardware channel the channel number and the signaling protocol. * ''asterisk -r'' should give you an Asterisk console (if Asterisk is in fact running). If the above tests succeed, then it's time for our initial Asterisk configuration. In the first configuration test, we'll configure both an FXS and an FXO channel - since that's what's in [http://downloads.oreilly.com/books/9780596510480.pdf asterisk, TFOTF]. This configuration comes in three parts:<Br> First, we make sure our FXS and FXO channels are defined in ''/etc/zaptel.conf'' - as we've already ensured previously. For this configuration test, we confirm that ''zaptel.conf'' contains something like # Span 1: WCTDM/0 "Wildcard TDM410P Board 1" (MASTER) fxoks=1 fxsks=3 # Global data loadzone = nl defaultzone = nl Next up, we check ''/etc/asterisk/zapata.conf''. When we filter that file through ''grep -v ^\; | grep -v ^$'' (thus removing lines beginning with ";" and empty lines), '''AND''' we insert the contents of ''zapata-channels.conf'' at the place of the insert statement, then we get something like [trunkgroups] [channels] context=default switchtype=national signalling=fxo_ls rxwink=300 usecallerid=yes hidecallerid=no callwaiting=yes usecallingpres=yes callwaitingcallerid=yes threewaycalling=yes transfer=yes canpark=yes cancallforward=yes callreturn=yes echocancel=yes echocancelwhenbridged=yes rxgain=0.0 txgain=0.0 group=1 callgroup=1 pickupgroup=1 immediate=no ; from here it's all zapata_channel.conf: signalling=fxo_ks callerid="Channel 1" <6001> mailbox=6001 group=5 context=from-internal channel => 1 callerid= mailbox= group= context=default signalling=fxo_ks callerid="Channel 2" <6002> mailbox=6002 group=5 context=from-internal channel => 2 callerid= mailbox= group= context=default signalling=fxs_ks callerid=asreceived group=0 context=from-pstn channel => 3 context=default Well that's all nice and dandy, but for testing we'll temporarily replace this ''zapata.conf'' with a much more dressed down one: [trunkgroups] [channels] usecallerid=yes hidecallerid=no callwaiting=no threewaycalling=yes transfer=yes echocancel=yes echotraining=yes switchtype=national ; from here it's all zapata_channel.conf: ; the internal phone on module 1/port 1 context=phones signalling=fxo_ks channel => 1 ; the incoming line on module 3/port 3 context=incoming signalling=fxs_ks channel => 3 The third configuration file we're going to change, is the file containing the "dialplan", which is ''/etc/asterisk/extensions.conf''. We'll use the example from the TFOTF book: [globals] [general] [default] exten => s,1,Verbose(1|Unrouted call handler) exten => s,n,Answer() exten => s,n,Wait(1) exten => s,n,Playback(tt-weasels) exten => s,n,Hangup() [incoming_calls] [internal] exten => 500,1,Verbose(1|Echo test application) exten => 500,n,Echo() exten => 500,n,Hangup() [phones] include => internal [incoming] exten => s,1,Answer() exten => s,n,Echo() With all config files changed (and their owner still ''asterisk:asterisk''), we can reload the necessary files. First we connect an outside line to the FXO port. Now we stop asterisk, then unload the Zaptel drivers, then reload them all (so they'll definately read their config files) (note: our example is for a Digium TDM410P, with driver wctdm24xxp; adapt to your own driver): /etc/init.d/asterisk stop rmmod wctdm24xxp rmmod zaptel modprobe zaptel modprobe wctdm24xxp /etc/init.d/asterisk start For demonstration purposes, start up an Asterisk console (''asterisk -f''). Now we can call the outside line attached to the FXO port (e.g. with a cell phone), and we should see in our Asterisk console something like [Oct 8 09:06:12] NOTICE[5640]: chan_zap.c:6562 ss_thread: Got event 18 (Ring Begin)... [Oct 8 09:06:14] NOTICE[5640]: chan_zap.c:6562 ss_thread: Got event 2 (Ring/Answered)... Furthermore, if you speak into your phone, you should hear an echo. The other test is grabbing the phone that's connected to the FXS port, and dial 500. This also should deliver an echo, albeit much quicker. 1129d9f5d22581e61420337d3335b2939e24e1f2 0 1478 1769 2008-10-10T18:56:41Z Saruman! 2 Page started wikitext text/x-wiki =Configuring SIP= In this section we'll be configuring our Asterisk to accept a SIP client, like a VoIP telephone or a softphone. =Configuring a SNOM360 softphone= From the SNOM site you can download a SNOM360 softfone. =Configuring IAX2= This concerns the inter-Asterisk eXchange protocol. 71faeaf1be1d4371d25d9ff8ec0d99c88bd44e2c 1770 1769 2008-10-10T19:37:36Z Saruman! 2 /* Configuring SIP */ config files added wikitext text/x-wiki =Configuring SIP= In this section we'll be configuring our Asterisk to accept a SIP client, like a VoIP telephone or a softphone. [http://downloads.oreilly.com/books/9780596510480.pdf The Book] tells us that we should begin with a most simple ''sip.conf'' file, so we will: [general] [1000] type=friend context=phones host=dynamic secret=Marilli0n With this setup, and the secret password (in this example Marilli0n) we can easily test if the SIP phone works. OK, so we're guessing your Asterisk was running when you changed or created your ''sip.conf''. Connect to Asterisk, and in the CLI, reload the diaplpan and SIP channel: asterisk -rvvv *CLI> dialplan reload *CLI> sip reload =Configuring a SNOM360 softphone= From the SNOM site you can download a SNOM360 softfone. =Configuring IAX2= This concerns the inter-Asterisk eXchange protocol. 14c0fb091864d8beab327b8b5d403175c7021d69 1771 1770 2008-10-10T20:01:19Z Saruman! 2 more sip wikitext text/x-wiki =Configuring SIP= In this section we'll be configuring our Asterisk to accept a SIP client, like a VoIP telephone or a softphone. [http://downloads.oreilly.com/books/9780596510480.pdf The Book] tells us that we should begin with a most simple ''sip.conf'' file, so we will: [general] [1000] type=friend context=phones host=dynamic secret=Marilli0n With this setup, and the secret password (in this example Marilli0n) we can easily test if the SIP phone works. OK, so we're guessing your Asterisk was running when you changed or created your ''sip.conf''. Connect to Asterisk, and in the CLI, reload the diaplpan and SIP channel: asterisk -rvvv *CLI> dialplan reload *CLI> sip reload =Configuring an X-Lite softphone= The configuration of an X-Lite is quite simple. =Configuring a SNOM360 softphone= From the SNOM site you can download a SNOM360 softfone. =Configuring IAX2= This concerns the inter-Asterisk eXchange protocol. 275204cfeabac6f37d848969650435ecde5ab723 0 1480 1788 2008-10-14T19:19:38Z Saruman! 2 Page started wikitext text/x-wiki = Asterisk basic configuration principles = In this section we'll have a look at the basic configuration of an Asterisk PBX. Contrary to the TFOT-book, we'll be looking at it from the theory side, and from there go to an example configuration. For this example configuration, we'll start from a server with on the "outside" a POTS line and a SIP account with an Internet provider, and on the "inside" two analogue telephones and a SIP softphone. Our goal is to let the PBX behave as if we don't even have a PBX, but a standard home situation: for an incoming call, all phones ring; and every internal phone can make calls to the outside. = Asterisk channel configuration basics = The first thing to realise, is that all devices attached to the Asterisk PBX have their specific configuration files. Correctly setting up each (set of) telephony devices = Asterisk dialplans - contexts = = Asterisk dialplans - handling incoming calls = = Asterisk dialplans - handling outgoing calls = = Where to go from here= c3d6c781e208eceb4da756f36187031aaabb9bc5 1791 1788 2008-10-14T19:30:16Z 82.161.20.132 0 /* Asterisk dialplans - handling incoming calls */ wikitext text/x-wiki = Asterisk basic configuration principles = In this section we'll have a look at the basic configuration of an Asterisk PBX. Contrary to the TFOT-book, we'll be looking at it from the theory side, and from there go to an example configuration. For this example configuration, we'll start from a server with on the "outside" a POTS line and a SIP account with an Internet provider, and on the "inside" two analogue telephones and a SIP softphone. Our goal is to let the PBX behave as if we don't even have a PBX, but a standard home situation: for an incoming call, all phones ring; and every internal phone can make calls to the outside. = Asterisk channel configuration basics = The first thing to realise, is that all devices attached to the Asterisk PBX have their specific configuration files. Correctly setting up each (set of) telephony devices = Asterisk dialplans - contexts = = Asterisk dialplans - handling incoming calls = What is a Channel? A channel is a connection which brings in a call to the Asterisk PBX. A channel could be a connection to an ordinary telephone handset or an ordinary telephone line, or to a logical call (like an Internet phone call). Asterisk makes no distinction between "FXO" and "FXS" style channels (that is, it doesn't distinguish between telephone lines and telephones). Every call is placed or received on a distinct channel. = Asterisk dialplans - handling outgoing calls = = Where to go from here= 9bdfbd01a51ee70fc6d5477cedb63bbe3486cb11 0 1480 1792 1791 2008-10-14T20:19:20Z Saruman! 2 /* Asterisk channel configuration basics */ first entries wikitext text/x-wiki = Asterisk basic configuration principles = In this section we'll have a look at the basic configuration of an Asterisk PBX. Contrary to the TFOT-book, we'll be looking at it from the theory side, and from there go to an example configuration. For this example configuration, we'll start from a server with on the "outside" a POTS line and a SIP account with an Internet provider, and on the "inside" two analogue telephones and a SIP softphone. Our goal is to let the PBX behave as if we don't even have a PBX, but a standard home situation: for an incoming call, all phones ring; and every internal phone can make calls to the outside. = Asterisk channel configuration basics = The first thing to realise is that Asterisk sees each connected telephony device as a "channel". But what is a Channel? To Asterisk, a channel is a connection which brings in a call to the Asterisk PBX. A channel could be a connection to an ordinary telephone handset or an ordinary telephone line, or to a logical call (like an Internet phone call). Asterisk makes no distinction between "FXO" and "FXS" style channels (that is, it doesn't distinguish between telephone lines and telephones). Every call is placed or received on a distinct channel. The second thing to realise, is that every type of device attached to the Asterisk PBX have their own specific configuration files. Correctly setting up each (set of) telephony devices makes them available in our Asterisk PBX as channels. Thus, the device configuration files serve as a kind of abstraction layer, and simplify our final Asterisk configuration by putting "channel-specific" information in separate files. If you've followed the previous Asterisk sections in this Wiki, or followed the first four chapters of the TFOT-book, then you've encountered the following configuration files: * ''zaptel.conf'' - in this file, you can set up the most basic parameters for your Zap-type hardware channels, most notably Digium telephony cards. You're configuring the hardware itself, via its driver. You could think of this file as belonging to the hardware, not Asterisk. If you'd have other software on your machine besides Asterisk that could make use of your telephony hardware, then that'd be influenced as well when you change ''zaptel.conf''. * ''zapata.conf'' (and possibly ''zapata-channel.conf'' if you're on Debian) - this file handles the Asterisk-specific configuration of the hardware telephony channels. It thus "sets up the Zap channels" that Asterisk sees - for incoming and outgoing calls. All parameters that set up the channel are specified here. * ''vpb.conf'' - this file is used to configure [http://www.voicetronix.com/ Voicetronix] cards with Asterisk. If you've a Voicetronix card in use, then you've also installed the Voicetronix drivers. This makes the card(s) useable under Linux. But to have Asterisk use the card(s), you need this ''vpb.conf'' file. It thus serves the same purpose as ''zapata.conf''. * ''sip.conf'' - this file contains all information on all SIP devices that we want to connect to our Asterisk server; be it one or more SIP accounts with Internet providers, or SIP capable telephones (hardware or software). When ''sip.conf'' has been set up correctly, we can refer to a SIP device by a friendly name like [1000] or [Jane]. * ''iax.conf'' - this file is just the same as the ''sip.conf'' file, only it handles devices that talk IAX2 protocol instead of the SIP protocol. These five files define all channels that our basic Asterisk PBX might handle (well, it won't even handle the last one, since we're not connecting any other Asterisk boxes or IAX-(soft)phones to our PBX, and it won't handle the third one if you don't have a Voicetronix card). As a reference, we're going to list the contents of four example files, and explain what they do in the way of preparing channels for our simple Asterisk server.: ==zaptel.conf== # Autogenerated by ./genzaptelconf -- do not hand edit # Zaptel Configuration File # # This file is parsed by the Zaptel Configurator, ztcfg # # It must be in the module loading order # Span 1: WCTDM/0 "Wildcard TDM410P Board 1" (MASTER) fxoks=1 fxoks=2 fxsks=3 # channel 4, WCTDM, no module. # Global data loadzone = nl defaultzone = nl This is a relatively simple file. As you can see, the ''genzaptelconf'' command has generated it for us. It belongs with a Digium TDM410P card, which has two FXS modules in positions 1 and 2, and one FXO module in position 3. The first two non-commented lines define the protocol that the FXS modules must "talk" Do not be alarmed by the difference between the ==zapata-channel.conf== ==zapata.conf== ==sip.conf== = Asterisk dialplans - contexts = = Asterisk dialplans - handling incoming calls = What is a Channel? A channel is a connection which brings in a call to the Asterisk PBX. A channel could be a connection to an ordinary telephone handset or an ordinary telephone line, or to a logical call (like an Internet phone call). Asterisk makes no distinction between "FXO" and "FXS" style channels (that is, it doesn't distinguish between telephone lines and telephones). Every call is placed or received on a distinct channel. = Asterisk dialplans - handling outgoing calls = = Where to go from here= 6d0128ded19e106dd3f2879f04c88cbd789c7548 1793 1792 2008-10-14T20:28:00Z Insomnia 3 /* Asterisk dialplans - contexts */ wikitext text/x-wiki = Asterisk basic configuration principles = In this section we'll have a look at the basic configuration of an Asterisk PBX. Contrary to the TFOT-book, we'll be looking at it from the theory side, and from there go to an example configuration. For this example configuration, we'll start from a server with on the "outside" a POTS line and a SIP account with an Internet provider, and on the "inside" two analogue telephones and a SIP softphone. Our goal is to let the PBX behave as if we don't even have a PBX, but a standard home situation: for an incoming call, all phones ring; and every internal phone can make calls to the outside. = Asterisk channel configuration basics = The first thing to realise is that Asterisk sees each connected telephony device as a "channel". But what is a Channel? To Asterisk, a channel is a connection which brings in a call to the Asterisk PBX. A channel could be a connection to an ordinary telephone handset or an ordinary telephone line, or to a logical call (like an Internet phone call). Asterisk makes no distinction between "FXO" and "FXS" style channels (that is, it doesn't distinguish between telephone lines and telephones). Every call is placed or received on a distinct channel. The second thing to realise, is that every type of device attached to the Asterisk PBX have their own specific configuration files. Correctly setting up each (set of) telephony devices makes them available in our Asterisk PBX as channels. Thus, the device configuration files serve as a kind of abstraction layer, and simplify our final Asterisk configuration by putting "channel-specific" information in separate files. If you've followed the previous Asterisk sections in this Wiki, or followed the first four chapters of the TFOT-book, then you've encountered the following configuration files: * ''zaptel.conf'' - in this file, you can set up the most basic parameters for your Zap-type hardware channels, most notably Digium telephony cards. You're configuring the hardware itself, via its driver. You could think of this file as belonging to the hardware, not Asterisk. If you'd have other software on your machine besides Asterisk that could make use of your telephony hardware, then that'd be influenced as well when you change ''zaptel.conf''. * ''zapata.conf'' (and possibly ''zapata-channel.conf'' if you're on Debian) - this file handles the Asterisk-specific configuration of the hardware telephony channels. It thus "sets up the Zap channels" that Asterisk sees - for incoming and outgoing calls. All parameters that set up the channel are specified here. * ''vpb.conf'' - this file is used to configure [http://www.voicetronix.com/ Voicetronix] cards with Asterisk. If you've a Voicetronix card in use, then you've also installed the Voicetronix drivers. This makes the card(s) useable under Linux. But to have Asterisk use the card(s), you need this ''vpb.conf'' file. It thus serves the same purpose as ''zapata.conf''. * ''sip.conf'' - this file contains all information on all SIP devices that we want to connect to our Asterisk server; be it one or more SIP accounts with Internet providers, or SIP capable telephones (hardware or software). When ''sip.conf'' has been set up correctly, we can refer to a SIP device by a friendly name like [1000] or [Jane]. * ''iax.conf'' - this file is just the same as the ''sip.conf'' file, only it handles devices that talk IAX2 protocol instead of the SIP protocol. These five files define all channels that our basic Asterisk PBX might handle (well, it won't even handle the last one, since we're not connecting any other Asterisk boxes or IAX-(soft)phones to our PBX, and it won't handle the third one if you don't have a Voicetronix card). As a reference, we're going to list the contents of four example files, and explain what they do in the way of preparing channels for our simple Asterisk server.: ==zaptel.conf== # Autogenerated by ./genzaptelconf -- do not hand edit # Zaptel Configuration File # # This file is parsed by the Zaptel Configurator, ztcfg # # It must be in the module loading order # Span 1: WCTDM/0 "Wildcard TDM410P Board 1" (MASTER) fxoks=1 fxoks=2 fxsks=3 # channel 4, WCTDM, no module. # Global data loadzone = nl defaultzone = nl This is a relatively simple file. As you can see, the ''genzaptelconf'' command has generated it for us. It belongs with a Digium TDM410P card, which has two FXS modules in positions 1 and 2, and one FXO module in position 3. The first two non-commented lines define the protocol that the FXS modules must "talk" Do not be alarmed by the difference between the ==zapata-channel.conf== ==zapata.conf== ==sip.conf== = Asterisk dialplans - contexts = A dial plan consists of a number of extensions. Each extensions consists of a number of priorities. Extensions are grouped in contexts. For each priority, an application is called. [context] exten => id, priority, command When Asterisk receives an incoming connection on a channel, Asterisk looks at the context defined for that channel for commands telling Asterisk what it should do. The context defines different sets of commands depending on what extension the user has dialed. For example, a context might provide one set of commands for what to do if the user dials "123", and another set of commands for what to do if the user dials "9", and another set of commands for what to do if the user dials any number beginning with "555". For some kinds of connections — such incoming calls from an outside telephone line — the user has not dialed an extension. In that case, Asterisk behaves as if the user had dialed a special extension named "s" (for Start). Asterisk will look for an extension "number" s in the definition of the context for that channel for instructions about what it should do to handle the call. Let's say, for example, that you have a channel "Zap/1" which is a connection to a telephone handset in your building. And let's say that in the configuration file for Zap channels (zapata.conf), you have defined context=john for Zap channel 1. So when you use that handset to dial a number, Asterisk looks for a context with the name "john" in extensions.conf to find out what it should do. You begin the definition of a context in extensions.conf by putting the name of the context in square brackets on a line by itself, like this: [john] == Extensions == Asterisk uses some extension names for special purposes: * i : Invalid * s : Start * h : Hangup * t : Timeout * T : AbsoluteTimeout * a : Asterisk extension * o : Operator = Asterisk dialplans - handling incoming calls = What is a Channel? A channel is a connection which brings in a call to the Asterisk PBX. A channel could be a connection to an ordinary telephone handset or an ordinary telephone line, or to a logical call (like an Internet phone call). Asterisk makes no distinction between "FXO" and "FXS" style channels (that is, it doesn't distinguish between telephone lines and telephones). Every call is placed or received on a distinct channel. = Asterisk dialplans - handling outgoing calls = = Where to go from here= 09e1308ac340d5e428e3d1ee5b481a3894e82823 1794 1793 2008-10-14T20:41:13Z Insomnia 3 /* Extensions */ wikitext text/x-wiki = Asterisk basic configuration principles = In this section we'll have a look at the basic configuration of an Asterisk PBX. Contrary to the TFOT-book, we'll be looking at it from the theory side, and from there go to an example configuration. For this example configuration, we'll start from a server with on the "outside" a POTS line and a SIP account with an Internet provider, and on the "inside" two analogue telephones and a SIP softphone. Our goal is to let the PBX behave as if we don't even have a PBX, but a standard home situation: for an incoming call, all phones ring; and every internal phone can make calls to the outside. = Asterisk channel configuration basics = The first thing to realise is that Asterisk sees each connected telephony device as a "channel". But what is a Channel? To Asterisk, a channel is a connection which brings in a call to the Asterisk PBX. A channel could be a connection to an ordinary telephone handset or an ordinary telephone line, or to a logical call (like an Internet phone call). Asterisk makes no distinction between "FXO" and "FXS" style channels (that is, it doesn't distinguish between telephone lines and telephones). Every call is placed or received on a distinct channel. The second thing to realise, is that every type of device attached to the Asterisk PBX have their own specific configuration files. Correctly setting up each (set of) telephony devices makes them available in our Asterisk PBX as channels. Thus, the device configuration files serve as a kind of abstraction layer, and simplify our final Asterisk configuration by putting "channel-specific" information in separate files. If you've followed the previous Asterisk sections in this Wiki, or followed the first four chapters of the TFOT-book, then you've encountered the following configuration files: * ''zaptel.conf'' - in this file, you can set up the most basic parameters for your Zap-type hardware channels, most notably Digium telephony cards. You're configuring the hardware itself, via its driver. You could think of this file as belonging to the hardware, not Asterisk. If you'd have other software on your machine besides Asterisk that could make use of your telephony hardware, then that'd be influenced as well when you change ''zaptel.conf''. * ''zapata.conf'' (and possibly ''zapata-channel.conf'' if you're on Debian) - this file handles the Asterisk-specific configuration of the hardware telephony channels. It thus "sets up the Zap channels" that Asterisk sees - for incoming and outgoing calls. All parameters that set up the channel are specified here. * ''vpb.conf'' - this file is used to configure [http://www.voicetronix.com/ Voicetronix] cards with Asterisk. If you've a Voicetronix card in use, then you've also installed the Voicetronix drivers. This makes the card(s) useable under Linux. But to have Asterisk use the card(s), you need this ''vpb.conf'' file. It thus serves the same purpose as ''zapata.conf''. * ''sip.conf'' - this file contains all information on all SIP devices that we want to connect to our Asterisk server; be it one or more SIP accounts with Internet providers, or SIP capable telephones (hardware or software). When ''sip.conf'' has been set up correctly, we can refer to a SIP device by a friendly name like [1000] or [Jane]. * ''iax.conf'' - this file is just the same as the ''sip.conf'' file, only it handles devices that talk IAX2 protocol instead of the SIP protocol. These five files define all channels that our basic Asterisk PBX might handle (well, it won't even handle the last one, since we're not connecting any other Asterisk boxes or IAX-(soft)phones to our PBX, and it won't handle the third one if you don't have a Voicetronix card). As a reference, we're going to list the contents of four example files, and explain what they do in the way of preparing channels for our simple Asterisk server.: ==zaptel.conf== # Autogenerated by ./genzaptelconf -- do not hand edit # Zaptel Configuration File # # This file is parsed by the Zaptel Configurator, ztcfg # # It must be in the module loading order # Span 1: WCTDM/0 "Wildcard TDM410P Board 1" (MASTER) fxoks=1 fxoks=2 fxsks=3 # channel 4, WCTDM, no module. # Global data loadzone = nl defaultzone = nl This is a relatively simple file. As you can see, the ''genzaptelconf'' command has generated it for us. It belongs with a Digium TDM410P card, which has two FXS modules in positions 1 and 2, and one FXO module in position 3. The first two non-commented lines define the protocol that the FXS modules must "talk" Do not be alarmed by the difference between the ==zapata-channel.conf== ==zapata.conf== ==sip.conf== = Asterisk dialplans - contexts = A dial plan consists of a number of extensions. Each extensions consists of a number of priorities. Extensions are grouped in contexts. For each priority, an application is called. [context] exten => id, priority, command When Asterisk receives an incoming connection on a channel, Asterisk looks at the context defined for that channel for commands telling Asterisk what it should do. The context defines different sets of commands depending on what extension the user has dialed. For example, a context might provide one set of commands for what to do if the user dials "123", and another set of commands for what to do if the user dials "9", and another set of commands for what to do if the user dials any number beginning with "555". For some kinds of connections — such incoming calls from an outside telephone line — the user has not dialed an extension. In that case, Asterisk behaves as if the user had dialed a special extension named "s" (for Start). Asterisk will look for an extension "number" s in the definition of the context for that channel for instructions about what it should do to handle the call. Let's say, for example, that you have a channel "Zap/1" which is a connection to a telephone handset in your building. And let's say that in the configuration file for Zap channels (zapata.conf), you have defined context=john for Zap channel 1. So when you use that handset to dial a number, Asterisk looks for a context with the name "john" in extensions.conf to find out what it should do. You begin the definition of a context in extensions.conf by putting the name of the context in square brackets on a line by itself, like this: [john] == Extensions == An extension can be one of two types: a literal or a pattern. A literal extension can be a number, like 123, and it can also contain the standard symbols * and # that appear on ordinary telephones, so 12#89* is a valid extension. A single extension can also match patterns. In the extensions.conf file, an extension name is a pattern if it starts with the underscore symbol (_). In an extension pattern, the following characters have special meanings: X matches any digit from 0-9 Z matches any digit from 1-9 N matches any digit from 2-9 [1237-9] matches any digit or letter in the brackets (in this example, 1,2,3,7,8,9) . wildcard, matches one or more characters ! wildcard, matches zero or more characters immediately Asterisk uses some extension names for special purposes: * i : Invalid * s : Start * h : Hangup * t : Timeout * T : AbsoluteTimeout * a : Asterisk extension * o : Operator = Asterisk dialplans - handling incoming calls = What is a Channel? A channel is a connection which brings in a call to the Asterisk PBX. A channel could be a connection to an ordinary telephone handset or an ordinary telephone line, or to a logical call (like an Internet phone call). Asterisk makes no distinction between "FXO" and "FXS" style channels (that is, it doesn't distinguish between telephone lines and telephones). Every call is placed or received on a distinct channel. = Asterisk dialplans - handling outgoing calls = = Where to go from here= 9f9ec04cb00dd31e104005644074834b642d74f6 1795 1794 2008-10-14T21:01:15Z Saruman! 2 /* Asterisk channel configuration basics */ added zapata-channels.conf example + explanation wikitext text/x-wiki = Asterisk basic configuration principles = In this section we'll have a look at the basic configuration of an Asterisk PBX. Contrary to the TFOT-book, we'll be looking at it from the theory side, and from there go to an example configuration. For this example configuration, we'll start from a server with on the "outside" a POTS line and a SIP account with an Internet provider, and on the "inside" two analogue telephones and a SIP softphone. Our goal is to let the PBX behave as if we don't even have a PBX, but a standard home situation: for an incoming call, all phones ring; and every internal phone can make calls to the outside. = Asterisk channel configuration basics = The first thing to realise is that Asterisk sees each connected telephony device as a "channel". But what is a Channel? To Asterisk, a channel is a connection which brings in a call to the Asterisk PBX. A channel could be a connection to an ordinary telephone handset or an ordinary telephone line, or to a logical call (like an Internet phone call). Asterisk makes no distinction between "FXO" and "FXS" style channels (that is, it doesn't distinguish between telephone lines and telephones). Every call is placed or received on a distinct channel. The second thing to realise, is that every type of device attached to the Asterisk PBX have their own specific configuration files. Correctly setting up each (set of) telephony devices makes them available in our Asterisk PBX as channels. Thus, the device configuration files serve as a kind of abstraction layer, and simplify our final Asterisk configuration by putting "channel-specific" information in separate files. If you've followed the previous Asterisk sections in this Wiki, or followed the first four chapters of the TFOT-book, then you've encountered the following configuration files: * ''zaptel.conf'' - in this file, you can set up the most basic parameters for your Zap-type hardware channels, most notably Digium telephony cards. You're configuring the hardware itself, via its driver. You could think of this file as belonging to the hardware, not Asterisk. If you'd have other software on your machine besides Asterisk that could make use of your telephony hardware, then that'd be influenced as well when you change ''zaptel.conf''. * ''zapata.conf'' (and possibly ''zapata-channels.conf'' if you're on Debian) - this file handles the Asterisk-specific configuration of the hardware telephony channels. It thus "sets up the Zap channels" that Asterisk sees - for incoming and outgoing calls. All parameters that set up the channel are specified here. * ''vpb.conf'' - this file is used to configure [http://www.voicetronix.com/ Voicetronix] cards with Asterisk. If you've a Voicetronix card in use, then you've also installed the Voicetronix drivers. This makes the card(s) useable under Linux. But to have Asterisk use the card(s), you need this ''vpb.conf'' file. It thus serves the same purpose as ''zapata.conf''. * ''sip.conf'' - this file contains all information on all SIP devices that we want to connect to our Asterisk server; be it one or more SIP accounts with Internet providers, or SIP capable telephones (hardware or software). When ''sip.conf'' has been set up correctly, we can refer to a SIP device by a friendly name like [1000] or [Jane]. * ''iax.conf'' - this file is just the same as the ''sip.conf'' file, only it handles devices that talk IAX2 protocol instead of the SIP protocol. These five files define all channels that our basic Asterisk PBX might handle (well, it won't even handle the last one, since we're not connecting any other Asterisk boxes or IAX-(soft)phones to our PBX, and it won't handle the third one if you don't have a Voicetronix card). As a reference, we're going to list the contents of four example files, and explain what they do in the way of preparing channels for our simple Asterisk server.: ==zaptel.conf== # Autogenerated by ./genzaptelconf -- do not hand edit # Zaptel Configuration File # # This file is parsed by the Zaptel Configurator, ztcfg # # It must be in the module loading order # Span 1: WCTDM/0 "Wildcard TDM410P Board 1" (MASTER) fxoks=1 fxoks=2 fxsks=3 # channel 4, WCTDM, no module. # Global data loadzone = nl defaultzone = nl This is a relatively simple file, configuring three Digium modules. As you can see, the ''genzaptelconf'' command has generated it for us. It belongs with a Digium TDM410P card, which has two FXS modules in positions 1 and 2, and one FXO module in position 3. The first two non-commented lines define the protocol that the FXS modules must "talk" with the attached devices, which "naturally" is the FXO protocol (yes, FXS talks FXO, and FXO talks FXS... a bit like electric current flowing from negative to positive. It's just a matter of definitions).<br> The third line defines that the FXO module talks FXS protocol.<br> The fourth line configures a set of indications to use for the defined channels. Since we're loading "nl", we're configuring Dutch dialtones etcetera for the channels.<br> Finally, the last line tell the server that any channel that does not have a zone assigned to it, should have the specified default zone configured - Dutch as well in this example.<br> With this simple file, the driver for our example card (''wctdm24xxp'', by the way) can set up the hardware just as we want it. Now to tell Asterisk how to use it... ==zapata-channels.conf== ; Autogenerated by ./genzaptelconf -- do not hand edit ; Zaptel Channels Configurations (zapata.conf) ; ; This is not intended to be a complete zapata.conf. Rather, it is intended ; to be #include-d by /etc/zapata.conf that will include the global settings ; ; Span 1: WCTDM/0 "Wildcard TDM410P Board 1" (MASTER) ;;; line="1 WCTDM/0/0" signalling=fxo_ks callerid="Channel 1" <6001> mailbox=6001 group=5 context=from-internal channel => 1 callerid= mailbox= group= context=default ;;; line="2 WCTDM/0/1" signalling=fxo_ks callerid="Channel 2" <6002> mailbox=6002 group=5 context=from-internal channel => 2 callerid= mailbox= group= context=default ;;; line="3 WCTDM/0/2" signalling=fxs_ks callerid=asreceived group=0 context=from-pstn channel => 3 context=default This second file is also auto-generated. It sets up three channels, associated with the three Digium hardware modules that we've configured with ''zaptel.conf''. Here, we also see how the channel numbers get assigned to the physical ports. The first module gets to be Zap channel 1 ('''Zap/1'''), the second '''Zap/2''' and so on. So if we would like our FXO module to be channel 1, and our FXS modules 2 and three, we could rotate the three channel numbers in this file. Probably we'd then also want to rotate the ''callerid''`s though... Furthermore, we don't think it's a good idea to assign channels to Zap devices in a different order than the devices are found in the system - meaning "stick with the default numbering as much as possible". Note that the way ''zapata-channels.conf'' is interpreted, means that any statement like ''signalling=fxs_ks'' actually ''sets'' the ''signalling'' parameter; when the ''channel => 1'' line is reached, then all preceding parameter assignments are applied to that particular channel. This also means that if you somewhere have set a channel to belong to context "foo", and then never set a context again, then every next channel also gets assigned to "foo". So remember: if you don't see a parameter being set with a specific channel, you CANNOT assume that it then has it's default value; if a preceding channel has set that parameter to value "bar", then for your specific channel, it is "bar" also. An interesting thing to see here is how ''genzaptelconf'' deals with the above concept. After defining each channel, it resets the most important parameters (a.o. the ones that should be unique with a channel) to empty or "default". This means that if you yourself are very meticulous, you could do without that safety net, and rewrite the above configuration file as: signalling=fxo_ks callerid="Channel 1" <6001> mailbox=6001 group=5 context=from-internal channel => 1 signalling=fxo_ks callerid="Channel 2" <6002> mailbox=6002 group=5 context=from-internal channel => 2 signalling=fxs_ks callerid=asreceived group=0 context=from-pstn channel => 3 Note: we like the thoroughnes of the ''genzaptelconf'' configuration, but we like the readability of the second file more. ==zapata.conf== [trunkgroups] [channels] switchtype=national rxwink=300 ; Atlas seems to use long (250ms) winks usecallerid=yes hidecallerid=no callwaiting=yes usecallingpres=yes callwaitingcallerid=yes threewaycalling=yes transfer=yes canpark=yes cancallforward=yes callreturn=yes echocancel=yes echocancelwhenbridged=yes rxgain=0.0 txgain=0.0 callgroup=1 pickupgroup=1 immediate=no #include zapata-channels.conf Under Debian, ==sip.conf== = Asterisk dialplans - contexts = A dial plan consists of a number of extensions. Each extensions consists of a number of priorities. Extensions are grouped in contexts. For each priority, an application is called. [context] exten => id, priority, command When Asterisk receives an incoming connection on a channel, Asterisk looks at the context defined for that channel for commands telling Asterisk what it should do. The context defines different sets of commands depending on what extension the user has dialed. For example, a context might provide one set of commands for what to do if the user dials "123", and another set of commands for what to do if the user dials "9", and another set of commands for what to do if the user dials any number beginning with "555". For some kinds of connections — such incoming calls from an outside telephone line — the user has not dialed an extension. In that case, Asterisk behaves as if the user had dialed a special extension named "s" (for Start). Asterisk will look for an extension "number" s in the definition of the context for that channel for instructions about what it should do to handle the call. Let's say, for example, that you have a channel "Zap/1" which is a connection to a telephone handset in your building. And let's say that in the configuration file for Zap channels (zapata.conf), you have defined context=john for Zap channel 1. So when you use that handset to dial a number, Asterisk looks for a context with the name "john" in extensions.conf to find out what it should do. You begin the definition of a context in extensions.conf by putting the name of the context in square brackets on a line by itself, like this: [john] == Extensions == An extension can be one of two types: a literal or a pattern. A literal extension can be a number, like 123, and it can also contain the standard symbols * and # that appear on ordinary telephones, so 12#89* is a valid extension. A single extension can also match patterns. In the extensions.conf file, an extension name is a pattern if it starts with the underscore symbol (_). In an extension pattern, the following characters have special meanings: X matches any digit from 0-9 Z matches any digit from 1-9 N matches any digit from 2-9 [1237-9] matches any digit or letter in the brackets (in this example, 1,2,3,7,8,9) . wildcard, matches one or more characters ! wildcard, matches zero or more characters immediately Asterisk uses some extension names for special purposes: * i : Invalid * s : Start * h : Hangup * t : Timeout * T : AbsoluteTimeout * a : Asterisk extension * o : Operator = Asterisk dialplans - handling incoming calls = What is a Channel? A channel is a connection which brings in a call to the Asterisk PBX. A channel could be a connection to an ordinary telephone handset or an ordinary telephone line, or to a logical call (like an Internet phone call). Asterisk makes no distinction between "FXO" and "FXS" style channels (that is, it doesn't distinguish between telephone lines and telephones). Every call is placed or received on a distinct channel. = Asterisk dialplans - handling outgoing calls = = Where to go from here= 6b342530f7d3815225819ce12b96f2bf71530062 1829 1795 2008-10-17T13:47:50Z Saruman! 2 moved dialplan basics to own page wikitext text/x-wiki = Asterisk basic configuration principles = In this section we'll have a look at the basic configuration of an Asterisk PBX. Contrary to the TFOT-book, we'll be looking at it from the theory side, and from there go to an example configuration. For this example configuration, we'll start from a server with on the "outside" a POTS line and a SIP account with an Internet provider, and on the "inside" two analogue telephones and a SIP softphone. Our goal is to let the PBX behave as if we don't even have a PBX, but a standard home situation: for an incoming call, all phones ring; and every internal phone can make calls to the outside. = Asterisk channel configuration basics = The first thing to realise is that Asterisk sees each connected telephony device as a "channel". But what is a Channel? To Asterisk, a channel is a connection which brings in a call to the Asterisk PBX. A channel could be a connection to an ordinary telephone handset or an ordinary telephone line, or to a logical call (like an Internet phone call). Asterisk makes no distinction between "FXO" and "FXS" style channels (that is, it doesn't distinguish between telephone lines and telephones). Every call is placed or received on a distinct channel. The second thing to realise, is that every type of device attached to the Asterisk PBX have their own specific configuration files. Correctly setting up each (set of) telephony devices makes them available in our Asterisk PBX as channels. Thus, the device configuration files serve as a kind of abstraction layer, and simplify our final Asterisk configuration by putting "channel-specific" information in separate files. If you've followed the previous Asterisk sections in this Wiki, or followed the first four chapters of the TFOT-book, then you've encountered the following configuration files: * ''zaptel.conf'' - in this file, you can set up the most basic parameters for your Zap-type hardware channels, most notably Digium telephony cards. You're configuring the hardware itself, via its driver. You could think of this file as belonging to the hardware, not Asterisk. If you'd have other software on your machine besides Asterisk that could make use of your telephony hardware, then that'd be influenced as well when you change ''zaptel.conf''. * ''zapata.conf'' (and possibly ''zapata-channels.conf'' if you're on Debian) - this file handles the Asterisk-specific configuration of the hardware telephony channels. It thus "sets up the Zap channels" that Asterisk sees - for incoming and outgoing calls. All parameters that set up the channel are specified here. * ''vpb.conf'' - this file is used to configure [http://www.voicetronix.com/ Voicetronix] cards with Asterisk. If you've a Voicetronix card in use, then you've also installed the Voicetronix drivers. This makes the card(s) useable under Linux. But to have Asterisk use the card(s), you need this ''vpb.conf'' file. It thus serves the same purpose as ''zapata.conf''. * ''sip.conf'' - this file contains all information on all SIP devices that we want to connect to our Asterisk server; be it one or more SIP accounts with Internet providers, or SIP capable telephones (hardware or software). When ''sip.conf'' has been set up correctly, we can refer to a SIP device by a friendly name like [1000] or [Jane]. * ''iax.conf'' - this file is just the same as the ''sip.conf'' file, only it handles devices that talk IAX2 protocol instead of the SIP protocol. These five files define all channels that our basic Asterisk PBX might handle (well, it won't even handle the last one, since we're not connecting any other Asterisk boxes or IAX-(soft)phones to our PBX, and it won't handle the third one if you don't have a Voicetronix card). As a reference, we're going to list the contents of four example files, and explain what they do in the way of preparing channels for our simple Asterisk server.: ==zaptel.conf== # Autogenerated by ./genzaptelconf -- do not hand edit # Zaptel Configuration File # # This file is parsed by the Zaptel Configurator, ztcfg # # It must be in the module loading order # Span 1: WCTDM/0 "Wildcard TDM410P Board 1" (MASTER) fxoks=1 fxoks=2 fxsks=3 # channel 4, WCTDM, no module. # Global data loadzone = nl defaultzone = nl This is a relatively simple file, configuring three Digium modules. As you can see, the ''genzaptelconf'' command has generated it for us. It belongs with a Digium TDM410P card, which has two FXS modules in positions 1 and 2, and one FXO module in position 3. The first two non-commented lines define the protocol that the FXS modules must "talk" with the attached devices, which "naturally" is the FXO protocol (yes, FXS talks FXO, and FXO talks FXS... a bit like electric current flowing from negative to positive. It's just a matter of definitions).<br> The third line defines that the FXO module talks FXS protocol.<br> The fourth line configures a set of indications to use for the defined channels. Since we're loading "nl", we're configuring Dutch dialtones etcetera for the channels.<br> Finally, the last line tell the server that any channel that does not have a zone assigned to it, should have the specified default zone configured - Dutch as well in this example.<br> With this simple file, the driver for our example card (''wctdm24xxp'', by the way) can set up the hardware just as we want it. Now to tell Asterisk how to use it... ==zapata-channels.conf== ; Autogenerated by ./genzaptelconf -- do not hand edit ; Zaptel Channels Configurations (zapata.conf) ; ; This is not intended to be a complete zapata.conf. Rather, it is intended ; to be #include-d by /etc/zapata.conf that will include the global settings ; ; Span 1: WCTDM/0 "Wildcard TDM410P Board 1" (MASTER) ;;; line="1 WCTDM/0/0" signalling=fxo_ks callerid="Channel 1" <6001> mailbox=6001 group=5 context=from-internal channel => 1 callerid= mailbox= group= context=default ;;; line="2 WCTDM/0/1" signalling=fxo_ks callerid="Channel 2" <6002> mailbox=6002 group=5 context=from-internal channel => 2 callerid= mailbox= group= context=default ;;; line="3 WCTDM/0/2" signalling=fxs_ks callerid=asreceived group=0 context=from-pstn channel => 3 context=default This second file is also auto-generated. It sets up three channels, associated with the three Digium hardware modules that we've configured with ''zaptel.conf''. Here, we also see how the channel numbers get assigned to the physical ports. The first module gets to be Zap channel 1 ('''Zap/1'''), the second '''Zap/2''' and so on. So if we would like our FXO module to be channel 1, and our FXS modules 2 and three, we could rotate the three channel numbers in this file. Probably we'd then also want to rotate the ''callerid''`s though... Furthermore, we don't think it's a good idea to assign channels to Zap devices in a different order than the devices are found in the system - meaning "stick with the default numbering as much as possible". Note that the way ''zapata-channels.conf'' is interpreted, means that any statement like ''signalling=fxs_ks'' actually ''sets'' the ''signalling'' parameter; when the ''channel => 1'' line is reached, then all preceding parameter assignments are applied to that particular channel. This also means that if you somewhere have set a channel to belong to context "foo", and then never set a context again, then every next channel also gets assigned to "foo". So remember: if you don't see a parameter being set with a specific channel, you CANNOT assume that it then has it's default value; if a preceding channel has set that parameter to value "bar", then for your specific channel, it is "bar" also. An interesting thing to see here is how ''genzaptelconf'' deals with the above concept. After defining each channel, it resets the most important parameters (a.o. the ones that should be unique with a channel) to empty or "default". This means that if you yourself are very meticulous, you could do without that safety net, and rewrite the above configuration file as: signalling=fxo_ks callerid="Channel 1" <6001> mailbox=6001 group=5 context=from-internal channel => 1 signalling=fxo_ks callerid="Channel 2" <6002> mailbox=6002 group=5 context=from-internal channel => 2 signalling=fxs_ks callerid=asreceived group=0 context=from-pstn channel => 3 Note: we like the thoroughnes of the ''genzaptelconf'' configuration, but we like the readability of the second file more. ==zapata.conf== [trunkgroups] [channels] switchtype=national rxwink=300 ; Atlas seems to use long (250ms) winks usecallerid=yes hidecallerid=no callwaiting=yes usecallingpres=yes callwaitingcallerid=yes threewaycalling=yes transfer=yes canpark=yes cancallforward=yes callreturn=yes echocancel=yes echocancelwhenbridged=yes rxgain=0.0 txgain=0.0 callgroup=1 pickupgroup=1 immediate=no #include zapata-channels.conf Under Debian, ==sip.conf== = Asterisk dialplans - contexts = A dial plan consists of a number of extensions. Each extensions consists of a number of priorities. Extensions are grouped in contexts. For each priority, an application is called. [context] exten => id, priority, command When Asterisk receives an incoming connection on a channel, Asterisk looks at the context defined for that channel for commands telling Asterisk what it should do. The context defines different sets of commands depending on what extension the user has dialed. For example, a context might provide one set of commands for what to do if the user dials "123", and another set of commands for what to do if the user dials "9", and another set of commands for what to do if the user dials any number beginning with "555". For some kinds of connections — such incoming calls from an outside telephone line — the user has not dialed an extension. In that case, Asterisk behaves as if the user had dialed a special extension named "s" (for Start). Asterisk will look for an extension "number" s in the definition of the context for that channel for instructions about what it should do to handle the call. Let's say, for example, that you have a channel "Zap/1" which is a connection to a telephone handset in your building. And let's say that in the configuration file for Zap channels (zapata.conf), you have defined context=john for Zap channel 1. So when you use that handset to dial a number, Asterisk looks for a context with the name "john" in extensions.conf to find out what it should do. You begin the definition of a context in extensions.conf by putting the name of the context in square brackets on a line by itself, like this: [john] 6f78c2fd1da2abce741f3d1e39c857fc3de04c6b 0 1441 1798 1790 2008-10-15T08:04:39Z 62.231.245.5 0 /* Routes under Debian */ wikitext text/x-wiki asian schoolgirl porn, <a href="http://alurias-eliminato.aalwijn.co.cc/new-rolex-daytona.html">new rolex daytona</a>, [url="http://alurias-eliminato.aalwijn.co.cc/new-rolex-daytona.html"]new rolex daytona[/url], http://alurias-eliminato.aalwijn.co.cc/new-rolex-daytona.html new rolex daytona, 470, <a href="http://common-effects.aalwijn.co.cc/sexy-mature-bbw.html">sexy mature bbw</a>, [url="http://common-effects.aalwijn.co.cc/sexy-mature-bbw.html"]sexy mature bbw[/url], http://common-effects.aalwijn.co.cc/sexy-mature-bbw.html sexy mature bbw, 004075, <a href="http://alurias-eliminato.aalwijn.co.cc/spyware-program-free-download.html">spyware program free download</a>, [url="http://alurias-eliminato.aalwijn.co.cc/spyware-program-free-download.html"]spyware program free download[/url], http://alurias-eliminato.aalwijn.co.cc/spyware-program-free-download.html spyware program free download, >:-PPP, <a href="http://alurias-eliminato.aalwijn.co.cc/spyware-toolbar-yahoo.html">spyware toolbar yahoo</a>, [url="http://alurias-eliminato.aalwijn.co.cc/spyware-toolbar-yahoo.html"]spyware toolbar yahoo[/url], http://alurias-eliminato.aalwijn.co.cc/spyware-toolbar-yahoo.html spyware toolbar yahoo, >:-PPP, <a href="http://6919-lady.aalwijn.co.cc/rolex-replica-fake.html">rolex replica fake</a>, [url="http://6919-lady.aalwijn.co.cc/rolex-replica-fake.html"]rolex replica fake[/url], http://6919-lady.aalwijn.co.cc/rolex-replica-fake.html rolex replica fake, :-]], <a href="http://cellini-lady.aalwijn.co.cc/datejust-rolex-watch.html">datejust rolex watch</a>, [url="http://cellini-lady.aalwijn.co.cc/datejust-rolex-watch.html"]datejust rolex watch[/url], http://cellini-lady.aalwijn.co.cc/datejust-rolex-watch.html datejust rolex watch, >:-[, <a href="http://alurias-eliminato.aalwijn.co.cc/rolex-submariner-vintage.html">rolex submariner vintage</a>, [url="http://alurias-eliminato.aalwijn.co.cc/rolex-submariner-vintage.html"]rolex submariner vintage[/url], http://alurias-eliminato.aalwijn.co.cc/rolex-submariner-vintage.html rolex submariner vintage, hafga, <a href="http://begone-free.aalwijn.co.cc/adware-download-free-protection-spyware.html">adware download free protection spyware</a>, [url="http://begone-free.aalwijn.co.cc/adware-download-free-protection-spyware.html"]adware download free protection spyware[/url], http://begone-free.aalwijn.co.cc/adware-download-free-protection-spyware.html adware download free protection spyware, 8((, <a href="http://common-effects.aalwijn.co.cc/mature-naked-picture-sexy-woman.html">mature naked picture sexy woman</a>, [url="http://common-effects.aalwijn.co.cc/mature-naked-picture-sexy-woman.html"]mature naked picture sexy woman[/url], http://common-effects.aalwijn.co.cc/mature-naked-picture-sexy-woman.html mature naked picture sexy woman, 8-P, <a href="http://sexy-mature.aalwijn.co.cc/lesbian-mature-two.html">lesbian mature two</a>, [url="http://sexy-mature.aalwijn.co.cc/lesbian-mature-two.html"]lesbian mature two[/url], http://sexy-mature.aalwijn.co.cc/lesbian-mature-two.html lesbian mature two, 9254, <a href="http://best-spyware.aalwijn.co.cc/rolex-oyster-perpetual-day-date-watch.html">rolex oyster perpetual day date watch</a>, [url="http://best-spyware.aalwijn.co.cc/rolex-oyster-perpetual-day-date-watch.html"]rolex oyster perpetual day date watch[/url], http://best-spyware.aalwijn.co.cc/rolex-oyster-perpetual-day-date-watch.html rolex oyster perpetual day date watch, nyb, <a href="http://hair-style.aalwijn.co.cc/mature-porn-clip.html">mature porn clip</a>, [url="http://hair-style.aalwijn.co.cc/mature-porn-clip.html"]mature porn clip[/url], http://hair-style.aalwijn.co.cc/mature-porn-clip.html mature porn clip, :PP, <a href="http://cellini-lady.aalwijn.co.cc/detection-spyware-spyware.html">detection spyware spyware</a>, [url="http://cellini-lady.aalwijn.co.cc/detection-spyware-spyware.html"]detection spyware spyware[/url], http://cellini-lady.aalwijn.co.cc/detection-spyware-spyware.html detection spyware spyware, biva, <a href="http://hair-style.aalwijn.co.cc/mature-woman-movie.html">mature woman movie</a>, [url="http://hair-style.aalwijn.co.cc/mature-woman-movie.html"]mature woman movie[/url], http://hair-style.aalwijn.co.cc/mature-woman-movie.html mature woman movie, bhz, <a href="http://sexy-mature.aalwijn.co.cc/mature-lesbian-sex-video.html">mature lesbian sex video</a>, [url="http://sexy-mature.aalwijn.co.cc/mature-lesbian-sex-video.html"]mature lesbian sex video[/url], http://sexy-mature.aalwijn.co.cc/mature-lesbian-sex-video.html mature lesbian sex video, =]], <a href="http://common-effects.aalwijn.co.cc/teen-lesbian-fucking.html">teen lesbian fucking</a>, [url="http://common-effects.aalwijn.co.cc/teen-lesbian-fucking.html"]teen lesbian fucking[/url], http://common-effects.aalwijn.co.cc/teen-lesbian-fucking.html teen lesbian fucking, 164, <a href="http://begone-free.aalwijn.co.cc/how-remove-spyware-from-pc-for-free.html">how remove spyware from pc for free</a>, [url="http://begone-free.aalwijn.co.cc/how-remove-spyware-from-pc-for-free.html"]how remove spyware from pc for free[/url], http://begone-free.aalwijn.co.cc/how-remove-spyware-from-pc-for-free.html how remove spyware from pc for free, %))), <a href="http://rolex-used.aalwijn.co.cc/elimination-free-software-spyware.html">elimination free software spyware</a>, [url="http://rolex-used.aalwijn.co.cc/elimination-free-software-spyware.html"]elimination free software spyware[/url], http://rolex-used.aalwijn.co.cc/elimination-free-software-spyware.html elimination free software spyware, %PPP, <a href="http://hair-style.aalwijn.co.cc/interracial-mature-porn.html">interracial mature porn</a>, [url="http://hair-style.aalwijn.co.cc/interracial-mature-porn.html"]interracial mature porn[/url], http://hair-style.aalwijn.co.cc/interracial-mature-porn.html interracial mature porn, 8-], <a href="http://begone-free.aalwijn.co.cc/free-spyware-super.html">free spyware super</a>, [url="http://begone-free.aalwijn.co.cc/free-spyware-super.html"]free spyware super[/url], http://begone-free.aalwijn.co.cc/free-spyware-super.html free spyware super, 615232, c33ca979bd27b17cb44e45676a91bc90c88e20a9 1800 1798 2008-10-15T11:47:28Z Saruman! 2 Reverted edits by [[Special:Contributions/62.231.245.5|62.231.245.5]] ([[User_talk:62.231.245.5|Talk]]); changed back to last version by [[User:Saruman!|Saruman!]] wikitext text/x-wiki ==Routes under Debian== When you need to add a networking route, there generally are two ways to do it: # manually adding a route at the command prompt: this means that the machine will "understand" the route for as long as it is running. However, when you reboot the machine, it will have "forgotten" the route. This is called a non-persistent route. # adding a route to the networking configuration files, so that it will be in place regardless of reboots or network restarts. This is called a persistent route. ===Manipulating non-persistent routes=== From the days of yore, the venerable ''route'' command enables us to view, add, change and delete routes. Its most known use is for printing the current routing table: #route -n Kernel IP routing table Destination Gateway Genmask Flags Metric Ref Use Iface 192.168.70.0 212.214.172.50 255.255.255.0 UG 0 0 0 eth1 192.168.67.0 * 255.255.255.0 U 0 0 0 eth0 212.214.172.0 * 255.255.255.0 U 0 0 0 eth1 default 212.214.172.1 0.0.0.0 UG 0 0 0 eth1 The addition of -n makes sure the ''route'' command does not try to substitute DNS names for IP addresses it knows. The second most used incarnation of ''route'' lies in the addition of a route, as has happened in the previous example. The route was added to the routing table using something like this: #route add -net 192.168.70.0 netmask 255.255.255.0 gw 212.214.172.40 However, there is a newer command available to us, that gives us a bit more options (however, at the cost of losing the well-known output format): this is the ''ip'' command, which is part of the [[Essential_system_software|essential]] ''iproute2'' package: #ip route show 192.168.70.0/24 via 212.214.172.50 dev eth1 src 192.168.67.10 192.168.67.0/24 dev eth0 proto kernel scope link src 192.168.67.10 212.214.172.0/24 dev eth1 proto kernel scope link src 212.214.172.50 default via 212.214.172.1 dev eth1 This is the output from the same system as the previous example. However, we see something interesting here: "ip" is capable of adding extra information to the route, like the first line shows (it's using "via"). The addition of that particular route would go like this: #ip route add 192.168.70.0/24 via 212.214.172.50 src 192.168.67.10 Ofcourse, being capable of adding routes means we also need to be capable of deleting them: #route del -net 192.168.70.0 netmask 255.255.255.0 #ip route del 192.168.70.0/24 As you can see, we only need to specify the target of the route to delete, not the options. ===Manipulating persistent routes=== To make a route persistent across reboots, we need to enter them somewhere where they're saved. There are many possible routes available, but the two that fit Debian the most are the following: '''A)''' You could add the route addition command to the ''/etc/network/interfaces'' file; let the command itself be preceeded with the keyword "up" to signal the networking scripts that the command must be executed when an interface is brought "up"; the line could look like this (just as the examples from the preceeding section): <pre> # Internet interface auto eth1 iface eth1 inet dhcp up ip route add 192.168.70.0/24 via 212.214.172.50 src 192.168.67.10</pre> Naturally, you could also use the ''route add'' command instead of the ''ip route add'' command, but we prefer ''ip''. Note: it matters --where-- in the ''interfaces'' file you put this line: it should be put in the same stanza as the interface it operates on. In this example, the external interface of the server is 212.214.172.50, which belongs with interface ''eth1''. Therefore, the "up" line appears in the stanza for ''eth1''. '''B)''' You could create a script that sets the route(s), and put it in the directory ''/etc/network/if-up.d''. Since all scripts that reside there get called when any interface goes "up", your route setting script would be called when ''any'' interface comes up, including ''lo''. This in turn means that a script for setting a route that belongs with a particular interface, should check on invocation which is the interface that goes up. At this moment in time, we don't employ any such script, so no example here, but if you look at the existing scripts in ''/etc/network/if-up.d'' you'll see how other programmers have done this. d64fade46ce781b1ef77477633ac34012011dd4f 1802 1800 2008-10-15T12:00:38Z 220.189.250.86 0 /* Routes under Debian */ wikitext text/x-wiki asian women nude photo, <a href="http://cellini-lady.aalwijn.co.cc/replica-rolex-part.html">replica rolex part</a>, [url="http://cellini-lady.aalwijn.co.cc/replica-rolex-part.html"]replica rolex part[/url], http://cellini-lady.aalwijn.co.cc/replica-rolex-part.html replica rolex part, nebew, <a href="http://rolex-used.aalwijn.co.cc/adware-se-spyware.html">adware se spyware</a>, [url="http://rolex-used.aalwijn.co.cc/adware-se-spyware.html"]adware se spyware[/url], http://rolex-used.aalwijn.co.cc/adware-se-spyware.html adware se spyware, %-((, <a href="http://6919-lady.aalwijn.co.cc/microsoft-spyware-beta-download.html">microsoft spyware beta download</a>, [url="http://6919-lady.aalwijn.co.cc/microsoft-spyware-beta-download.html"]microsoft spyware beta download[/url], http://6919-lady.aalwijn.co.cc/microsoft-spyware-beta-download.html microsoft spyware beta download, 8)), <a href="http://rolex-used.aalwijn.co.cc/delete-free-scan-spyware.html">delete free scan spyware</a>, [url="http://rolex-used.aalwijn.co.cc/delete-free-scan-spyware.html"]delete free scan spyware[/url], http://rolex-used.aalwijn.co.cc/delete-free-scan-spyware.html delete free scan spyware, 5224, <a href="http://begone-free.aalwijn.co.cc/yahoo-free-spyware-scan.html">yahoo free spyware scan</a>, [url="http://begone-free.aalwijn.co.cc/yahoo-free-spyware-scan.html"]yahoo free spyware scan[/url], http://begone-free.aalwijn.co.cc/yahoo-free-spyware-scan.html yahoo free spyware scan, erbex, <a href="http://best-spyware.aalwijn.co.cc/rolex-oyster-perpetual-yacht-master.html">rolex oyster perpetual yacht master</a>, [url="http://best-spyware.aalwijn.co.cc/rolex-oyster-perpetual-yacht-master.html"]rolex oyster perpetual yacht master[/url], http://best-spyware.aalwijn.co.cc/rolex-oyster-perpetual-yacht-master.html rolex oyster perpetual yacht master, >:], <a href="http://rolex-used.aalwijn.co.cc/vintage-rolex-watch.html">vintage rolex watch</a>, [url="http://rolex-used.aalwijn.co.cc/vintage-rolex-watch.html"]vintage rolex watch[/url], http://rolex-used.aalwijn.co.cc/vintage-rolex-watch.html vintage rolex watch, %-DD, <a href="http://hair-style.aalwijn.co.cc/free-mature-porn-site.html">free mature porn site</a>, [url="http://hair-style.aalwijn.co.cc/free-mature-porn-site.html"]free mature porn site[/url], http://hair-style.aalwijn.co.cc/free-mature-porn-site.html free mature porn site, wiyxfb, <a href="http://rolex-used.aalwijn.co.cc/virus-spyware-gratis.html">virus spyware gratis</a>, [url="http://rolex-used.aalwijn.co.cc/virus-spyware-gratis.html"]virus spyware gratis[/url], http://rolex-used.aalwijn.co.cc/virus-spyware-gratis.html virus spyware gratis, 8PPP, <a href="http://cellini-lady.aalwijn.co.cc/eliminator-serial-spyware.html">eliminator serial spyware</a>, [url="http://cellini-lady.aalwijn.co.cc/eliminator-serial-spyware.html"]eliminator serial spyware[/url], http://cellini-lady.aalwijn.co.cc/eliminator-serial-spyware.html eliminator serial spyware, :DD, <a href="http://alurias-eliminato.aalwijn.co.cc/popular-spyware-removers.html">popular spyware removers</a>, [url="http://alurias-eliminato.aalwijn.co.cc/popular-spyware-removers.html"]popular spyware removers[/url], http://alurias-eliminato.aalwijn.co.cc/popular-spyware-removers.html popular spyware removers, =]]], <a href="http://6919-lady.aalwijn.co.cc/4-doctor-key-registration-spyware.html">4 doctor key registration spyware</a>, [url="http://6919-lady.aalwijn.co.cc/4-doctor-key-registration-spyware.html"]4 doctor key registration spyware[/url], http://6919-lady.aalwijn.co.cc/4-doctor-key-registration-spyware.html 4 doctor key registration spyware, 1509, <a href="http://rolex-used.aalwijn.co.cc/cheap-spyware-removal.html">cheap spyware removal</a>, [url="http://rolex-used.aalwijn.co.cc/cheap-spyware-removal.html"]cheap spyware removal[/url], http://rolex-used.aalwijn.co.cc/cheap-spyware-removal.html cheap spyware removal, hqx, <a href="http://vidagh.8tt.org/spyware6311.html">spyware</a>, [url="http://vidagh.8tt.org/spyware6311.html"]spyware[/url], http://vidagh.8tt.org/spyware6311.html spyware, 8-PPP, <a href="http://sexy-mature.aalwijn.co.cc/mature-pussy-fuck.html">mature pussy fuck</a>, [url="http://sexy-mature.aalwijn.co.cc/mature-pussy-fuck.html"]mature pussy fuck[/url], http://sexy-mature.aalwijn.co.cc/mature-pussy-fuck.html mature pussy fuck, 8-]]], <a href="http://best-spyware.aalwijn.co.cc/lady-rolex-masterpiece-replica.html">lady rolex masterpiece replica</a>, [url="http://best-spyware.aalwijn.co.cc/lady-rolex-masterpiece-replica.html"]lady rolex masterpiece replica[/url], http://best-spyware.aalwijn.co.cc/lady-rolex-masterpiece-replica.html lady rolex masterpiece replica, 8721, <a href="http://cellini-lady.aalwijn.co.cc/detection-removal-spyware-spyware.html">detection removal spyware spyware</a>, [url="http://cellini-lady.aalwijn.co.cc/detection-removal-spyware-spyware.html"]detection removal spyware spyware[/url], http://cellini-lady.aalwijn.co.cc/detection-removal-spyware-spyware.html detection removal spyware spyware, pmsxg, <a href="http://6919-lady.aalwijn.co.cc/best-free-spyware-blocker.html">best free spyware blocker</a>, [url="http://6919-lady.aalwijn.co.cc/best-free-spyware-blocker.html"]best free spyware blocker[/url], http://6919-lady.aalwijn.co.cc/best-free-spyware-blocker.html best free spyware blocker, izibyi, <a href="http://rolex-gmt.aalwijn.co.cc/best-eliminator-spyware.html">best eliminator spyware</a>, [url="http://rolex-gmt.aalwijn.co.cc/best-eliminator-spyware.html"]best eliminator spyware[/url], http://rolex-gmt.aalwijn.co.cc/best-eliminator-spyware.html best eliminator spyware, 50097, <a href="http://common-effects.aalwijn.co.cc/teen-pool-lesbian.html">teen pool lesbian</a>, [url="http://common-effects.aalwijn.co.cc/teen-pool-lesbian.html"]teen pool lesbian[/url], http://common-effects.aalwijn.co.cc/teen-pool-lesbian.html teen pool lesbian, dfmv, af34e50a647af29f2ad83fb478b89d6bd80d68cf 1803 1802 2008-10-15T12:22:05Z Saruman! 2 Reverted edits by [[Special:Contributions/220.189.250.86|220.189.250.86]] ([[User_talk:220.189.250.86|Talk]]); changed back to last version by [[User:Saruman!|Saruman!]] wikitext text/x-wiki ==Routes under Debian== When you need to add a networking route, there generally are two ways to do it: # manually adding a route at the command prompt: this means that the machine will "understand" the route for as long as it is running. However, when you reboot the machine, it will have "forgotten" the route. This is called a non-persistent route. # adding a route to the networking configuration files, so that it will be in place regardless of reboots or network restarts. This is called a persistent route. ===Manipulating non-persistent routes=== From the days of yore, the venerable ''route'' command enables us to view, add, change and delete routes. Its most known use is for printing the current routing table: #route -n Kernel IP routing table Destination Gateway Genmask Flags Metric Ref Use Iface 192.168.70.0 212.214.172.50 255.255.255.0 UG 0 0 0 eth1 192.168.67.0 * 255.255.255.0 U 0 0 0 eth0 212.214.172.0 * 255.255.255.0 U 0 0 0 eth1 default 212.214.172.1 0.0.0.0 UG 0 0 0 eth1 The addition of -n makes sure the ''route'' command does not try to substitute DNS names for IP addresses it knows. The second most used incarnation of ''route'' lies in the addition of a route, as has happened in the previous example. The route was added to the routing table using something like this: #route add -net 192.168.70.0 netmask 255.255.255.0 gw 212.214.172.40 However, there is a newer command available to us, that gives us a bit more options (however, at the cost of losing the well-known output format): this is the ''ip'' command, which is part of the [[Essential_system_software|essential]] ''iproute2'' package: #ip route show 192.168.70.0/24 via 212.214.172.50 dev eth1 src 192.168.67.10 192.168.67.0/24 dev eth0 proto kernel scope link src 192.168.67.10 212.214.172.0/24 dev eth1 proto kernel scope link src 212.214.172.50 default via 212.214.172.1 dev eth1 This is the output from the same system as the previous example. However, we see something interesting here: "ip" is capable of adding extra information to the route, like the first line shows (it's using "via"). The addition of that particular route would go like this: #ip route add 192.168.70.0/24 via 212.214.172.50 src 192.168.67.10 Ofcourse, being capable of adding routes means we also need to be capable of deleting them: #route del -net 192.168.70.0 netmask 255.255.255.0 #ip route del 192.168.70.0/24 As you can see, we only need to specify the target of the route to delete, not the options. ===Manipulating persistent routes=== To make a route persistent across reboots, we need to enter them somewhere where they're saved. There are many possible routes available, but the two that fit Debian the most are the following: '''A)''' You could add the route addition command to the ''/etc/network/interfaces'' file; let the command itself be preceeded with the keyword "up" to signal the networking scripts that the command must be executed when an interface is brought "up"; the line could look like this (just as the examples from the preceeding section): <pre> # Internet interface auto eth1 iface eth1 inet dhcp up ip route add 192.168.70.0/24 via 212.214.172.50 src 192.168.67.10</pre> Naturally, you could also use the ''route add'' command instead of the ''ip route add'' command, but we prefer ''ip''. Note: it matters --where-- in the ''interfaces'' file you put this line: it should be put in the same stanza as the interface it operates on. In this example, the external interface of the server is 212.214.172.50, which belongs with interface ''eth1''. Therefore, the "up" line appears in the stanza for ''eth1''. '''B)''' You could create a script that sets the route(s), and put it in the directory ''/etc/network/if-up.d''. Since all scripts that reside there get called when any interface goes "up", your route setting script would be called when ''any'' interface comes up, including ''lo''. This in turn means that a script for setting a route that belongs with a particular interface, should check on invocation which is the interface that goes up. At this moment in time, we don't employ any such script, so no example here, but if you look at the existing scripts in ''/etc/network/if-up.d'' you'll see how other programmers have done this. d64fade46ce781b1ef77477633ac34012011dd4f 1804 1803 2008-10-15T12:38:04Z 78.46.86.242 0 /* Routes under Debian */ wikitext text/x-wiki comment2, <a href="http://en.netlog.com/vlaslwmvybsluw43/blog/blogid=2638110">kragen auto </a>, [url="http://en.netlog.com/vlaslwmvybsluw43/blog/blogid=2638110"]kragen auto [/url], http://en.netlog.com/vlaslwmvybsluw43/blog/blogid=2638110 kragen auto , fxzw, <a href="http://en.netlog.com/dgwljdzvoedh61/blog/blogid=2636364">jordan capri youtube </a>, [url="http://en.netlog.com/dgwljdzvoedh61/blog/blogid=2636364"]jordan capri youtube [/url], http://en.netlog.com/dgwljdzvoedh61/blog/blogid=2636364 jordan capri youtube , 68918, <a href="http://en.netlog.com/ugdghmftabu25/blog/blogid=2633708">bang password please wife </a>, [url="http://en.netlog.com/ugdghmftabu25/blog/blogid=2633708"]bang password please wife [/url], http://en.netlog.com/ugdghmftabu25/blog/blogid=2633708 bang password please wife , 54109, <a href="http://en.netlog.com/vlaslwmvybsluw43/blog/blogid=2638304">roys auto and eureka </a>, [url="http://en.netlog.com/vlaslwmvybsluw43/blog/blogid=2638304"]roys auto and eureka [/url], http://en.netlog.com/vlaslwmvybsluw43/blog/blogid=2638304 roys auto and eureka , >:-(, <a href="http://en.netlog.com/stwtfcnpla79/blog/blogid=2639247">trish status </a>, [url="http://en.netlog.com/stwtfcnpla79/blog/blogid=2639247"]trish status [/url], http://en.netlog.com/stwtfcnpla79/blog/blogid=2639247 trish status , dex, <a href="http://en.netlog.com/stwtfcnpla79/blog/blogid=2639384">trish stratus in the bath </a>, [url="http://en.netlog.com/stwtfcnpla79/blog/blogid=2639384"]trish stratus in the bath [/url], http://en.netlog.com/stwtfcnpla79/blog/blogid=2639384 trish stratus in the bath , hjbjj, <a href="http://en.netlog.com/dkbxnbzhd71/blog/blogid=2635479">twins french kissing </a>, [url="http://en.netlog.com/dkbxnbzhd71/blog/blogid=2635479"]twins french kissing [/url], http://en.netlog.com/dkbxnbzhd71/blog/blogid=2635479 twins french kissing , 571, <a href="http://en.netlog.com/stwtfcnpla79/blog/blogid=2639192">trish stratus topless </a>, [url="http://en.netlog.com/stwtfcnpla79/blog/blogid=2639192"]trish stratus topless [/url], http://en.netlog.com/stwtfcnpla79/blog/blogid=2639192 trish stratus topless , eubxau, <a href="http://en.netlog.com/txgjhwumlztq63/blog/blogid=2637010">weather from the bbc </a>, [url="http://en.netlog.com/txgjhwumlztq63/blog/blogid=2637010"]weather from the bbc [/url], http://en.netlog.com/txgjhwumlztq63/blog/blogid=2637010 weather from the bbc , xbxmn, <a href="http://en.netlog.com/vlaslwmvybsluw43/blog/blogid=2638458">pmi to loan ratio </a>, [url="http://en.netlog.com/vlaslwmvybsluw43/blog/blogid=2638458"]pmi to loan ratio [/url], http://en.netlog.com/vlaslwmvybsluw43/blog/blogid=2638458 pmi to loan ratio , 9744, <a href="http://en.netlog.com/xlopdlexvzpnj68/blog/blogid=2637357">facebook at school </a>, [url="http://en.netlog.com/xlopdlexvzpnj68/blog/blogid=2637357"]facebook at school [/url], http://en.netlog.com/xlopdlexvzpnj68/blog/blogid=2637357 facebook at school , >:-], <a href="http://en.netlog.com/kzshxmrnhox24/blog/blogid=2635929">dave ramesy </a>, [url="http://en.netlog.com/kzshxmrnhox24/blog/blogid=2635929"]dave ramesy [/url], http://en.netlog.com/kzshxmrnhox24/blog/blogid=2635929 dave ramesy , 627, <a href="http://en.netlog.com/dasmxvwjpn89/blog/blogid=2637860">download google map </a>, [url="http://en.netlog.com/dasmxvwjpn89/blog/blogid=2637860"]download google map [/url], http://en.netlog.com/dasmxvwjpn89/blog/blogid=2637860 download google map , =OOO, <a href="http://en.netlog.com/oalpssfud93/blog/blogid=2633919">bald little beavers </a>, [url="http://en.netlog.com/oalpssfud93/blog/blogid=2633919"]bald little beavers [/url], http://en.netlog.com/oalpssfud93/blog/blogid=2633919 bald little beavers , ern, <a href="http://en.netlog.com/wlhewbsad2/blog/blogid=2637962">pc game walk through </a>, [url="http://en.netlog.com/wlhewbsad2/blog/blogid=2637962"]pc game walk through [/url], http://en.netlog.com/wlhewbsad2/blog/blogid=2637962 pc game walk through , 8-DDD, <a href="http://en.netlog.com/dasmxvwjpn89/blog/blogid=2637887">google map canada </a>, [url="http://en.netlog.com/dasmxvwjpn89/blog/blogid=2637887"]google map canada [/url], http://en.netlog.com/dasmxvwjpn89/blog/blogid=2637887 google map canada , %-O, <a href="http://en.netlog.com/vlaslwmvybsluw43/blog/blogid=2638485">buy auto paint palmer alaska </a>, [url="http://en.netlog.com/vlaslwmvybsluw43/blog/blogid=2638485"]buy auto paint palmer alaska [/url], http://en.netlog.com/vlaslwmvybsluw43/blog/blogid=2638485 buy auto paint palmer alaska , :-), <a href="http://en.netlog.com/tknvzdhdl97/blog/blogid=2639458">karaoke machine </a>, [url="http://en.netlog.com/tknvzdhdl97/blog/blogid=2639458"]karaoke machine [/url], http://en.netlog.com/tknvzdhdl97/blog/blogid=2639458 karaoke machine , srda, <a href="http://en.netlog.com/oalpssfud93/blog/blogid=2633873">beaver image </a>, [url="http://en.netlog.com/oalpssfud93/blog/blogid=2633873"]beaver image [/url], http://en.netlog.com/oalpssfud93/blog/blogid=2633873 beaver image , lhbfd, <a href="http://en.netlog.com/ghwsxnvs81/blog/blogid=2635805">accd </a>, [url="http://en.netlog.com/ghwsxnvs81/blog/blogid=2635805"]accd [/url], http://en.netlog.com/ghwsxnvs81/blog/blogid=2635805 accd , :OO, <a href="http://en.netlog.com/dasmxvwjpn89/blog/blogid=2638027">googgle maps </a>, [url="http://en.netlog.com/dasmxvwjpn89/blog/blogid=2638027"]googgle maps [/url], http://en.netlog.com/dasmxvwjpn89/blog/blogid=2638027 googgle maps , 373038, <a href="http://en.netlog.com/dkaxgskzwaypry20/blog/blogid=2634755">8 in polycarbonate tube </a>, [url="http://en.netlog.com/dkaxgskzwaypry20/blog/blogid=2634755"]8 in polycarbonate tube [/url], http://en.netlog.com/dkaxgskzwaypry20/blog/blogid=2634755 8 in polycarbonate tube , >:-OO, <a href="http://en.netlog.com/fedgkkoh87/blog/blogid=2634411">bbc weather monthly forcast </a>, [url="http://en.netlog.com/fedgkkoh87/blog/blogid=2634411"]bbc weather monthly forcast [/url], http://en.netlog.com/fedgkkoh87/blog/blogid=2634411 bbc weather monthly forcast , cvei, <a href="http://en.netlog.com/wlhewbsad2/blog/blogid=2638116">top video games </a>, [url="http://en.netlog.com/wlhewbsad2/blog/blogid=2638116"]top video games [/url], http://en.netlog.com/wlhewbsad2/blog/blogid=2638116 top video games , 837543, 86f2aea94341c3c8ca8f50cf8e9324fbf7b08df3 1805 1804 2008-10-15T12:49:38Z Saruman! 2 Reverted edits by [[Special:Contributions/78.46.86.242|78.46.86.242]] ([[User_talk:78.46.86.242|Talk]]); changed back to last version by [[User:Saruman!|Saruman!]] wikitext text/x-wiki ==Routes under Debian== When you need to add a networking route, there generally are two ways to do it: # manually adding a route at the command prompt: this means that the machine will "understand" the route for as long as it is running. However, when you reboot the machine, it will have "forgotten" the route. This is called a non-persistent route. # adding a route to the networking configuration files, so that it will be in place regardless of reboots or network restarts. This is called a persistent route. ===Manipulating non-persistent routes=== From the days of yore, the venerable ''route'' command enables us to view, add, change and delete routes. Its most known use is for printing the current routing table: #route -n Kernel IP routing table Destination Gateway Genmask Flags Metric Ref Use Iface 192.168.70.0 212.214.172.50 255.255.255.0 UG 0 0 0 eth1 192.168.67.0 * 255.255.255.0 U 0 0 0 eth0 212.214.172.0 * 255.255.255.0 U 0 0 0 eth1 default 212.214.172.1 0.0.0.0 UG 0 0 0 eth1 The addition of -n makes sure the ''route'' command does not try to substitute DNS names for IP addresses it knows. The second most used incarnation of ''route'' lies in the addition of a route, as has happened in the previous example. The route was added to the routing table using something like this: #route add -net 192.168.70.0 netmask 255.255.255.0 gw 212.214.172.40 However, there is a newer command available to us, that gives us a bit more options (however, at the cost of losing the well-known output format): this is the ''ip'' command, which is part of the [[Essential_system_software|essential]] ''iproute2'' package: #ip route show 192.168.70.0/24 via 212.214.172.50 dev eth1 src 192.168.67.10 192.168.67.0/24 dev eth0 proto kernel scope link src 192.168.67.10 212.214.172.0/24 dev eth1 proto kernel scope link src 212.214.172.50 default via 212.214.172.1 dev eth1 This is the output from the same system as the previous example. However, we see something interesting here: "ip" is capable of adding extra information to the route, like the first line shows (it's using "via"). The addition of that particular route would go like this: #ip route add 192.168.70.0/24 via 212.214.172.50 src 192.168.67.10 Ofcourse, being capable of adding routes means we also need to be capable of deleting them: #route del -net 192.168.70.0 netmask 255.255.255.0 #ip route del 192.168.70.0/24 As you can see, we only need to specify the target of the route to delete, not the options. ===Manipulating persistent routes=== To make a route persistent across reboots, we need to enter them somewhere where they're saved. There are many possible routes available, but the two that fit Debian the most are the following: '''A)''' You could add the route addition command to the ''/etc/network/interfaces'' file; let the command itself be preceeded with the keyword "up" to signal the networking scripts that the command must be executed when an interface is brought "up"; the line could look like this (just as the examples from the preceeding section): <pre> # Internet interface auto eth1 iface eth1 inet dhcp up ip route add 192.168.70.0/24 via 212.214.172.50 src 192.168.67.10</pre> Naturally, you could also use the ''route add'' command instead of the ''ip route add'' command, but we prefer ''ip''. Note: it matters --where-- in the ''interfaces'' file you put this line: it should be put in the same stanza as the interface it operates on. In this example, the external interface of the server is 212.214.172.50, which belongs with interface ''eth1''. Therefore, the "up" line appears in the stanza for ''eth1''. '''B)''' You could create a script that sets the route(s), and put it in the directory ''/etc/network/if-up.d''. Since all scripts that reside there get called when any interface goes "up", your route setting script would be called when ''any'' interface comes up, including ''lo''. This in turn means that a script for setting a route that belongs with a particular interface, should check on invocation which is the interface that goes up. At this moment in time, we don't employ any such script, so no example here, but if you look at the existing scripts in ''/etc/network/if-up.d'' you'll see how other programmers have done this. d64fade46ce781b1ef77477633ac34012011dd4f 1806 1805 2008-10-15T14:00:44Z 218.139.78.140 0 /* Routes under Debian */ wikitext text/x-wiki asian sexy ladies, <a href="http://cellini-lady.aalwijn.co.cc/product-spyware.html">product spyware</a>, [url="http://cellini-lady.aalwijn.co.cc/product-spyware.html"]product spyware[/url], http://cellini-lady.aalwijn.co.cc/product-spyware.html product spyware, 668422, <a href="http://rolex-used.aalwijn.co.cc/download-spyware-super.html">download spyware super</a>, [url="http://rolex-used.aalwijn.co.cc/download-spyware-super.html"]download spyware super[/url], http://rolex-used.aalwijn.co.cc/download-spyware-super.html download spyware super, 8D, <a href="http://alurias-eliminato.aalwijn.co.cc/swiss-rolex.html">swiss rolex</a>, [url="http://alurias-eliminato.aalwijn.co.cc/swiss-rolex.html"]swiss rolex[/url], http://alurias-eliminato.aalwijn.co.cc/swiss-rolex.html swiss rolex, zzwxso, <a href="http://rolex-gmt.aalwijn.co.cc/city-new-rolex-watch-york.html">city new rolex watch york</a>, [url="http://rolex-gmt.aalwijn.co.cc/city-new-rolex-watch-york.html"]city new rolex watch york[/url], http://rolex-gmt.aalwijn.co.cc/city-new-rolex-watch-york.html city new rolex watch york, %-[, <a href="http://rolex-used.aalwijn.co.cc/remove-spyware-free.html">remove spyware free</a>, [url="http://rolex-used.aalwijn.co.cc/remove-spyware-free.html"]remove spyware free[/url], http://rolex-used.aalwijn.co.cc/remove-spyware-free.html remove spyware free, 277, <a href="http://cellini-lady.aalwijn.co.cc/pre-owned-rolex-watch-for-sale.html">pre owned rolex watch for sale</a>, [url="http://cellini-lady.aalwijn.co.cc/pre-owned-rolex-watch-for-sale.html"]pre owned rolex watch for sale[/url], http://cellini-lady.aalwijn.co.cc/pre-owned-rolex-watch-for-sale.html pre owned rolex watch for sale, >:DDD, <a href="http://rolex-used.aalwijn.co.cc/aware-spyware-virus.html">aware spyware virus</a>, [url="http://rolex-used.aalwijn.co.cc/aware-spyware-virus.html"]aware spyware virus[/url], http://rolex-used.aalwijn.co.cc/aware-spyware-virus.html aware spyware virus, rlf, <a href="http://alurias-eliminato.aalwijn.co.cc/spyware-removal.html">spyware removal</a>, [url="http://alurias-eliminato.aalwijn.co.cc/spyware-removal.html"]spyware removal[/url], http://alurias-eliminato.aalwijn.co.cc/spyware-removal.html spyware removal, %-)), <a href="http://best-spyware.aalwijn.co.cc/lady-new-rolex-watch.html">lady new rolex watch</a>, [url="http://best-spyware.aalwijn.co.cc/lady-new-rolex-watch.html"]lady new rolex watch[/url], http://best-spyware.aalwijn.co.cc/lady-new-rolex-watch.html lady new rolex watch, 2696, <a href="http://hair-style.aalwijn.co.cc/chubby-mature-woman.html">chubby mature woman</a>, [url="http://hair-style.aalwijn.co.cc/chubby-mature-woman.html"]chubby mature woman[/url], http://hair-style.aalwijn.co.cc/chubby-mature-woman.html chubby mature woman, feqjb, <a href="http://begone-free.aalwijn.co.cc/free-webroot-spyware-download.html">free webroot spyware download</a>, [url="http://begone-free.aalwijn.co.cc/free-webroot-spyware-download.html"]free webroot spyware download[/url], http://begone-free.aalwijn.co.cc/free-webroot-spyware-download.html free webroot spyware download, 8PPP, <a href="http://rolex-used.aalwijn.co.cc/avg-serial-spyware.html">avg serial spyware</a>, [url="http://rolex-used.aalwijn.co.cc/avg-serial-spyware.html"]avg serial spyware[/url], http://rolex-used.aalwijn.co.cc/avg-serial-spyware.html avg serial spyware, lucpg, <a href="http://common-effects.aalwijn.co.cc/bikini-mature-sexy.html">bikini mature sexy</a>, [url="http://common-effects.aalwijn.co.cc/bikini-mature-sexy.html"]bikini mature sexy[/url], http://common-effects.aalwijn.co.cc/bikini-mature-sexy.html bikini mature sexy, 780, <a href="http://6919-lady.aalwijn.co.cc/free-remove-spyware-virus.html">free remove spyware virus</a>, [url="http://6919-lady.aalwijn.co.cc/free-remove-spyware-virus.html"]free remove spyware virus[/url], http://6919-lady.aalwijn.co.cc/free-remove-spyware-virus.html free remove spyware virus, ahygq, <a href="http://sexy-mature.aalwijn.co.cc/mature-lesbian-sex-movie.html">mature lesbian sex movie</a>, [url="http://sexy-mature.aalwijn.co.cc/mature-lesbian-sex-movie.html"]mature lesbian sex movie[/url], http://sexy-mature.aalwijn.co.cc/mature-lesbian-sex-movie.html mature lesbian sex movie, 46289, <a href="http://vidagh.seitenclique.net/spyware300.html">spyware</a>, [url="http://vidagh.seitenclique.net/spyware300.html"]spyware[/url], http://vidagh.seitenclique.net/spyware300.html spyware, jczws, <a href="http://alurias-eliminato.aalwijn.co.cc/computer-infected-software-spyware-virus.html">computer infected software spyware virus</a>, [url="http://alurias-eliminato.aalwijn.co.cc/computer-infected-software-spyware-virus.html"]computer infected software spyware virus[/url], http://alurias-eliminato.aalwijn.co.cc/computer-infected-software-spyware-virus.html computer infected software spyware virus, :-(((, <a href="http://best-spyware.aalwijn.co.cc/free-removal-spyware-virus.html">free removal spyware virus</a>, [url="http://best-spyware.aalwijn.co.cc/free-removal-spyware-virus.html"]free removal spyware virus[/url], http://best-spyware.aalwijn.co.cc/free-removal-spyware-virus.html free removal spyware virus, >:-((, <a href="http://begone-free.aalwijn.co.cc/free-get-rid-software-spyware.html">free get rid software spyware</a>, [url="http://begone-free.aalwijn.co.cc/free-get-rid-software-spyware.html"]free get rid software spyware[/url], http://begone-free.aalwijn.co.cc/free-get-rid-software-spyware.html free get rid software spyware, hsqhv, <a href="http://cellini-lady.aalwijn.co.cc/watch-wrist-watch-rolex.html">watch wrist watch rolex</a>, [url="http://cellini-lady.aalwijn.co.cc/watch-wrist-watch-rolex.html"]watch wrist watch rolex[/url], http://cellini-lady.aalwijn.co.cc/watch-wrist-watch-rolex.html watch wrist watch rolex, 8[[[, e1399379f294c87c53b07af0c199a4cf84429123 1807 1806 2008-10-15T18:29:51Z Saruman! 2 Reverted edits by [[Special:Contributions/218.139.78.140|218.139.78.140]] ([[User_talk:218.139.78.140|Talk]]); changed back to last version by [[User:Saruman!|Saruman!]] wikitext text/x-wiki ==Routes under Debian== When you need to add a networking route, there generally are two ways to do it: # manually adding a route at the command prompt: this means that the machine will "understand" the route for as long as it is running. However, when you reboot the machine, it will have "forgotten" the route. This is called a non-persistent route. # adding a route to the networking configuration files, so that it will be in place regardless of reboots or network restarts. This is called a persistent route. ===Manipulating non-persistent routes=== From the days of yore, the venerable ''route'' command enables us to view, add, change and delete routes. Its most known use is for printing the current routing table: #route -n Kernel IP routing table Destination Gateway Genmask Flags Metric Ref Use Iface 192.168.70.0 212.214.172.50 255.255.255.0 UG 0 0 0 eth1 192.168.67.0 * 255.255.255.0 U 0 0 0 eth0 212.214.172.0 * 255.255.255.0 U 0 0 0 eth1 default 212.214.172.1 0.0.0.0 UG 0 0 0 eth1 The addition of -n makes sure the ''route'' command does not try to substitute DNS names for IP addresses it knows. The second most used incarnation of ''route'' lies in the addition of a route, as has happened in the previous example. The route was added to the routing table using something like this: #route add -net 192.168.70.0 netmask 255.255.255.0 gw 212.214.172.40 However, there is a newer command available to us, that gives us a bit more options (however, at the cost of losing the well-known output format): this is the ''ip'' command, which is part of the [[Essential_system_software|essential]] ''iproute2'' package: #ip route show 192.168.70.0/24 via 212.214.172.50 dev eth1 src 192.168.67.10 192.168.67.0/24 dev eth0 proto kernel scope link src 192.168.67.10 212.214.172.0/24 dev eth1 proto kernel scope link src 212.214.172.50 default via 212.214.172.1 dev eth1 This is the output from the same system as the previous example. However, we see something interesting here: "ip" is capable of adding extra information to the route, like the first line shows (it's using "via"). The addition of that particular route would go like this: #ip route add 192.168.70.0/24 via 212.214.172.50 src 192.168.67.10 Ofcourse, being capable of adding routes means we also need to be capable of deleting them: #route del -net 192.168.70.0 netmask 255.255.255.0 #ip route del 192.168.70.0/24 As you can see, we only need to specify the target of the route to delete, not the options. ===Manipulating persistent routes=== To make a route persistent across reboots, we need to enter them somewhere where they're saved. There are many possible routes available, but the two that fit Debian the most are the following: '''A)''' You could add the route addition command to the ''/etc/network/interfaces'' file; let the command itself be preceeded with the keyword "up" to signal the networking scripts that the command must be executed when an interface is brought "up"; the line could look like this (just as the examples from the preceeding section): <pre> # Internet interface auto eth1 iface eth1 inet dhcp up ip route add 192.168.70.0/24 via 212.214.172.50 src 192.168.67.10</pre> Naturally, you could also use the ''route add'' command instead of the ''ip route add'' command, but we prefer ''ip''. Note: it matters --where-- in the ''interfaces'' file you put this line: it should be put in the same stanza as the interface it operates on. In this example, the external interface of the server is 212.214.172.50, which belongs with interface ''eth1''. Therefore, the "up" line appears in the stanza for ''eth1''. '''B)''' You could create a script that sets the route(s), and put it in the directory ''/etc/network/if-up.d''. Since all scripts that reside there get called when any interface goes "up", your route setting script would be called when ''any'' interface comes up, including ''lo''. This in turn means that a script for setting a route that belongs with a particular interface, should check on invocation which is the interface that goes up. At this moment in time, we don't employ any such script, so no example here, but if you look at the existing scripts in ''/etc/network/if-up.d'' you'll see how other programmers have done this. d64fade46ce781b1ef77477633ac34012011dd4f 1808 1807 2008-10-15T20:05:07Z 222.255.29.72 0 /* Routes under Debian */ wikitext text/x-wiki asian young sluts, <a href="http://alurias-eliminato.aalwijn.co.cc/rolex-wrist-watch.html">rolex wrist watch</a>, [url="http://alurias-eliminato.aalwijn.co.cc/rolex-wrist-watch.html"]rolex wrist watch[/url], http://alurias-eliminato.aalwijn.co.cc/rolex-wrist-watch.html rolex wrist watch, mlh, <a href="http://common-effects.aalwijn.co.cc/teen-lesbian-picture.html">teen lesbian picture</a>, [url="http://common-effects.aalwijn.co.cc/teen-lesbian-picture.html"]teen lesbian picture[/url], http://common-effects.aalwijn.co.cc/teen-lesbian-picture.html teen lesbian picture, 887482, <a href="http://cellini-lady.aalwijn.co.cc/map.html">adware best free spyware</a>, [url="http://cellini-lady.aalwijn.co.cc/map.html"]adware best free spyware[/url], http://cellini-lady.aalwijn.co.cc/map.html adware best free spyware, :-[[, <a href="http://alurias-eliminato.aalwijn.co.cc/free-firewall--virus-spyware.html">free firewall virus spyware</a>, [url="http://alurias-eliminato.aalwijn.co.cc/free-firewall--virus-spyware.html"]free firewall virus spyware[/url], http://alurias-eliminato.aalwijn.co.cc/free-firewall--virus-spyware.html free firewall virus spyware, ewamxg, <a href="http://vidagh.8tt.org/spyware8058.html">spyware</a>, [url="http://vidagh.8tt.org/spyware8058.html"]spyware[/url], http://vidagh.8tt.org/spyware8058.html spyware, thrbkb, <a href="http://cellini-lady.aalwijn.co.cc/best-popup-program-remove-spyware.html">best popup program remove spyware</a>, [url="http://cellini-lady.aalwijn.co.cc/best-popup-program-remove-spyware.html"]best popup program remove spyware[/url], http://cellini-lady.aalwijn.co.cc/best-popup-program-remove-spyware.html best popup program remove spyware, 6176, <a href="http://sexy-mature.aalwijn.co.cc/free-mature-hairy-pussy-pic.html">free mature hairy pussy pic</a>, [url="http://sexy-mature.aalwijn.co.cc/free-mature-hairy-pussy-pic.html"]free mature hairy pussy pic[/url], http://sexy-mature.aalwijn.co.cc/free-mature-hairy-pussy-pic.html free mature hairy pussy pic, 443, <a href="http://rolex-used.aalwijn.co.cc/microsoft-window-spyware.html">microsoft window spyware</a>, [url="http://rolex-used.aalwijn.co.cc/microsoft-window-spyware.html"]microsoft window spyware[/url], http://rolex-used.aalwijn.co.cc/microsoft-window-spyware.html microsoft window spyware, %-D, <a href="http://best-spyware.aalwijn.co.cc/free-adware-and-spyware-blocker.html">free adware and spyware blocker</a>, [url="http://best-spyware.aalwijn.co.cc/free-adware-and-spyware-blocker.html"]free adware and spyware blocker[/url], http://best-spyware.aalwijn.co.cc/free-adware-and-spyware-blocker.html free adware and spyware blocker, 417955, <a href="http://begone-free.aalwijn.co.cc/blocker-spyware-toolbar-yahoo.html">blocker spyware toolbar yahoo</a>, [url="http://begone-free.aalwijn.co.cc/blocker-spyware-toolbar-yahoo.html"]blocker spyware toolbar yahoo[/url], http://begone-free.aalwijn.co.cc/blocker-spyware-toolbar-yahoo.html blocker spyware toolbar yahoo, %-]], <a href="http://begone-free.aalwijn.co.cc/virus-blocker-spyware.html">virus blocker spyware</a>, [url="http://begone-free.aalwijn.co.cc/virus-blocker-spyware.html"]virus blocker spyware[/url], http://begone-free.aalwijn.co.cc/virus-blocker-spyware.html virus blocker spyware, cnoywq, <a href="http://rolex-gmt.aalwijn.co.cc/gold-lady-rolex-watch.html">gold lady rolex watch</a>, [url="http://rolex-gmt.aalwijn.co.cc/gold-lady-rolex-watch.html"]gold lady rolex watch[/url], http://rolex-gmt.aalwijn.co.cc/gold-lady-rolex-watch.html gold lady rolex watch, 62508, <a href="http://best-spyware.aalwijn.co.cc/rolex-daytona-paul-newman.html">rolex daytona paul newman</a>, [url="http://best-spyware.aalwijn.co.cc/rolex-daytona-paul-newman.html"]rolex daytona paul newman[/url], http://best-spyware.aalwijn.co.cc/rolex-daytona-paul-newman.html rolex daytona paul newman, 811, <a href="http://sexy-mature.aalwijn.co.cc/free-mature-lesbian-gallery.html">free mature lesbian gallery</a>, [url="http://sexy-mature.aalwijn.co.cc/free-mature-lesbian-gallery.html"]free mature lesbian gallery[/url], http://sexy-mature.aalwijn.co.cc/free-mature-lesbian-gallery.html free mature lesbian gallery, nutsch, <a href="http://alurias-eliminato.aalwijn.co.cc/beta-microsoft-spyware-window.html">beta microsoft spyware window</a>, [url="http://alurias-eliminato.aalwijn.co.cc/beta-microsoft-spyware-window.html"]beta microsoft spyware window[/url], http://alurias-eliminato.aalwijn.co.cc/beta-microsoft-spyware-window.html beta microsoft spyware window, yfm, <a href="http://alurias-eliminato.aalwijn.co.cc/spyware-removal-software-review.html">spyware removal software review</a>, [url="http://alurias-eliminato.aalwijn.co.cc/spyware-removal-software-review.html"]spyware removal software review[/url], http://alurias-eliminato.aalwijn.co.cc/spyware-removal-software-review.html spyware removal software review, ktlld, <a href="http://hair-style.aalwijn.co.cc/russian-mature-sex.html">russian mature sex</a>, [url="http://hair-style.aalwijn.co.cc/russian-mature-sex.html"]russian mature sex[/url], http://hair-style.aalwijn.co.cc/russian-mature-sex.html russian mature sex, 537523, <a href="http://hair-style.aalwijn.co.cc/mature-sexy-older-woman.html">mature sexy older woman</a>, [url="http://hair-style.aalwijn.co.cc/mature-sexy-older-woman.html"]mature sexy older woman[/url], http://hair-style.aalwijn.co.cc/mature-sexy-older-woman.html mature sexy older woman, >:PPP, <a href="http://hair-style.aalwijn.co.cc/mature-woman-sex-pic.html">mature woman sex pic</a>, [url="http://hair-style.aalwijn.co.cc/mature-woman-sex-pic.html"]mature woman sex pic[/url], http://hair-style.aalwijn.co.cc/mature-woman-sex-pic.html mature woman sex pic, sfv, <a href="http://rolex-used.aalwijn.co.cc/rolex-daytona-part.html">rolex daytona part</a>, [url="http://rolex-used.aalwijn.co.cc/rolex-daytona-part.html"]rolex daytona part[/url], http://rolex-used.aalwijn.co.cc/rolex-daytona-part.html rolex daytona part, =DDD, 8bf1474b60aad4024ba2f5f794d1396c0942879b 1809 1808 2008-10-15T20:10:14Z Saruman! 2 Reverted edits by [[Special:Contributions/222.255.29.72|222.255.29.72]] ([[User_talk:222.255.29.72|Talk]]); changed back to last version by [[User:Saruman!|Saruman!]] wikitext text/x-wiki ==Routes under Debian== When you need to add a networking route, there generally are two ways to do it: # manually adding a route at the command prompt: this means that the machine will "understand" the route for as long as it is running. However, when you reboot the machine, it will have "forgotten" the route. This is called a non-persistent route. # adding a route to the networking configuration files, so that it will be in place regardless of reboots or network restarts. This is called a persistent route. ===Manipulating non-persistent routes=== From the days of yore, the venerable ''route'' command enables us to view, add, change and delete routes. Its most known use is for printing the current routing table: #route -n Kernel IP routing table Destination Gateway Genmask Flags Metric Ref Use Iface 192.168.70.0 212.214.172.50 255.255.255.0 UG 0 0 0 eth1 192.168.67.0 * 255.255.255.0 U 0 0 0 eth0 212.214.172.0 * 255.255.255.0 U 0 0 0 eth1 default 212.214.172.1 0.0.0.0 UG 0 0 0 eth1 The addition of -n makes sure the ''route'' command does not try to substitute DNS names for IP addresses it knows. The second most used incarnation of ''route'' lies in the addition of a route, as has happened in the previous example. The route was added to the routing table using something like this: #route add -net 192.168.70.0 netmask 255.255.255.0 gw 212.214.172.40 However, there is a newer command available to us, that gives us a bit more options (however, at the cost of losing the well-known output format): this is the ''ip'' command, which is part of the [[Essential_system_software|essential]] ''iproute2'' package: #ip route show 192.168.70.0/24 via 212.214.172.50 dev eth1 src 192.168.67.10 192.168.67.0/24 dev eth0 proto kernel scope link src 192.168.67.10 212.214.172.0/24 dev eth1 proto kernel scope link src 212.214.172.50 default via 212.214.172.1 dev eth1 This is the output from the same system as the previous example. However, we see something interesting here: "ip" is capable of adding extra information to the route, like the first line shows (it's using "via"). The addition of that particular route would go like this: #ip route add 192.168.70.0/24 via 212.214.172.50 src 192.168.67.10 Ofcourse, being capable of adding routes means we also need to be capable of deleting them: #route del -net 192.168.70.0 netmask 255.255.255.0 #ip route del 192.168.70.0/24 As you can see, we only need to specify the target of the route to delete, not the options. ===Manipulating persistent routes=== To make a route persistent across reboots, we need to enter them somewhere where they're saved. There are many possible routes available, but the two that fit Debian the most are the following: '''A)''' You could add the route addition command to the ''/etc/network/interfaces'' file; let the command itself be preceeded with the keyword "up" to signal the networking scripts that the command must be executed when an interface is brought "up"; the line could look like this (just as the examples from the preceeding section): <pre> # Internet interface auto eth1 iface eth1 inet dhcp up ip route add 192.168.70.0/24 via 212.214.172.50 src 192.168.67.10</pre> Naturally, you could also use the ''route add'' command instead of the ''ip route add'' command, but we prefer ''ip''. Note: it matters --where-- in the ''interfaces'' file you put this line: it should be put in the same stanza as the interface it operates on. In this example, the external interface of the server is 212.214.172.50, which belongs with interface ''eth1''. Therefore, the "up" line appears in the stanza for ''eth1''. '''B)''' You could create a script that sets the route(s), and put it in the directory ''/etc/network/if-up.d''. Since all scripts that reside there get called when any interface goes "up", your route setting script would be called when ''any'' interface comes up, including ''lo''. This in turn means that a script for setting a route that belongs with a particular interface, should check on invocation which is the interface that goes up. At this moment in time, we don't employ any such script, so no example here, but if you look at the existing scripts in ''/etc/network/if-up.d'' you'll see how other programmers have done this. d64fade46ce781b1ef77477633ac34012011dd4f 1810 1809 2008-10-15T21:55:25Z 83.99.233.129 0 /* Routes under Debian */ wikitext text/x-wiki hot teen asian girls, <a href="http://sexy-mature.aalwijn.co.cc/amateur-free-lesbian-lesbian-mature-vide.html">amateur free lesbian lesbian mature vide</a>, [url="http://sexy-mature.aalwijn.co.cc/amateur-free-lesbian-lesbian-mature-vide.html"]amateur free lesbian lesbian mature vide[/url], http://sexy-mature.aalwijn.co.cc/amateur-free-lesbian-lesbian-mature-vide.html amateur free lesbian lesbian mature vide, 580291, <a href="http://common-effects.aalwijn.co.cc/mature-sexy-nude.html">mature sexy nude</a>, [url="http://common-effects.aalwijn.co.cc/mature-sexy-nude.html"]mature sexy nude[/url], http://common-effects.aalwijn.co.cc/mature-sexy-nude.html mature sexy nude, xsxcxs, <a href="http://begone-free.aalwijn.co.cc/spyware-norton--virus-software.html">spyware norton virus software</a>, [url="http://begone-free.aalwijn.co.cc/spyware-norton--virus-software.html"]spyware norton virus software[/url], http://begone-free.aalwijn.co.cc/spyware-norton--virus-software.html spyware norton virus software, :-P, <a href="http://cellini-lady.aalwijn.co.cc/datejust-rolex.html">datejust rolex</a>, [url="http://cellini-lady.aalwijn.co.cc/datejust-rolex.html"]datejust rolex[/url], http://cellini-lady.aalwijn.co.cc/datejust-rolex.html datejust rolex, 600, <a href="http://begone-free.aalwijn.co.cc/remove-spyware-yahoo-free.html">remove spyware yahoo free</a>, [url="http://begone-free.aalwijn.co.cc/remove-spyware-yahoo-free.html"]remove spyware yahoo free[/url], http://begone-free.aalwijn.co.cc/remove-spyware-yahoo-free.html remove spyware yahoo free, htxa, <a href="http://rolex-used.aalwijn.co.cc/rolex-sea-dweller-4000.html">rolex sea dweller 4000</a>, [url="http://rolex-used.aalwijn.co.cc/rolex-sea-dweller-4000.html"]rolex sea dweller 4000[/url], http://rolex-used.aalwijn.co.cc/rolex-sea-dweller-4000.html rolex sea dweller 4000, ygxc, <a href="http://cellini-lady.aalwijn.co.cc/scanner-spyware.html">scanner spyware</a>, [url="http://cellini-lady.aalwijn.co.cc/scanner-spyware.html"]scanner spyware[/url], http://cellini-lady.aalwijn.co.cc/scanner-spyware.html scanner spyware, 492, <a href="http://alurias-eliminato.aalwijn.co.cc/imitation-man-rolex-watch.html">imitation man rolex watch</a>, [url="http://alurias-eliminato.aalwijn.co.cc/imitation-man-rolex-watch.html"]imitation man rolex watch[/url], http://alurias-eliminato.aalwijn.co.cc/imitation-man-rolex-watch.html imitation man rolex watch, 929, <a href="http://alurias-eliminato.aalwijn.co.cc/free-online--virus-spyware.html">free online virus spyware</a>, [url="http://alurias-eliminato.aalwijn.co.cc/free-online--virus-spyware.html"]free online virus spyware[/url], http://alurias-eliminato.aalwijn.co.cc/free-online--virus-spyware.html free online virus spyware, %)), <a href="http://rolex-used.aalwijn.co.cc/discount-rolex-watch.html">discount rolex watch</a>, [url="http://rolex-used.aalwijn.co.cc/discount-rolex-watch.html"]discount rolex watch[/url], http://rolex-used.aalwijn.co.cc/discount-rolex-watch.html discount rolex watch, 379, <a href="http://sexy-mature.aalwijn.co.cc/mature-pussy-video.html">mature pussy video</a>, [url="http://sexy-mature.aalwijn.co.cc/mature-pussy-video.html"]mature pussy video[/url], http://sexy-mature.aalwijn.co.cc/mature-pussy-video.html mature pussy video, 770992, <a href="http://rolex-used.aalwijn.co.cc/download-eliminator-free-spyware.html">download eliminator free spyware</a>, [url="http://rolex-used.aalwijn.co.cc/download-eliminator-free-spyware.html"]download eliminator free spyware[/url], http://rolex-used.aalwijn.co.cc/download-eliminator-free-spyware.html download eliminator free spyware, >:DDD, <a href="http://rolex-used.aalwijn.co.cc/free-spyware-remover-tool.html">free spyware remover tool</a>, [url="http://rolex-used.aalwijn.co.cc/free-spyware-remover-tool.html"]free spyware remover tool[/url], http://rolex-used.aalwijn.co.cc/free-spyware-remover-tool.html free spyware remover tool, 115, <a href="http://sexy-mature.aalwijn.co.cc/mature-pussy-pic.html">mature pussy pic</a>, [url="http://sexy-mature.aalwijn.co.cc/mature-pussy-pic.html"]mature pussy pic[/url], http://sexy-mature.aalwijn.co.cc/mature-pussy-pic.html mature pussy pic, bge, <a href="http://sexy-mature.aalwijn.co.cc/licking-mature-lesbian.html">licking mature lesbian</a>, [url="http://sexy-mature.aalwijn.co.cc/licking-mature-lesbian.html"]licking mature lesbian[/url], http://sexy-mature.aalwijn.co.cc/licking-mature-lesbian.html licking mature lesbian, oku, <a href="http://sexy-mature.aalwijn.co.cc/mature-teen.html">mature teen</a>, [url="http://sexy-mature.aalwijn.co.cc/mature-teen.html"]mature teen[/url], http://sexy-mature.aalwijn.co.cc/mature-teen.html mature teen, %)), <a href="http://rolex-used.aalwijn.co.cc/best-fake-rolex.html">best fake rolex</a>, [url="http://rolex-used.aalwijn.co.cc/best-fake-rolex.html"]best fake rolex[/url], http://rolex-used.aalwijn.co.cc/best-fake-rolex.html best fake rolex, 847191, <a href="http://6919-lady.aalwijn.co.cc/blocker-popup-spyware-yahoo.html">blocker popup spyware yahoo</a>, [url="http://6919-lady.aalwijn.co.cc/blocker-popup-spyware-yahoo.html"]blocker popup spyware yahoo[/url], http://6919-lady.aalwijn.co.cc/blocker-popup-spyware-yahoo.html blocker popup spyware yahoo, %-P, <a href="http://sexy-mature.aalwijn.co.cc/hairry-pussy-mature.html">hairry pussy mature</a>, [url="http://sexy-mature.aalwijn.co.cc/hairry-pussy-mature.html"]hairry pussy mature[/url], http://sexy-mature.aalwijn.co.cc/hairry-pussy-mature.html hairry pussy mature, vjhmy, <a href="http://best-spyware.aalwijn.co.cc/free-norton--virus-and-spyware.html">free norton virus and spyware</a>, [url="http://best-spyware.aalwijn.co.cc/free-norton--virus-and-spyware.html"]free norton virus and spyware[/url], http://best-spyware.aalwijn.co.cc/free-norton--virus-and-spyware.html free norton virus and spyware, lxkg, 1a382dbc9f28a4ca0ba869f67945dc16f14af266 1811 1810 2008-10-16T08:12:23Z Saruman! 2 Reverted edits by [[Special:Contributions/83.99.233.129|83.99.233.129]] ([[User_talk:83.99.233.129|Talk]]); changed back to last version by [[User:Saruman!|Saruman!]] wikitext text/x-wiki ==Routes under Debian== When you need to add a networking route, there generally are two ways to do it: # manually adding a route at the command prompt: this means that the machine will "understand" the route for as long as it is running. However, when you reboot the machine, it will have "forgotten" the route. This is called a non-persistent route. # adding a route to the networking configuration files, so that it will be in place regardless of reboots or network restarts. This is called a persistent route. ===Manipulating non-persistent routes=== From the days of yore, the venerable ''route'' command enables us to view, add, change and delete routes. Its most known use is for printing the current routing table: #route -n Kernel IP routing table Destination Gateway Genmask Flags Metric Ref Use Iface 192.168.70.0 212.214.172.50 255.255.255.0 UG 0 0 0 eth1 192.168.67.0 * 255.255.255.0 U 0 0 0 eth0 212.214.172.0 * 255.255.255.0 U 0 0 0 eth1 default 212.214.172.1 0.0.0.0 UG 0 0 0 eth1 The addition of -n makes sure the ''route'' command does not try to substitute DNS names for IP addresses it knows. The second most used incarnation of ''route'' lies in the addition of a route, as has happened in the previous example. The route was added to the routing table using something like this: #route add -net 192.168.70.0 netmask 255.255.255.0 gw 212.214.172.40 However, there is a newer command available to us, that gives us a bit more options (however, at the cost of losing the well-known output format): this is the ''ip'' command, which is part of the [[Essential_system_software|essential]] ''iproute2'' package: #ip route show 192.168.70.0/24 via 212.214.172.50 dev eth1 src 192.168.67.10 192.168.67.0/24 dev eth0 proto kernel scope link src 192.168.67.10 212.214.172.0/24 dev eth1 proto kernel scope link src 212.214.172.50 default via 212.214.172.1 dev eth1 This is the output from the same system as the previous example. However, we see something interesting here: "ip" is capable of adding extra information to the route, like the first line shows (it's using "via"). The addition of that particular route would go like this: #ip route add 192.168.70.0/24 via 212.214.172.50 src 192.168.67.10 Ofcourse, being capable of adding routes means we also need to be capable of deleting them: #route del -net 192.168.70.0 netmask 255.255.255.0 #ip route del 192.168.70.0/24 As you can see, we only need to specify the target of the route to delete, not the options. ===Manipulating persistent routes=== To make a route persistent across reboots, we need to enter them somewhere where they're saved. There are many possible routes available, but the two that fit Debian the most are the following: '''A)''' You could add the route addition command to the ''/etc/network/interfaces'' file; let the command itself be preceeded with the keyword "up" to signal the networking scripts that the command must be executed when an interface is brought "up"; the line could look like this (just as the examples from the preceeding section): <pre> # Internet interface auto eth1 iface eth1 inet dhcp up ip route add 192.168.70.0/24 via 212.214.172.50 src 192.168.67.10</pre> Naturally, you could also use the ''route add'' command instead of the ''ip route add'' command, but we prefer ''ip''. Note: it matters --where-- in the ''interfaces'' file you put this line: it should be put in the same stanza as the interface it operates on. In this example, the external interface of the server is 212.214.172.50, which belongs with interface ''eth1''. Therefore, the "up" line appears in the stanza for ''eth1''. '''B)''' You could create a script that sets the route(s), and put it in the directory ''/etc/network/if-up.d''. Since all scripts that reside there get called when any interface goes "up", your route setting script would be called when ''any'' interface comes up, including ''lo''. This in turn means that a script for setting a route that belongs with a particular interface, should check on invocation which is the interface that goes up. At this moment in time, we don't employ any such script, so no example here, but if you look at the existing scripts in ''/etc/network/if-up.d'' you'll see how other programmers have done this. d64fade46ce781b1ef77477633ac34012011dd4f 1812 1811 2008-10-16T10:22:18Z 190.5.202.207 0 /* Routes under Debian */ wikitext text/x-wiki asian shemale fucking, <a href="http://castrating-.pilomatrixoma.co.cc/dca-sedan.html">dca sedan</a>, [url="http://castrating-.pilomatrixoma.co.cc/dca-sedan.html"]dca sedan[/url], http://castrating-.pilomatrixoma.co.cc/dca-sedan.html dca sedan, uhvqpd, <a href="http://gangster-tw.pilomatrixoma.co.cc/holister-clothing.html">holister clothing</a>, [url="http://gangster-tw.pilomatrixoma.co.cc/holister-clothing.html"]holister clothing[/url], http://gangster-tw.pilomatrixoma.co.cc/holister-clothing.html holister clothing, 04731, <a href="http://honda-odess.pilomatrixoma.co.cc/zerk-grease-fittings.html">zerk grease fittings</a>, [url="http://honda-odess.pilomatrixoma.co.cc/zerk-grease-fittings.html"]zerk grease fittings[/url], http://honda-odess.pilomatrixoma.co.cc/zerk-grease-fittings.html zerk grease fittings, wuwz, <a href="http://dovey-coe.pilomatrixoma.co.cc/mowry-twins.html">mowry twins</a>, [url="http://dovey-coe.pilomatrixoma.co.cc/mowry-twins.html"]mowry twins[/url], http://dovey-coe.pilomatrixoma.co.cc/mowry-twins.html mowry twins, =]], <a href="http://legacy-of.pilomatrixoma.co.cc/vial-crimp-capping.html">vial crimp capping</a>, [url="http://legacy-of.pilomatrixoma.co.cc/vial-crimp-capping.html"]vial crimp capping[/url], http://legacy-of.pilomatrixoma.co.cc/vial-crimp-capping.html vial crimp capping, =-), <a href="http://legacy-of.pilomatrixoma.co.cc/amir-jafari.html">amir jafari</a>, [url="http://legacy-of.pilomatrixoma.co.cc/amir-jafari.html"]amir jafari[/url], http://legacy-of.pilomatrixoma.co.cc/amir-jafari.html amir jafari, 8-OO, <a href="http://castrating-.pilomatrixoma.co.cc/flordia-lottery.html">flordia lottery</a>, [url="http://castrating-.pilomatrixoma.co.cc/flordia-lottery.html"]flordia lottery[/url], http://castrating-.pilomatrixoma.co.cc/flordia-lottery.html flordia lottery, 611, <a href="http://trish-strau.pilomatrixoma.co.cc/ritterkreuz.html">ritterkreuz</a>, [url="http://trish-strau.pilomatrixoma.co.cc/ritterkreuz.html"]ritterkreuz[/url], http://trish-strau.pilomatrixoma.co.cc/ritterkreuz.html ritterkreuz, nuur, <a href="http://trish-strau.pilomatrixoma.co.cc/acs-exe.html">acs.exe</a>, [url="http://trish-strau.pilomatrixoma.co.cc/acs-exe.html"]acs.exe[/url], http://trish-strau.pilomatrixoma.co.cc/acs-exe.html acs.exe, iro, <a href="http://trish-strau.pilomatrixoma.co.cc/quif.html">quif</a>, [url="http://trish-strau.pilomatrixoma.co.cc/quif.html"]quif[/url], http://trish-strau.pilomatrixoma.co.cc/quif.html quif, iproe, <a href="http://castrating-.pilomatrixoma.co.cc/universalcard.html">universalcard</a>, [url="http://castrating-.pilomatrixoma.co.cc/universalcard.html"]universalcard[/url], http://castrating-.pilomatrixoma.co.cc/universalcard.html universalcard, bjyih, <a href="http://dovey-coe.pilomatrixoma.co.cc/pfn_list_corrupt.html">pfn_list_corrupt</a>, [url="http://dovey-coe.pilomatrixoma.co.cc/pfn_list_corrupt.html"]pfn_list_corrupt[/url], http://dovey-coe.pilomatrixoma.co.cc/pfn_list_corrupt.html pfn_list_corrupt, bxbysk, <a href="http://eu3000is-.pilomatrixoma.co.cc/jayasudha.html">jayasudha</a>, [url="http://eu3000is-.pilomatrixoma.co.cc/jayasudha.html"]jayasudha[/url], http://eu3000is-.pilomatrixoma.co.cc/jayasudha.html jayasudha, 73095, <a href="http://eu3000is-.pilomatrixoma.co.cc/promatech.html">promatech</a>, [url="http://eu3000is-.pilomatrixoma.co.cc/promatech.html"]promatech[/url], http://eu3000is-.pilomatrixoma.co.cc/promatech.html promatech, %-[[, <a href="http://eu3000is-.pilomatrixoma.co.cc/anubus.html">anubus</a>, [url="http://eu3000is-.pilomatrixoma.co.cc/anubus.html"]anubus[/url], http://eu3000is-.pilomatrixoma.co.cc/anubus.html anubus, >:), <a href="http://eu3000is-.pilomatrixoma.co.cc/rastafarian-symbols.html">rastafarian symbols</a>, [url="http://eu3000is-.pilomatrixoma.co.cc/rastafarian-symbols.html"]rastafarian symbols[/url], http://eu3000is-.pilomatrixoma.co.cc/rastafarian-symbols.html rastafarian symbols, 664, <a href="http://teenpanties.pilomatrixoma.co.cc/dupage-roe.html">dupage roe</a>, [url="http://teenpanties.pilomatrixoma.co.cc/dupage-roe.html"]dupage roe[/url], http://teenpanties.pilomatrixoma.co.cc/dupage-roe.html dupage roe, 083, <a href="http://eu3000is-.pilomatrixoma.co.cc/leanna-creel.html">leanna creel</a>, [url="http://eu3000is-.pilomatrixoma.co.cc/leanna-creel.html"]leanna creel[/url], http://eu3000is-.pilomatrixoma.co.cc/leanna-creel.html leanna creel, 790, <a href="http://dovey-coe.pilomatrixoma.co.cc/powerstar-tankless-water-heater.html">powerstar tankless water heater</a>, [url="http://dovey-coe.pilomatrixoma.co.cc/powerstar-tankless-water-heater.html"]powerstar tankless water heater[/url], http://dovey-coe.pilomatrixoma.co.cc/powerstar-tankless-water-heater.html powerstar tankless water heater, jen, <a href="http://dovey-coe.pilomatrixoma.co.cc/hydromatic-pump.html">hydromatic pump</a>, [url="http://dovey-coe.pilomatrixoma.co.cc/hydromatic-pump.html"]hydromatic pump[/url], http://dovey-coe.pilomatrixoma.co.cc/hydromatic-pump.html hydromatic pump, vfpa, 46f8eb5a02ae850f4c238bd7a66e07e34adc2856 1813 1812 2008-10-16T10:45:54Z Saruman! 2 Reverted edits by [[Special:Contributions/190.5.202.207|190.5.202.207]] ([[User_talk:190.5.202.207|Talk]]); changed back to last version by [[User:Saruman!|Saruman!]] wikitext text/x-wiki ==Routes under Debian== When you need to add a networking route, there generally are two ways to do it: # manually adding a route at the command prompt: this means that the machine will "understand" the route for as long as it is running. However, when you reboot the machine, it will have "forgotten" the route. This is called a non-persistent route. # adding a route to the networking configuration files, so that it will be in place regardless of reboots or network restarts. This is called a persistent route. ===Manipulating non-persistent routes=== From the days of yore, the venerable ''route'' command enables us to view, add, change and delete routes. Its most known use is for printing the current routing table: #route -n Kernel IP routing table Destination Gateway Genmask Flags Metric Ref Use Iface 192.168.70.0 212.214.172.50 255.255.255.0 UG 0 0 0 eth1 192.168.67.0 * 255.255.255.0 U 0 0 0 eth0 212.214.172.0 * 255.255.255.0 U 0 0 0 eth1 default 212.214.172.1 0.0.0.0 UG 0 0 0 eth1 The addition of -n makes sure the ''route'' command does not try to substitute DNS names for IP addresses it knows. The second most used incarnation of ''route'' lies in the addition of a route, as has happened in the previous example. The route was added to the routing table using something like this: #route add -net 192.168.70.0 netmask 255.255.255.0 gw 212.214.172.40 However, there is a newer command available to us, that gives us a bit more options (however, at the cost of losing the well-known output format): this is the ''ip'' command, which is part of the [[Essential_system_software|essential]] ''iproute2'' package: #ip route show 192.168.70.0/24 via 212.214.172.50 dev eth1 src 192.168.67.10 192.168.67.0/24 dev eth0 proto kernel scope link src 192.168.67.10 212.214.172.0/24 dev eth1 proto kernel scope link src 212.214.172.50 default via 212.214.172.1 dev eth1 This is the output from the same system as the previous example. However, we see something interesting here: "ip" is capable of adding extra information to the route, like the first line shows (it's using "via"). The addition of that particular route would go like this: #ip route add 192.168.70.0/24 via 212.214.172.50 src 192.168.67.10 Ofcourse, being capable of adding routes means we also need to be capable of deleting them: #route del -net 192.168.70.0 netmask 255.255.255.0 #ip route del 192.168.70.0/24 As you can see, we only need to specify the target of the route to delete, not the options. ===Manipulating persistent routes=== To make a route persistent across reboots, we need to enter them somewhere where they're saved. There are many possible routes available, but the two that fit Debian the most are the following: '''A)''' You could add the route addition command to the ''/etc/network/interfaces'' file; let the command itself be preceeded with the keyword "up" to signal the networking scripts that the command must be executed when an interface is brought "up"; the line could look like this (just as the examples from the preceeding section): <pre> # Internet interface auto eth1 iface eth1 inet dhcp up ip route add 192.168.70.0/24 via 212.214.172.50 src 192.168.67.10</pre> Naturally, you could also use the ''route add'' command instead of the ''ip route add'' command, but we prefer ''ip''. Note: it matters --where-- in the ''interfaces'' file you put this line: it should be put in the same stanza as the interface it operates on. In this example, the external interface of the server is 212.214.172.50, which belongs with interface ''eth1''. Therefore, the "up" line appears in the stanza for ''eth1''. '''B)''' You could create a script that sets the route(s), and put it in the directory ''/etc/network/if-up.d''. Since all scripts that reside there get called when any interface goes "up", your route setting script would be called when ''any'' interface comes up, including ''lo''. This in turn means that a script for setting a route that belongs with a particular interface, should check on invocation which is the interface that goes up. At this moment in time, we don't employ any such script, so no example here, but if you look at the existing scripts in ''/etc/network/if-up.d'' you'll see how other programmers have done this. d64fade46ce781b1ef77477633ac34012011dd4f 1814 1813 2008-10-16T12:16:48Z 64.111.207.138 0 /* Routes under Debian */ wikitext text/x-wiki fine asian boobs, <a href="http://honda-odess.pilomatrixoma.co.cc/buckaroo-tack.html">buckaroo tack</a>, [url="http://honda-odess.pilomatrixoma.co.cc/buckaroo-tack.html"]buckaroo tack[/url], http://honda-odess.pilomatrixoma.co.cc/buckaroo-tack.html buckaroo tack, >:-DDD, <a href="http://hottie-gott.pilomatrixoma.co.cc/metaformin.html">metaformin</a>, [url="http://hottie-gott.pilomatrixoma.co.cc/metaformin.html"]metaformin[/url], http://hottie-gott.pilomatrixoma.co.cc/metaformin.html metaformin, 56219, <a href="http://legacy-of.pilomatrixoma.co.cc/shopgoodwill.html">shopgoodwill</a>, [url="http://legacy-of.pilomatrixoma.co.cc/shopgoodwill.html"]shopgoodwill[/url], http://legacy-of.pilomatrixoma.co.cc/shopgoodwill.html shopgoodwill, 596, <a href="http://irukandji-j.pilomatrixoma.co.cc/domai-sabrina.html">domai sabrina</a>, [url="http://irukandji-j.pilomatrixoma.co.cc/domai-sabrina.html"]domai sabrina[/url], http://irukandji-j.pilomatrixoma.co.cc/domai-sabrina.html domai sabrina, >:PPP, <a href="http://hottie-gott.pilomatrixoma.co.cc/ballad-of-bilbo-baggins.html">ballad of bilbo baggins</a>, [url="http://hottie-gott.pilomatrixoma.co.cc/ballad-of-bilbo-baggins.html"]ballad of bilbo baggins[/url], http://hottie-gott.pilomatrixoma.co.cc/ballad-of-bilbo-baggins.html ballad of bilbo baggins, rcaj, <a href="http://gangster-tw.pilomatrixoma.co.cc/clea-koff.html">clea koff</a>, [url="http://gangster-tw.pilomatrixoma.co.cc/clea-koff.html"]clea koff[/url], http://gangster-tw.pilomatrixoma.co.cc/clea-koff.html clea koff, 5810, <a href="http://eu3000is-.pilomatrixoma.co.cc/lara-croft-bares-all.html">lara croft bares all</a>, [url="http://eu3000is-.pilomatrixoma.co.cc/lara-croft-bares-all.html"]lara croft bares all[/url], http://eu3000is-.pilomatrixoma.co.cc/lara-croft-bares-all.html lara croft bares all, 981221, <a href="http://legacy-of.pilomatrixoma.co.cc/kathrine-hepburn.html">kathrine hepburn</a>, [url="http://legacy-of.pilomatrixoma.co.cc/kathrine-hepburn.html"]kathrine hepburn[/url], http://legacy-of.pilomatrixoma.co.cc/kathrine-hepburn.html kathrine hepburn, hpd, <a href="http://dovey-coe.pilomatrixoma.co.cc/shamu-cam.html">shamu cam</a>, [url="http://dovey-coe.pilomatrixoma.co.cc/shamu-cam.html"]shamu cam[/url], http://dovey-coe.pilomatrixoma.co.cc/shamu-cam.html shamu cam, >:-(((, <a href="http://irukandji-j.pilomatrixoma.co.cc/kalwall.html">kalwall</a>, [url="http://irukandji-j.pilomatrixoma.co.cc/kalwall.html"]kalwall[/url], http://irukandji-j.pilomatrixoma.co.cc/kalwall.html kalwall, hpz, <a href="http://legacy-of.pilomatrixoma.co.cc/omnimon.html">omnimon</a>, [url="http://legacy-of.pilomatrixoma.co.cc/omnimon.html"]omnimon[/url], http://legacy-of.pilomatrixoma.co.cc/omnimon.html omnimon, 25545, <a href="http://irukandji-j.pilomatrixoma.co.cc/krystal-steal-sex.html">krystal steal sex</a>, [url="http://irukandji-j.pilomatrixoma.co.cc/krystal-steal-sex.html"]krystal steal sex[/url], http://irukandji-j.pilomatrixoma.co.cc/krystal-steal-sex.html krystal steal sex, %O, <a href="http://castrating-.pilomatrixoma.co.cc/monkys.html">monkys</a>, [url="http://castrating-.pilomatrixoma.co.cc/monkys.html"]monkys[/url], http://castrating-.pilomatrixoma.co.cc/monkys.html monkys, >:-O, <a href="http://dovey-coe.pilomatrixoma.co.cc/truesync-desktop-download.html">truesync desktop download</a>, [url="http://dovey-coe.pilomatrixoma.co.cc/truesync-desktop-download.html"]truesync desktop download[/url], http://dovey-coe.pilomatrixoma.co.cc/truesync-desktop-download.html truesync desktop download, 63244, <a href="http://legacy-of.pilomatrixoma.co.cc/famous-mainers.html">famous mainers</a>, [url="http://legacy-of.pilomatrixoma.co.cc/famous-mainers.html"]famous mainers[/url], http://legacy-of.pilomatrixoma.co.cc/famous-mainers.html famous mainers, 45704, <a href="http://castrating-.pilomatrixoma.co.cc/lizzy-borden-nude.html">lizzy borden nude</a>, [url="http://castrating-.pilomatrixoma.co.cc/lizzy-borden-nude.html"]lizzy borden nude[/url], http://castrating-.pilomatrixoma.co.cc/lizzy-borden-nude.html lizzy borden nude, 2995, <a href="http://castrating-.pilomatrixoma.co.cc/flexitec.html">flexitec</a>, [url="http://castrating-.pilomatrixoma.co.cc/flexitec.html"]flexitec[/url], http://castrating-.pilomatrixoma.co.cc/flexitec.html flexitec, =-(((, <a href="http://irukandji-j.pilomatrixoma.co.cc/ngk-spark-plug-cross-reference.html">ngk spark plug cross reference</a>, [url="http://irukandji-j.pilomatrixoma.co.cc/ngk-spark-plug-cross-reference.html"]ngk spark plug cross reference[/url], http://irukandji-j.pilomatrixoma.co.cc/ngk-spark-plug-cross-reference.html ngk spark plug cross reference, cgoiit, <a href="http://legacy-of.pilomatrixoma.co.cc/umpa-lumpas.html">umpa lumpas</a>, [url="http://legacy-of.pilomatrixoma.co.cc/umpa-lumpas.html"]umpa lumpas[/url], http://legacy-of.pilomatrixoma.co.cc/umpa-lumpas.html umpa lumpas, dsmp, <a href="http://trish-strau.pilomatrixoma.co.cc/oberweis-dairy.html">oberweis dairy</a>, [url="http://trish-strau.pilomatrixoma.co.cc/oberweis-dairy.html"]oberweis dairy[/url], http://trish-strau.pilomatrixoma.co.cc/oberweis-dairy.html oberweis dairy, 344973, b8581bc1190616ce40064bf0d21bf0dae3ed0706 1815 1814 2008-10-16T13:33:48Z Saruman! 2 Reverted edits by [[Special:Contributions/64.111.207.138|64.111.207.138]] ([[User_talk:64.111.207.138|Talk]]); changed back to last version by [[User:Saruman!|Saruman!]] wikitext text/x-wiki ==Routes under Debian== When you need to add a networking route, there generally are two ways to do it: # manually adding a route at the command prompt: this means that the machine will "understand" the route for as long as it is running. However, when you reboot the machine, it will have "forgotten" the route. This is called a non-persistent route. # adding a route to the networking configuration files, so that it will be in place regardless of reboots or network restarts. This is called a persistent route. ===Manipulating non-persistent routes=== From the days of yore, the venerable ''route'' command enables us to view, add, change and delete routes. Its most known use is for printing the current routing table: #route -n Kernel IP routing table Destination Gateway Genmask Flags Metric Ref Use Iface 192.168.70.0 212.214.172.50 255.255.255.0 UG 0 0 0 eth1 192.168.67.0 * 255.255.255.0 U 0 0 0 eth0 212.214.172.0 * 255.255.255.0 U 0 0 0 eth1 default 212.214.172.1 0.0.0.0 UG 0 0 0 eth1 The addition of -n makes sure the ''route'' command does not try to substitute DNS names for IP addresses it knows. The second most used incarnation of ''route'' lies in the addition of a route, as has happened in the previous example. The route was added to the routing table using something like this: #route add -net 192.168.70.0 netmask 255.255.255.0 gw 212.214.172.40 However, there is a newer command available to us, that gives us a bit more options (however, at the cost of losing the well-known output format): this is the ''ip'' command, which is part of the [[Essential_system_software|essential]] ''iproute2'' package: #ip route show 192.168.70.0/24 via 212.214.172.50 dev eth1 src 192.168.67.10 192.168.67.0/24 dev eth0 proto kernel scope link src 192.168.67.10 212.214.172.0/24 dev eth1 proto kernel scope link src 212.214.172.50 default via 212.214.172.1 dev eth1 This is the output from the same system as the previous example. However, we see something interesting here: "ip" is capable of adding extra information to the route, like the first line shows (it's using "via"). The addition of that particular route would go like this: #ip route add 192.168.70.0/24 via 212.214.172.50 src 192.168.67.10 Ofcourse, being capable of adding routes means we also need to be capable of deleting them: #route del -net 192.168.70.0 netmask 255.255.255.0 #ip route del 192.168.70.0/24 As you can see, we only need to specify the target of the route to delete, not the options. ===Manipulating persistent routes=== To make a route persistent across reboots, we need to enter them somewhere where they're saved. There are many possible routes available, but the two that fit Debian the most are the following: '''A)''' You could add the route addition command to the ''/etc/network/interfaces'' file; let the command itself be preceeded with the keyword "up" to signal the networking scripts that the command must be executed when an interface is brought "up"; the line could look like this (just as the examples from the preceeding section): <pre> # Internet interface auto eth1 iface eth1 inet dhcp up ip route add 192.168.70.0/24 via 212.214.172.50 src 192.168.67.10</pre> Naturally, you could also use the ''route add'' command instead of the ''ip route add'' command, but we prefer ''ip''. Note: it matters --where-- in the ''interfaces'' file you put this line: it should be put in the same stanza as the interface it operates on. In this example, the external interface of the server is 212.214.172.50, which belongs with interface ''eth1''. Therefore, the "up" line appears in the stanza for ''eth1''. '''B)''' You could create a script that sets the route(s), and put it in the directory ''/etc/network/if-up.d''. Since all scripts that reside there get called when any interface goes "up", your route setting script would be called when ''any'' interface comes up, including ''lo''. This in turn means that a script for setting a route that belongs with a particular interface, should check on invocation which is the interface that goes up. At this moment in time, we don't employ any such script, so no example here, but if you look at the existing scripts in ''/etc/network/if-up.d'' you'll see how other programmers have done this. d64fade46ce781b1ef77477633ac34012011dd4f 1840 1815 2008-10-20T19:56:39Z Saruman! 2 added resolvconf section wikitext text/x-wiki ==Routes under Debian== When you need to add a networking route, there generally are two ways to do it: # manually adding a route at the command prompt: this means that the machine will "understand" the route for as long as it is running. However, when you reboot the machine, it will have "forgotten" the route. This is called a non-persistent route. # adding a route to the networking configuration files, so that it will be in place regardless of reboots or network restarts. This is called a persistent route. ===Manipulating non-persistent routes=== From the days of yore, the venerable ''route'' command enables us to view, add, change and delete routes. Its most known use is for printing the current routing table: #route -n Kernel IP routing table Destination Gateway Genmask Flags Metric Ref Use Iface 192.168.70.0 212.214.172.50 255.255.255.0 UG 0 0 0 eth1 192.168.67.0 * 255.255.255.0 U 0 0 0 eth0 212.214.172.0 * 255.255.255.0 U 0 0 0 eth1 default 212.214.172.1 0.0.0.0 UG 0 0 0 eth1 The addition of -n makes sure the ''route'' command does not try to substitute DNS names for IP addresses it knows. The second most used incarnation of ''route'' lies in the addition of a route, as has happened in the previous example. The route was added to the routing table using something like this: #route add -net 192.168.70.0 netmask 255.255.255.0 gw 212.214.172.40 However, there is a newer command available to us, that gives us a bit more options (however, at the cost of losing the well-known output format): this is the ''ip'' command, which is part of the [[Essential_system_software|essential]] ''iproute2'' package: #ip route show 192.168.70.0/24 via 212.214.172.50 dev eth1 src 192.168.67.10 192.168.67.0/24 dev eth0 proto kernel scope link src 192.168.67.10 212.214.172.0/24 dev eth1 proto kernel scope link src 212.214.172.50 default via 212.214.172.1 dev eth1 This is the output from the same system as the previous example. However, we see something interesting here: "ip" is capable of adding extra information to the route, like the first line shows (it's using "via"). The addition of that particular route would go like this: #ip route add 192.168.70.0/24 via 212.214.172.50 src 192.168.67.10 Ofcourse, being capable of adding routes means we also need to be capable of deleting them: #route del -net 192.168.70.0 netmask 255.255.255.0 #ip route del 192.168.70.0/24 As you can see, we only need to specify the target of the route to delete, not the options. ===Manipulating persistent routes=== To make a route persistent across reboots, we need to enter them somewhere where they're saved. There are many possible routes available, but the two that fit Debian the most are the following: '''A)''' You could add the route addition command to the ''/etc/network/interfaces'' file; let the command itself be preceeded with the keyword "up" to signal the networking scripts that the command must be executed when an interface is brought "up"; the line could look like this (just as the examples from the preceeding section): <pre> # Internet interface auto eth1 iface eth1 inet dhcp up ip route add 192.168.70.0/24 via 212.214.172.50 src 192.168.67.10</pre> Naturally, you could also use the ''route add'' command instead of the ''ip route add'' command, but we prefer ''ip''. Note: it matters --where-- in the ''interfaces'' file you put this line: it should be put in the same stanza as the interface it operates on. In this example, the external interface of the server is 212.214.172.50, which belongs with interface ''eth1''. Therefore, the "up" line appears in the stanza for ''eth1''. '''B)''' You could create a script that sets the route(s), and put it in the directory ''/etc/network/if-up.d''. Since all scripts that reside there get called when any interface goes "up", your route setting script would be called when ''any'' interface comes up, including ''lo''. This in turn means that a script for setting a route that belongs with a particular interface, should check on invocation which is the interface that goes up. At this moment in time, we don't employ any such script, so no example here, but if you look at the existing scripts in ''/etc/network/if-up.d'' you'll see how other programmers have done this. ==DNS resolution under Debian== One headache you might encounter when configuring a Debian server is how to let every program know how to resolve DNS names. Before a program can connect to an external network resource (say, for example, a web server), it must have a means of converting DNS names (e.g. www.saruman.biz) into the corresponding IP addresses (e.g. 192.168.67.10). This process is called "name resolution". The need for name resolution means that every program needs to know about the available means by which to do this name resolution. From the good old days comes the configuration file ''resolv.conf'', normally found in ''/etc''. It contains information about the nameservers to be used by the system, be they actual servers or lookup files. However, more and more programs have the need to dynamically modify the ''resolv.conf'' configuration file. This means that frequently they step on each other, and the ''resolv.conf'' file can become out-of-sync. The ''resolvconf'' program addresses this problem. It acts as an intermediary between programs that supply nameserver information (e.g. DHCP clients) and programs that use nameserver information (e.g. resolver). When ''resolvconf'' is properly installed, the file ''/etc/resolv.conf'' is replaced by a symbolic link to ''/etc/resolvconf/run/resolv.conf'', and any resolver thus uses the dynamically generated resolver configuration file at ''/etc/resolvconf/run/resolv.conf''. The ''resolvconf'' program is only necessary when a system has multiple programs that need to dynamically modify the nameserver information. In a simple system where the nameservers do not change often or are only changed by one program, the standard ''/etc/resolv.conf'' configuration file is adequate. 0fcbccde614738d9edc16700f5f404eea5ba7890 1848 1840 2008-10-22T09:54:15Z 194.165.42.61 0 0 wikitext text/x-wiki 10Ln2s <a href="http://qagxoudlwsrg.com/">qagxoudlwsrg</a>, [url=http://hkohogbnntqz.com/]hkohogbnntqz[/url], [link=http://ajmoxspubzba.com/]ajmoxspubzba[/link], http://izdncmzymuhe.com/ ==DNS resolution under Debian== One headache you might encounter when configuring a Debian server is how to let every program know how to resolve DNS names. Before a program can connect to an external network resource (say, for example, a web server), it must have a means of converting DNS names (e.g. www.saruman.biz) into the corresponding IP addresses (e.g. 192.168.67.10). This process is called "name resolution". The need for name resolution means that every program needs to know about the available means by which to do this name resolution. From the good old days comes the configuration file ''resolv.conf'', normally found in ''/etc''. It contains information about the nameservers to be used by the system, be they actual servers or lookup files. However, more and more programs have the need to dynamically modify the ''resolv.conf'' configuration file. This means that frequently they step on each other, and the ''resolv.conf'' file can become out-of-sync. The ''resolvconf'' program addresses this problem. It acts as an intermediary between programs that supply nameserver information (e.g. DHCP clients) and programs that use nameserver information (e.g. resolver). When ''resolvconf'' is properly installed, the file ''/etc/resolv.conf'' is replaced by a symbolic link to ''/etc/resolvconf/run/resolv.conf'', and any resolver thus uses the dynamically generated resolver configuration file at ''/etc/resolvconf/run/resolv.conf''. The ''resolvconf'' program is only necessary when a system has multiple programs that need to dynamically modify the nameserver information. In a simple system where the nameservers do not change often or are only changed by one program, the standard ''/etc/resolv.conf'' configuration file is adequate. cb0fdf6870b144a4e85b3a54c5eff02e707de26e 1850 1848 2008-10-22T10:48:58Z Saruman! 2 Reverted edits by [[Special:Contributions/194.165.42.61|194.165.42.61]] ([[User_talk:194.165.42.61|Talk]]); changed back to last version by [[User:Saruman!|Saruman!]] wikitext text/x-wiki ==Routes under Debian== When you need to add a networking route, there generally are two ways to do it: # manually adding a route at the command prompt: this means that the machine will "understand" the route for as long as it is running. However, when you reboot the machine, it will have "forgotten" the route. This is called a non-persistent route. # adding a route to the networking configuration files, so that it will be in place regardless of reboots or network restarts. This is called a persistent route. ===Manipulating non-persistent routes=== From the days of yore, the venerable ''route'' command enables us to view, add, change and delete routes. Its most known use is for printing the current routing table: #route -n Kernel IP routing table Destination Gateway Genmask Flags Metric Ref Use Iface 192.168.70.0 212.214.172.50 255.255.255.0 UG 0 0 0 eth1 192.168.67.0 * 255.255.255.0 U 0 0 0 eth0 212.214.172.0 * 255.255.255.0 U 0 0 0 eth1 default 212.214.172.1 0.0.0.0 UG 0 0 0 eth1 The addition of -n makes sure the ''route'' command does not try to substitute DNS names for IP addresses it knows. The second most used incarnation of ''route'' lies in the addition of a route, as has happened in the previous example. The route was added to the routing table using something like this: #route add -net 192.168.70.0 netmask 255.255.255.0 gw 212.214.172.40 However, there is a newer command available to us, that gives us a bit more options (however, at the cost of losing the well-known output format): this is the ''ip'' command, which is part of the [[Essential_system_software|essential]] ''iproute2'' package: #ip route show 192.168.70.0/24 via 212.214.172.50 dev eth1 src 192.168.67.10 192.168.67.0/24 dev eth0 proto kernel scope link src 192.168.67.10 212.214.172.0/24 dev eth1 proto kernel scope link src 212.214.172.50 default via 212.214.172.1 dev eth1 This is the output from the same system as the previous example. However, we see something interesting here: "ip" is capable of adding extra information to the route, like the first line shows (it's using "via"). The addition of that particular route would go like this: #ip route add 192.168.70.0/24 via 212.214.172.50 src 192.168.67.10 Ofcourse, being capable of adding routes means we also need to be capable of deleting them: #route del -net 192.168.70.0 netmask 255.255.255.0 #ip route del 192.168.70.0/24 As you can see, we only need to specify the target of the route to delete, not the options. ===Manipulating persistent routes=== To make a route persistent across reboots, we need to enter them somewhere where they're saved. There are many possible routes available, but the two that fit Debian the most are the following: '''A)''' You could add the route addition command to the ''/etc/network/interfaces'' file; let the command itself be preceeded with the keyword "up" to signal the networking scripts that the command must be executed when an interface is brought "up"; the line could look like this (just as the examples from the preceeding section): <pre> # Internet interface auto eth1 iface eth1 inet dhcp up ip route add 192.168.70.0/24 via 212.214.172.50 src 192.168.67.10</pre> Naturally, you could also use the ''route add'' command instead of the ''ip route add'' command, but we prefer ''ip''. Note: it matters --where-- in the ''interfaces'' file you put this line: it should be put in the same stanza as the interface it operates on. In this example, the external interface of the server is 212.214.172.50, which belongs with interface ''eth1''. Therefore, the "up" line appears in the stanza for ''eth1''. '''B)''' You could create a script that sets the route(s), and put it in the directory ''/etc/network/if-up.d''. Since all scripts that reside there get called when any interface goes "up", your route setting script would be called when ''any'' interface comes up, including ''lo''. This in turn means that a script for setting a route that belongs with a particular interface, should check on invocation which is the interface that goes up. At this moment in time, we don't employ any such script, so no example here, but if you look at the existing scripts in ''/etc/network/if-up.d'' you'll see how other programmers have done this. ==DNS resolution under Debian== One headache you might encounter when configuring a Debian server is how to let every program know how to resolve DNS names. Before a program can connect to an external network resource (say, for example, a web server), it must have a means of converting DNS names (e.g. www.saruman.biz) into the corresponding IP addresses (e.g. 192.168.67.10). This process is called "name resolution". The need for name resolution means that every program needs to know about the available means by which to do this name resolution. From the good old days comes the configuration file ''resolv.conf'', normally found in ''/etc''. It contains information about the nameservers to be used by the system, be they actual servers or lookup files. However, more and more programs have the need to dynamically modify the ''resolv.conf'' configuration file. This means that frequently they step on each other, and the ''resolv.conf'' file can become out-of-sync. The ''resolvconf'' program addresses this problem. It acts as an intermediary between programs that supply nameserver information (e.g. DHCP clients) and programs that use nameserver information (e.g. resolver). When ''resolvconf'' is properly installed, the file ''/etc/resolv.conf'' is replaced by a symbolic link to ''/etc/resolvconf/run/resolv.conf'', and any resolver thus uses the dynamically generated resolver configuration file at ''/etc/resolvconf/run/resolv.conf''. The ''resolvconf'' program is only necessary when a system has multiple programs that need to dynamically modify the nameserver information. In a simple system where the nameservers do not change often or are only changed by one program, the standard ''/etc/resolv.conf'' configuration file is adequate. 0fcbccde614738d9edc16700f5f404eea5ba7890 1866 1850 2008-10-22T23:00:09Z 194.247.134.226 0 0 wikitext text/x-wiki i8v6Mh <a href="http://wuaekhcarfov.com/">wuaekhcarfov</a>, [url=http://kzcmexmoyukn.com/]kzcmexmoyukn[/url], [link=http://tcjuwyeytrld.com/]tcjuwyeytrld[/link], http://xqeqkujxpeyt.com/ ==DNS resolution under Debian== One headache you might encounter when configuring a Debian server is how to let every program know how to resolve DNS names. Before a program can connect to an external network resource (say, for example, a web server), it must have a means of converting DNS names (e.g. www.saruman.biz) into the corresponding IP addresses (e.g. 192.168.67.10). This process is called "name resolution". The need for name resolution means that every program needs to know about the available means by which to do this name resolution. From the good old days comes the configuration file ''resolv.conf'', normally found in ''/etc''. It contains information about the nameservers to be used by the system, be they actual servers or lookup files. However, more and more programs have the need to dynamically modify the ''resolv.conf'' configuration file. This means that frequently they step on each other, and the ''resolv.conf'' file can become out-of-sync. The ''resolvconf'' program addresses this problem. It acts as an intermediary between programs that supply nameserver information (e.g. DHCP clients) and programs that use nameserver information (e.g. resolver). When ''resolvconf'' is properly installed, the file ''/etc/resolv.conf'' is replaced by a symbolic link to ''/etc/resolvconf/run/resolv.conf'', and any resolver thus uses the dynamically generated resolver configuration file at ''/etc/resolvconf/run/resolv.conf''. The ''resolvconf'' program is only necessary when a system has multiple programs that need to dynamically modify the nameserver information. In a simple system where the nameservers do not change often or are only changed by one program, the standard ''/etc/resolv.conf'' configuration file is adequate. ab7e0f330da4b54d08a95369d8963775a568d738 1868 1866 2008-10-23T05:31:45Z Saruman! 2 Reverted edits by [[Special:Contributions/194.247.134.226|194.247.134.226]] ([[User_talk:194.247.134.226|Talk]]); changed back to last version by [[User:Saruman!|Saruman!]] wikitext text/x-wiki ==Routes under Debian== When you need to add a networking route, there generally are two ways to do it: # manually adding a route at the command prompt: this means that the machine will "understand" the route for as long as it is running. However, when you reboot the machine, it will have "forgotten" the route. This is called a non-persistent route. # adding a route to the networking configuration files, so that it will be in place regardless of reboots or network restarts. This is called a persistent route. ===Manipulating non-persistent routes=== From the days of yore, the venerable ''route'' command enables us to view, add, change and delete routes. Its most known use is for printing the current routing table: #route -n Kernel IP routing table Destination Gateway Genmask Flags Metric Ref Use Iface 192.168.70.0 212.214.172.50 255.255.255.0 UG 0 0 0 eth1 192.168.67.0 * 255.255.255.0 U 0 0 0 eth0 212.214.172.0 * 255.255.255.0 U 0 0 0 eth1 default 212.214.172.1 0.0.0.0 UG 0 0 0 eth1 The addition of -n makes sure the ''route'' command does not try to substitute DNS names for IP addresses it knows. The second most used incarnation of ''route'' lies in the addition of a route, as has happened in the previous example. The route was added to the routing table using something like this: #route add -net 192.168.70.0 netmask 255.255.255.0 gw 212.214.172.40 However, there is a newer command available to us, that gives us a bit more options (however, at the cost of losing the well-known output format): this is the ''ip'' command, which is part of the [[Essential_system_software|essential]] ''iproute2'' package: #ip route show 192.168.70.0/24 via 212.214.172.50 dev eth1 src 192.168.67.10 192.168.67.0/24 dev eth0 proto kernel scope link src 192.168.67.10 212.214.172.0/24 dev eth1 proto kernel scope link src 212.214.172.50 default via 212.214.172.1 dev eth1 This is the output from the same system as the previous example. However, we see something interesting here: "ip" is capable of adding extra information to the route, like the first line shows (it's using "via"). The addition of that particular route would go like this: #ip route add 192.168.70.0/24 via 212.214.172.50 src 192.168.67.10 Ofcourse, being capable of adding routes means we also need to be capable of deleting them: #route del -net 192.168.70.0 netmask 255.255.255.0 #ip route del 192.168.70.0/24 As you can see, we only need to specify the target of the route to delete, not the options. ===Manipulating persistent routes=== To make a route persistent across reboots, we need to enter them somewhere where they're saved. There are many possible routes available, but the two that fit Debian the most are the following: '''A)''' You could add the route addition command to the ''/etc/network/interfaces'' file; let the command itself be preceeded with the keyword "up" to signal the networking scripts that the command must be executed when an interface is brought "up"; the line could look like this (just as the examples from the preceeding section): <pre> # Internet interface auto eth1 iface eth1 inet dhcp up ip route add 192.168.70.0/24 via 212.214.172.50 src 192.168.67.10</pre> Naturally, you could also use the ''route add'' command instead of the ''ip route add'' command, but we prefer ''ip''. Note: it matters --where-- in the ''interfaces'' file you put this line: it should be put in the same stanza as the interface it operates on. In this example, the external interface of the server is 212.214.172.50, which belongs with interface ''eth1''. Therefore, the "up" line appears in the stanza for ''eth1''. '''B)''' You could create a script that sets the route(s), and put it in the directory ''/etc/network/if-up.d''. Since all scripts that reside there get called when any interface goes "up", your route setting script would be called when ''any'' interface comes up, including ''lo''. This in turn means that a script for setting a route that belongs with a particular interface, should check on invocation which is the interface that goes up. At this moment in time, we don't employ any such script, so no example here, but if you look at the existing scripts in ''/etc/network/if-up.d'' you'll see how other programmers have done this. ==DNS resolution under Debian== One headache you might encounter when configuring a Debian server is how to let every program know how to resolve DNS names. Before a program can connect to an external network resource (say, for example, a web server), it must have a means of converting DNS names (e.g. www.saruman.biz) into the corresponding IP addresses (e.g. 192.168.67.10). This process is called "name resolution". The need for name resolution means that every program needs to know about the available means by which to do this name resolution. From the good old days comes the configuration file ''resolv.conf'', normally found in ''/etc''. It contains information about the nameservers to be used by the system, be they actual servers or lookup files. However, more and more programs have the need to dynamically modify the ''resolv.conf'' configuration file. This means that frequently they step on each other, and the ''resolv.conf'' file can become out-of-sync. The ''resolvconf'' program addresses this problem. It acts as an intermediary between programs that supply nameserver information (e.g. DHCP clients) and programs that use nameserver information (e.g. resolver). When ''resolvconf'' is properly installed, the file ''/etc/resolv.conf'' is replaced by a symbolic link to ''/etc/resolvconf/run/resolv.conf'', and any resolver thus uses the dynamically generated resolver configuration file at ''/etc/resolvconf/run/resolv.conf''. The ''resolvconf'' program is only necessary when a system has multiple programs that need to dynamically modify the nameserver information. In a simple system where the nameservers do not change often or are only changed by one program, the standard ''/etc/resolv.conf'' configuration file is adequate. 0fcbccde614738d9edc16700f5f404eea5ba7890 1881 1868 2008-10-23T20:59:45Z Saruman! 2 Added VLAN section wikitext text/x-wiki ==Routes under Debian== When you need to add a networking route, there generally are two ways to do it: # manually adding a route at the command prompt: this means that the machine will "understand" the route for as long as it is running. However, when you reboot the machine, it will have "forgotten" the route. This is called a non-persistent route. # adding a route to the networking configuration files, so that it will be in place regardless of reboots or network restarts. This is called a persistent route. ===Manipulating non-persistent routes=== From the days of yore, the venerable ''route'' command enables us to view, add, change and delete routes. Its most known use is for printing the current routing table: #route -n Kernel IP routing table Destination Gateway Genmask Flags Metric Ref Use Iface 192.168.70.0 212.214.172.50 255.255.255.0 UG 0 0 0 eth1 192.168.67.0 * 255.255.255.0 U 0 0 0 eth0 212.214.172.0 * 255.255.255.0 U 0 0 0 eth1 default 212.214.172.1 0.0.0.0 UG 0 0 0 eth1 The addition of -n makes sure the ''route'' command does not try to substitute DNS names for IP addresses it knows. The second most used incarnation of ''route'' lies in the addition of a route, as has happened in the previous example. The route was added to the routing table using something like this: #route add -net 192.168.70.0 netmask 255.255.255.0 gw 212.214.172.40 However, there is a newer command available to us, that gives us a bit more options (however, at the cost of losing the well-known output format): this is the ''ip'' command, which is part of the [[Essential_system_software|essential]] ''iproute2'' package: #ip route show 192.168.70.0/24 via 212.214.172.50 dev eth1 src 192.168.67.10 192.168.67.0/24 dev eth0 proto kernel scope link src 192.168.67.10 212.214.172.0/24 dev eth1 proto kernel scope link src 212.214.172.50 default via 212.214.172.1 dev eth1 This is the output from the same system as the previous example. However, we see something interesting here: "ip" is capable of adding extra information to the route, like the first line shows (it's using "via"). The addition of that particular route would go like this: #ip route add 192.168.70.0/24 via 212.214.172.50 src 192.168.67.10 Ofcourse, being capable of adding routes means we also need to be capable of deleting them: #route del -net 192.168.70.0 netmask 255.255.255.0 #ip route del 192.168.70.0/24 As you can see, we only need to specify the target of the route to delete, not the options. ===Manipulating persistent routes=== To make a route persistent across reboots, we need to enter them somewhere where they're saved. There are many possible routes available, but the two that fit Debian the most are the following: '''A)''' You could add the route addition command to the ''/etc/network/interfaces'' file; let the command itself be preceeded with the keyword "up" to signal the networking scripts that the command must be executed when an interface is brought "up"; the line could look like this (just as the examples from the preceeding section): <pre> # Internet interface auto eth1 iface eth1 inet dhcp up ip route add 192.168.70.0/24 via 212.214.172.50 src 192.168.67.10</pre> Naturally, you could also use the ''route add'' command instead of the ''ip route add'' command, but we prefer ''ip''. Note: it matters --where-- in the ''interfaces'' file you put this line: it should be put in the same stanza as the interface it operates on. In this example, the external interface of the server is 212.214.172.50, which belongs with interface ''eth1''. Therefore, the "up" line appears in the stanza for ''eth1''. '''B)''' You could create a script that sets the route(s), and put it in the directory ''/etc/network/if-up.d''. Since all scripts that reside there get called when any interface goes "up", your route setting script would be called when ''any'' interface comes up, including ''lo''. This in turn means that a script for setting a route that belongs with a particular interface, should check on invocation which is the interface that goes up. At this moment in time, we don't employ any such script, so no example here, but if you look at the existing scripts in ''/etc/network/if-up.d'' you'll see how other programmers have done this. ==DNS resolution under Debian== One headache you might encounter when configuring a Debian server is how to let every program know how to resolve DNS names. Before a program can connect to an external network resource (say, for example, a web server), it must have a means of converting DNS names (e.g. www.saruman.biz) into the corresponding IP addresses (e.g. 192.168.67.10). This process is called "name resolution". The need for name resolution means that every program needs to know about the available means by which to do this name resolution. From the good old days comes the configuration file ''resolv.conf'', normally found in ''/etc''. It contains information about the nameservers to be used by the system, be they actual servers or lookup files. However, more and more programs have the need to dynamically modify the ''resolv.conf'' configuration file. This means that frequently they step on each other, and the ''resolv.conf'' file can become out-of-sync. The ''resolvconf'' program addresses this problem. It acts as an intermediary between programs that supply nameserver information (e.g. DHCP clients) and programs that use nameserver information (e.g. resolver). When ''resolvconf'' is properly installed, the file ''/etc/resolv.conf'' is replaced by a symbolic link to ''/etc/resolvconf/run/resolv.conf'', and any resolver thus uses the dynamically generated resolver configuration file at ''/etc/resolvconf/run/resolv.conf''. The ''resolvconf'' program is only necessary when a system has multiple programs that need to dynamically modify the nameserver information. In a simple system where the nameservers do not change often or are only changed by one program, the standard ''/etc/resolv.conf'' configuration file is adequate. == VLANs under Debian == Debian can support network traffic over VLANs (ethernet 802.1q) - and we don't mean the normal "untagged" network ports (hey, VLANs are transparent that way, anybody and anything can use untagged network ports). No, we mean that Debian can accept network traffic in from, and send traffic out to, a VLAN tagged switchport. Suppose you have a layer 2 switch with support for 802.1q VLANs, and want to route traffic from one VLAN to another. For this you can use a Debian router with a single network interface, using VLAN support (this is called "router on a stick" because the routing takes place over only one cable). First, as root, run apt-get install vlan modprobe 8021q The first line is to install the vlan package, which contains all necessary tools to create and manipulate VLAN-enabled network ports. The second line loads the module that enables VLAN tagging for your ethernet network cards. Note: if you don't have the stock Debian kernel, but compiled your own, then you might have chosen not to compile the 8021q module. In that case, compile the module. Also note, that if you've compiled the 8021q code into the kernel itself, then you don't need to load the module and that second line is unnecessary for you. You'll find this kernel compile option (depending on your kernel version) under Networking -> Networking Options -> "802.1Q VLAN Support". This option has been in the Linux kernel since version 2.4.14. ifconfig eth0 down vconfig add eth0 2 vconfig add eth0 3 The first command brings down your network on eth0 (not the thing to do if you're working remote, then :-). The next two commands create two virtual interfaces ''eth0.2'' and ''eth0.3'', which have VLAN tags 2 and 3 (don't use VLAN tag 1 if you can help it; on many devices VLAN1 is a special hardware management VLAN). The virtual interfaces run on top of your ''eth0'' interface.<br> Now because your VLAN interfaces run on top of ''eth0'', you've got to bring ''eth0'' itself up, even if you don't want to run network traffic over it. Furthermore, you've got to configure the two virtual interfaces you've created. Let's suppose you want to run IP subnet 192.168.1.0/24 on VLAN2, and 192.168.2.0/24 on VLAN3. You can do so with ifconfig eth0 0.0.0.0 up ifconfig eth0.2 192.168.1.1 broadcast 192.168.1.255 netmask 255.255.255.0 up ifconfig eth0.3 192.168.2.1 broadcast 192.168.2.255 netmask 255.255.255.0 up Now that you've this done, you must still configure one of your switch ports to belong to VLAN 2 and 3 at the same time (tagged port), and connect ''eth0'' from your linux box to that port. This enables your box to run network traffic on both VLANs. To round things up: if you haven't yet enabled forwarding, you can do so now. Furthermore, you might wish to augment your route table so that the routing engine in your server knows how to handle packets that it needs to forward from one VLAN to the other: echo 1 > /proc/sys/net/ipv4/ip_forward route add -net 10.1.1.0 netmask 255.255.255.0 gw eth0.2 route add -net 10.1.2.0 netmask 255.255.255.0 gw eth0.3 This is it; nothing to it, right? 0eee61c8c8d0a43496c965f729db633ca12252dd 0 1419 1816 1460 2008-10-16T18:54:21Z 82.161.20.132 0 /* '''SMART''' */ wikitext text/x-wiki == '''SMART''' == If you want to read out the smart status of your hard disk you can use smartmontools. >apt-get install smartmontools Now you have 2 utility program's (smartctl and smartd). With smartctl you can read out your hard disks >smartctl -a /dev/hda This will give you all info of your hard disk. For sata disk you will have to give the -d option >smartctl -d ata -a /dev/hda Fore more options on smartctl use -h Now we can configure the smart daemon in /etc/smartd.conf. This daemon will monitor your hard disks. This config file gives you a good explination of the different options you can use I use the following options /dev/sda -d ata -a -o on -S on -s (S/../.././02|L/../../6/03) /dev/sda -d ata -H -m admin@linuz.nl == Format == To see you're current disk partitioning darktower:~# fdisk -l Disk /dev/hda: 120.0 GB, 120060444672 bytes 255 heads, 63 sectors/track, 14596 cylinders Units = cylinders of 16065 * 512 = 8225280 bytes Device Boot Start End Blocks Id System /dev/hda1 1 14596 117242338+ 83 Linux To see more info on you're drive you can use ''smartctl'' This is a command provided by the smartmontools package. smartctl -i /dev/hda Also ''hdparm'' can be used to get or set the drive parameters. hdparm -d /dev/hda 62000e69e67b32b5e3b0545d5744c61a463ddd65 1817 1816 2008-10-16T19:06:15Z 82.161.20.132 0 /* Format */ wikitext text/x-wiki == '''SMART''' == If you want to read out the smart status of your hard disk you can use smartmontools. >apt-get install smartmontools Now you have 2 utility program's (smartctl and smartd). With smartctl you can read out your hard disks >smartctl -a /dev/hda This will give you all info of your hard disk. For sata disk you will have to give the -d option >smartctl -d ata -a /dev/hda Fore more options on smartctl use -h Now we can configure the smart daemon in /etc/smartd.conf. This daemon will monitor your hard disks. This config file gives you a good explination of the different options you can use I use the following options /dev/sda -d ata -a -o on -S on -s (S/../.././02|L/../../6/03) /dev/sda -d ata -H -m admin@linuz.nl == Format == To see you're current disk partitioning darktower:~# fdisk -l Disk /dev/hda: 120.0 GB, 120060444672 bytes 255 heads, 63 sectors/track, 14596 cylinders Units = cylinders of 16065 * 512 = 8225280 bytes Device Boot Start End Blocks Id System /dev/hda1 1 14596 117242338+ 83 Linux To see more info on you're drive you can use ''smartctl'' This is a command provided by the smartmontools package. smartctl -i /dev/hda Also ''hdparm'' can be used to get or set the drive parameters. hdparm -d /dev/hda Now to partition the disk cfdisk /dev/hda . Now that we have 1 or more partitions, we have to format it with a filesystem. The most commonly used filesystem is ext3 (in unix that is) mkfs.ext3 /dev/hda1 977683d80795c4557fea8c036aadf011f334ae22 1818 1817 2008-10-16T19:21:41Z Insomnia 3 /* Format */ wikitext text/x-wiki == '''SMART''' == If you want to read out the smart status of your hard disk you can use smartmontools. >apt-get install smartmontools Now you have 2 utility program's (smartctl and smartd). With smartctl you can read out your hard disks >smartctl -a /dev/hda This will give you all info of your hard disk. For sata disk you will have to give the -d option >smartctl -d ata -a /dev/hda Fore more options on smartctl use -h Now we can configure the smart daemon in /etc/smartd.conf. This daemon will monitor your hard disks. This config file gives you a good explination of the different options you can use I use the following options /dev/sda -d ata -a -o on -S on -s (S/../.././02|L/../../6/03) /dev/sda -d ata -H -m admin@linuz.nl == Format == To see you're current disk partitioning darktower:~# fdisk -l Disk /dev/hda: 120.0 GB, 120060444672 bytes 255 heads, 63 sectors/track, 14596 cylinders Units = cylinders of 16065 * 512 = 8225280 bytes Device Boot Start End Blocks Id System /dev/hda1 1 14596 117242338+ 83 Linux To see more info on you're drive you can use ''smartctl'' This is a command provided by the smartmontools package. smartctl -i /dev/hda Also ''hdparm'' can be used to get or set the drive parameters. darktower:~# hdparm -d /dev/hda /dev/hda: using_dma = 1 (on) To set udma use -d0 (off) or -d1 (on). Fore more options on smartctl use -h Now to partition the disk cfdisk /dev/hda Choose you're partioning type en size Now that we have 1 or more partitions, we have to format it with a filesystem. The most commonly used filesystem is ext3 (in unix that is) mkfs.ext3 /dev/hda1 2d1339168e696958b45e407851ac6489fff95056 1819 1818 2008-10-16T19:34:44Z Insomnia 3 /* '''SMART''' */ wikitext text/x-wiki == '''SMART''' == If you want to read out the smart status of your hard disk you can use smartmontools. >apt-get install smartmontools Now you have 2 utility program's (smartctl and smartd). With smartctl you can read out your hard disks. To see more info on you're drive type: >smartctl -i /dev/hda Or to see all the smart read out >smartctl -a /dev/hda This will give you all info of your hard disk. For sata disk you will have to give the -d option >smartctl -d ata -a /dev/hda Fore more options on smartctl use -h Now we can configure the smart daemon in /etc/smartd.conf. This daemon will monitor your hard disks. This config file gives you a good explination of the different options you can use I use the following options /dev/sda -d ata -a -o on -S on -s (S/../.././02|L/../../6/03) /dev/sda -d ata -H -m admin@linuz.nl == Format == To see you're current disk partitioning darktower:~# fdisk -l Disk /dev/hda: 120.0 GB, 120060444672 bytes 255 heads, 63 sectors/track, 14596 cylinders Units = cylinders of 16065 * 512 = 8225280 bytes Device Boot Start End Blocks Id System /dev/hda1 1 14596 117242338+ 83 Linux To see more info on you're drive you can use ''smartctl'' This is a command provided by the smartmontools package. smartctl -i /dev/hda Also ''hdparm'' can be used to get or set the drive parameters. darktower:~# hdparm -d /dev/hda /dev/hda: using_dma = 1 (on) To set udma use -d0 (off) or -d1 (on). Fore more options on smartctl use -h Now to partition the disk cfdisk /dev/hda Choose you're partioning type en size Now that we have 1 or more partitions, we have to format it with a filesystem. The most commonly used filesystem is ext3 (in unix that is) mkfs.ext3 /dev/hda1 5d439df15972e6c9e9d74f67b030a4fcfd3f8acc 1820 1819 2008-10-16T19:36:18Z Insomnia 3 /* Format */ wikitext text/x-wiki == '''SMART''' == If you want to read out the smart status of your hard disk you can use smartmontools. >apt-get install smartmontools Now you have 2 utility program's (smartctl and smartd). With smartctl you can read out your hard disks. To see more info on you're drive type: >smartctl -i /dev/hda Or to see all the smart read out >smartctl -a /dev/hda This will give you all info of your hard disk. For sata disk you will have to give the -d option >smartctl -d ata -a /dev/hda Fore more options on smartctl use -h Now we can configure the smart daemon in /etc/smartd.conf. This daemon will monitor your hard disks. This config file gives you a good explination of the different options you can use I use the following options /dev/sda -d ata -a -o on -S on -s (S/../.././02|L/../../6/03) /dev/sda -d ata -H -m admin@linuz.nl == Format == To see you're current disk partitioning darktower:~# fdisk -l Disk /dev/hda: 120.0 GB, 120060444672 bytes 255 heads, 63 sectors/track, 14596 cylinders Units = cylinders of 16065 * 512 = 8225280 bytes Device Boot Start End Blocks Id System /dev/hda1 1 14596 117242338+ 83 Linux To see more info on you're drive you can use ''smartctl'' This is a command provided by the smartmontools package. smartctl -i /dev/hda == HDPARM == Also ''hdparm'' can be used to get or set the drive parameters. darktower:~# hdparm -d /dev/hda /dev/hda: using_dma = 1 (on) To set udma use -d0 (off) or -d1 (on). Fore more options on smartctl use -h Now to partition the disk cfdisk /dev/hda Choose you're partioning type en size Now that we have 1 or more partitions, we have to format it with a filesystem. The most commonly used filesystem is ext3 (in unix that is) mkfs.ext3 /dev/hda1 1661e31dbce209f06082fbb01566c4878af41532 1821 1820 2008-10-16T19:37:21Z Insomnia 3 /* HDPARM */ wikitext text/x-wiki == '''SMART''' == If you want to read out the smart status of your hard disk you can use smartmontools. >apt-get install smartmontools Now you have 2 utility program's (smartctl and smartd). With smartctl you can read out your hard disks. To see more info on you're drive type: >smartctl -i /dev/hda Or to see all the smart read out >smartctl -a /dev/hda This will give you all info of your hard disk. For sata disk you will have to give the -d option >smartctl -d ata -a /dev/hda Fore more options on smartctl use -h Now we can configure the smart daemon in /etc/smartd.conf. This daemon will monitor your hard disks. This config file gives you a good explination of the different options you can use I use the following options /dev/sda -d ata -a -o on -S on -s (S/../.././02|L/../../6/03) /dev/sda -d ata -H -m admin@linuz.nl == Format == To see you're current disk partitioning darktower:~# fdisk -l Disk /dev/hda: 120.0 GB, 120060444672 bytes 255 heads, 63 sectors/track, 14596 cylinders Units = cylinders of 16065 * 512 = 8225280 bytes Device Boot Start End Blocks Id System /dev/hda1 1 14596 117242338+ 83 Linux To see more info on you're drive you can use ''smartctl'' This is a command provided by the smartmontools package. smartctl -i /dev/hda == HDPARM == Also ''hdparm'' can be used to get or set the drive parameters. darktower:~# hdparm -d /dev/hda /dev/hda: using_dma = 1 (on) To set udma use -d0 (off) or -d1 (on). Fore more options on smartctl use -h == Partioning and format == Now to partition the disk cfdisk /dev/hda Choose you're partioning type en size Now that we have 1 or more partitions, we have to format it with a filesystem. The most commonly used filesystem is ext3 (in unix that is) mkfs.ext3 /dev/hda1 11a64a4a9d5e94e4f512b397b69993d6a0d70f72 1822 1821 2008-10-16T19:38:29Z Insomnia 3 /* Format */ wikitext text/x-wiki == '''SMART''' == If you want to read out the smart status of your hard disk you can use smartmontools. >apt-get install smartmontools Now you have 2 utility program's (smartctl and smartd). With smartctl you can read out your hard disks. To see more info on you're drive type: >smartctl -i /dev/hda Or to see all the smart read out >smartctl -a /dev/hda This will give you all info of your hard disk. For sata disk you will have to give the -d option >smartctl -d ata -a /dev/hda Fore more options on smartctl use -h Now we can configure the smart daemon in /etc/smartd.conf. This daemon will monitor your hard disks. This config file gives you a good explination of the different options you can use I use the following options /dev/sda -d ata -a -o on -S on -s (S/../.././02|L/../../6/03) /dev/sda -d ata -H -m admin@linuz.nl == HDPARM == Also ''hdparm'' can be used to get or set the drive parameters. darktower:~# hdparm -d /dev/hda /dev/hda: using_dma = 1 (on) To set udma use -d0 (off) or -d1 (on). Fore more options on smartctl use -h == Partioning and format == Now to partition the disk cfdisk /dev/hda Choose you're partioning type en size Now that we have 1 or more partitions, we have to format it with a filesystem. The most commonly used filesystem is ext3 (in unix that is) mkfs.ext3 /dev/hda1 6a89498154f29209cf63f4682562bb496805b833 1823 1822 2008-10-16T19:39:17Z Insomnia 3 /* Partioning */ wikitext text/x-wiki == '''SMART''' == If you want to read out the smart status of your hard disk you can use smartmontools. >apt-get install smartmontools Now you have 2 utility program's (smartctl and smartd). With smartctl you can read out your hard disks. To see more info on you're drive type: >smartctl -i /dev/hda Or to see all the smart read out >smartctl -a /dev/hda This will give you all info of your hard disk. For sata disk you will have to give the -d option >smartctl -d ata -a /dev/hda Fore more options on smartctl use -h Now we can configure the smart daemon in /etc/smartd.conf. This daemon will monitor your hard disks. This config file gives you a good explination of the different options you can use I use the following options /dev/sda -d ata -a -o on -S on -s (S/../.././02|L/../../6/03) /dev/sda -d ata -H -m admin@linuz.nl == HDPARM == Also ''hdparm'' can be used to get or set the drive parameters. darktower:~# hdparm -d /dev/hda /dev/hda: using_dma = 1 (on) To set udma use -d0 (off) or -d1 (on). Fore more options on smartctl use -h == Partioning == Now to partition the disk cfdisk /dev/hda Choose you're partioning type en size Now that we have 1 or more partitions, we have to format it with a filesystem. The most commonly used filesystem is ext3 (in unix that is) mkfs.ext3 /dev/hda1 == Format == To see you're current disk partitioning darktower:~# fdisk -l Disk /dev/hda: 120.0 GB, 120060444672 bytes 255 heads, 63 sectors/track, 14596 cylinders Units = cylinders of 16065 * 512 = 8225280 bytes Device Boot Start End Blocks Id System /dev/hda1 1 14596 117242338+ 83 Linux To see more info on you're drive you can use ''smartctl'' This is a command provided by the smartmontools package. smartctl -i /dev/hda 7c87c4a90d4e850714a9994fcdcc5837e0515296 1824 1823 2008-10-16T19:42:22Z Insomnia 3 /* HDPARM */ wikitext text/x-wiki == '''SMART''' == If you want to read out the smart status of your hard disk you can use smartmontools. >apt-get install smartmontools Now you have 2 utility program's (smartctl and smartd). With smartctl you can read out your hard disks. To see more info on you're drive type: >smartctl -i /dev/hda Or to see all the smart read out >smartctl -a /dev/hda This will give you all info of your hard disk. For sata disk you will have to give the -d option >smartctl -d ata -a /dev/hda Fore more options on smartctl use -h Now we can configure the smart daemon in /etc/smartd.conf. This daemon will monitor your hard disks. This config file gives you a good explination of the different options you can use I use the following options /dev/sda -d ata -a -o on -S on -s (S/../.././02|L/../../6/03) /dev/sda -d ata -H -m admin@linuz.nl == HDPARM == Install hdparm apt-get install hdparm ''hdparm'' can be used to get or set the drive parameters. To set udma use -d0 (off) or -d1 (on). Fore more options on smartctl use -h darktower:~# hdparm -d /dev/hda /dev/hda: using_dma = 1 (on) == Partioning == Now to partition the disk cfdisk /dev/hda Choose you're partioning type en size Now that we have 1 or more partitions, we have to format it with a filesystem. The most commonly used filesystem is ext3 (in unix that is) mkfs.ext3 /dev/hda1 == Format == To see you're current disk partitioning darktower:~# fdisk -l Disk /dev/hda: 120.0 GB, 120060444672 bytes 255 heads, 63 sectors/track, 14596 cylinders Units = cylinders of 16065 * 512 = 8225280 bytes Device Boot Start End Blocks Id System /dev/hda1 1 14596 117242338+ 83 Linux To see more info on you're drive you can use ''smartctl'' This is a command provided by the smartmontools package. smartctl -i /dev/hda 4a1441283b4e2e5c416839908c5b25d23ecfcf23 1825 1824 2008-10-16T19:43:20Z Insomnia 3 /* Partioning */ wikitext text/x-wiki == '''SMART''' == If you want to read out the smart status of your hard disk you can use smartmontools. >apt-get install smartmontools Now you have 2 utility program's (smartctl and smartd). With smartctl you can read out your hard disks. To see more info on you're drive type: >smartctl -i /dev/hda Or to see all the smart read out >smartctl -a /dev/hda This will give you all info of your hard disk. For sata disk you will have to give the -d option >smartctl -d ata -a /dev/hda Fore more options on smartctl use -h Now we can configure the smart daemon in /etc/smartd.conf. This daemon will monitor your hard disks. This config file gives you a good explination of the different options you can use I use the following options /dev/sda -d ata -a -o on -S on -s (S/../.././02|L/../../6/03) /dev/sda -d ata -H -m admin@linuz.nl == HDPARM == Install hdparm apt-get install hdparm ''hdparm'' can be used to get or set the drive parameters. To set udma use -d0 (off) or -d1 (on). Fore more options on smartctl use -h darktower:~# hdparm -d /dev/hda /dev/hda: using_dma = 1 (on) == Partioning == Now to partition the disk cfdisk /dev/hda Choose you're partioning type en size == Format == To see you're current disk partitioning darktower:~# fdisk -l Disk /dev/hda: 120.0 GB, 120060444672 bytes 255 heads, 63 sectors/track, 14596 cylinders Units = cylinders of 16065 * 512 = 8225280 bytes Device Boot Start End Blocks Id System /dev/hda1 1 14596 117242338+ 83 Linux To see more info on you're drive you can use ''smartctl'' This is a command provided by the smartmontools package. smartctl -i /dev/hda 341bff48c0b5d6ab02b88b436396889581d60b73 1826 1825 2008-10-16T19:44:43Z Insomnia 3 /* Format */ wikitext text/x-wiki == '''SMART''' == If you want to read out the smart status of your hard disk you can use smartmontools. >apt-get install smartmontools Now you have 2 utility program's (smartctl and smartd). With smartctl you can read out your hard disks. To see more info on you're drive type: >smartctl -i /dev/hda Or to see all the smart read out >smartctl -a /dev/hda This will give you all info of your hard disk. For sata disk you will have to give the -d option >smartctl -d ata -a /dev/hda Fore more options on smartctl use -h Now we can configure the smart daemon in /etc/smartd.conf. This daemon will monitor your hard disks. This config file gives you a good explination of the different options you can use I use the following options /dev/sda -d ata -a -o on -S on -s (S/../.././02|L/../../6/03) /dev/sda -d ata -H -m admin@linuz.nl == HDPARM == Install hdparm apt-get install hdparm ''hdparm'' can be used to get or set the drive parameters. To set udma use -d0 (off) or -d1 (on). Fore more options on smartctl use -h darktower:~# hdparm -d /dev/hda /dev/hda: using_dma = 1 (on) == Partioning == Now to partition the disk cfdisk /dev/hda Choose you're partioning type en size == Format == To see you're current disk partitioning darktower:~# fdisk -l Disk /dev/hda: 120.0 GB, 120060444672 bytes 255 heads, 63 sectors/track, 14596 cylinders Units = cylinders of 16065 * 512 = 8225280 bytes Device Boot Start End Blocks Id System /dev/hda1 1 14596 117242338+ 83 Linux Now that we have 1 or more partitions, we have to format it with a filesystem. The most commonly used filesystem is ext3 (in unix that is) mkfs.ext3 /dev/hda1 ed3b3d73aa644bb259a3eca0ab07ffd310770a64 1827 1826 2008-10-16T19:53:13Z Insomnia 3 /* Partitioning */ wikitext text/x-wiki == '''SMART''' == If you want to read out the smart status of your hard disk you can use smartmontools. >apt-get install smartmontools Now you have 2 utility program's (smartctl and smartd). With smartctl you can read out your hard disks. To see more info on you're drive type: >smartctl -i /dev/hda Or to see all the smart read out >smartctl -a /dev/hda This will give you all info of your hard disk. For sata disk you will have to give the -d option >smartctl -d ata -a /dev/hda Fore more options on smartctl use -h Now we can configure the smart daemon in /etc/smartd.conf. This daemon will monitor your hard disks. This config file gives you a good explination of the different options you can use I use the following options /dev/sda -d ata -a -o on -S on -s (S/../.././02|L/../../6/03) /dev/sda -d ata -H -m admin@linuz.nl == HDPARM == Install hdparm apt-get install hdparm ''hdparm'' can be used to get or set the drive parameters. To set udma use -d0 (off) or -d1 (on). Fore more options on smartctl use -h darktower:~# hdparm -d /dev/hda /dev/hda: using_dma = 1 (on) == Partitioning == To partition the disk use cfdisk cfdisk /dev/hda Choose you're partioning type en size. == Format == To see you're current disk partitioning darktower:~# fdisk -l Disk /dev/hda: 120.0 GB, 120060444672 bytes 255 heads, 63 sectors/track, 14596 cylinders Units = cylinders of 16065 * 512 = 8225280 bytes Device Boot Start End Blocks Id System /dev/hda1 1 14596 117242338+ 83 Linux Now that we have 1 or more partitions, we have to format it with a filesystem. The most commonly used filesystem is ext3 (in unix that is) mkfs.ext3 /dev/hda1 56af62de6e25db88bb54be9fa4cf79bc0796b3cc 0 1475 1828 1767 2008-10-17T13:47:03Z Saruman! 2 /* Configuring Asterisk - the basics */ adding Dialplan theory link wikitext text/x-wiki =Asterisk under Debian 5.0 "Lenny"= The pages on this Wiki all relate to running Asterisk with [http://www.digium.com/ Digium] hardware on [http://www.debian.org/releases/lenny/ Debian 5.0 "Lenny"]. The scenario we're working on here is a single server, attached to both the Internet (over ADSL) and a home network, that's being expanded to also serve as a telephone PBX. We might make a distinction between an Asterisk PBX connected to the Plain Old Telephone System (POTS) using [http://www.digium.com/en/products/analog/x100m.php an FXO module], and an Asterisk that only has VoIP functionality. Read the different subsections for more information, but remember: the basis of all the information in this wiki is [http://downloads.oreilly.com/books/9780596510480.pdf this fantastic book]. If you're interested in Asterisk, we seriously suggest you [http://oreilly.com/catalog/9780596510480/index.html buy it]. =Installing the hardware= When you need only VoIP support, and no standard phones or telephone lines need to be connected to your Asterisk PBX, you really don't need any kind of special hardware. However, if you need to receive from or send out calls to the Plain Old Telephone System (POTS), you need hardware with FXO capabilities. Furthermore, if you need to attach regular telephones to your PBX (as opposed to just using softphones, phone software on laptops and desktops), you need hardware with FXS capabilities. For our discussion on obtaining and installing telephony hardware, [[Telephony hardware explained | go here]]. =Configuring hardware support= Once you've installed your [[Telephony hardware explained | telephony hardware]], you probably want to start using it. The bad news is, this requires the Linux kernel to support that hardware with drivers, that it currently does not have. The good news is, we can explain to you [[Installing and configuring Zaptel | how to get and install those]]. =Installing Asterisk under Debian= When the hardware is running, you can [[install Asterisk under Debian]] - well actually you could install and configure Asterisk, and add hardware later, but we like to explain things in this particular order. We'll also do some [[install Asterisk under Debian | basic configuration and testing]] here, to test the installation of your FXO and FXS enabled hardware. When that is in working order, we continue with [[Configuring and testing SIP and IAX2 | configuring and testing SIP and IAX2]], in which we'll try to, well, configure and test both SIP (a softphone) and IAX2, which is a connection between two Asterisk PBXes. =Configuring Asterisk - the basics= Once Asterisk is up and running, we can start putting in the most [[Asterisk basic configuration | basic configuration]]. Directly after this, we hand out some [[Dialplan theory]]. This gives you the possibility to receive and place calls, but not yet much of the funky stuff that is described in the [http://downloads.oreilly.com/books/9780596510480.pdf Asterisk TFOTF book]. 7cd05b2dd72f355a34a7890f2a54c463dda8cef8 0 1481 1830 2008-10-17T14:17:41Z Saruman! 2 Page started wikitext text/x-wiki =What is a dialplan?= When first starting with Asterisk, you might be intimidated by the sheer complexity of the dialplan. But we find it is actually very simple - so simple that it's getting difficult, as it were :-) Think of it this way: you've got a PBX, and that can do just about one thing: handle calls. And what is a call? Two endpoints, connected together to enable communication (''voice'' communication, we're inclined to think). So Asterisk must handle calls. For any call, there's an element of "dialing", where the initiating endpoint feeds information into the telephony system about who he/she wants to reach. This initiates the call, but the call is not actually set up until the other side "picks up" - either because the target endpoint has accepted the call, or because a PBX on the target endpoint site has picked up the phone. In the latter case, it might be necessary to feed additional info into the call, like in answering a "voice menu". So, we can observe that calls come in three varieties: * incoming, where one side of the call is already totally set up to communicate. This is the case when someone "outside" your premises tries to contact someone "inside" * outgoing, where the PBX must also make a connection, but the receiving party is not on a channel attached to the PBX, but "somewhere out there". * passing through, where the PBX accepts an incoming connection, but then dials out to reach the intended recipient. However, the more you think about these two kinds of calls, the more you'll see that they're almost the same. The most notable difference is in who is paying for the call.... So, when you have a PBX like Asterisk, you have to instruct it how to handle calls - be it incoming, outgoing or passing through. In all cases, the initiating party has or will enter information by dialing, upon which the PBX must act. The recipe for these actions is thus called a "dialplan". So when WE have to create a dialplan for our Asterisk PBX, what must we do? Not much, only to create little recipes for each perceivable call that Asterisk must handle for us. As such, creating a dialplan is much like programming - only the language that we have to program in is a bit clumsy and limited (at least with Asterisk 1.4). So we have to learn this call programming stuff - and how hard can that be? =Dialplan elements= Any dialplan contains the following building blocks: * Applications * Extensions * Contexts =Applications= = Extensions = An extension can be one of two types: a literal or a pattern. A literal extension can be a number, like 123, and it can also contain the standard symbols * and # that appear on ordinary telephones, so 12#89* is a valid extension. A single extension can also match patterns. In the extensions.conf file, an extension name is a pattern if it starts with the underscore symbol (_). In an extension pattern, the following characters have special meanings: X matches any digit from 0-9 Z matches any digit from 1-9 N matches any digit from 2-9 [1237-9] matches any digit or letter in the brackets (in this example, 1,2,3,7,8,9) . wildcard, matches one or more characters ! wildcard, matches zero or more characters immediately Asterisk uses some extension names for special purposes: * i : Invalid * s : Start * h : Hangup * t : Timeout * T : AbsoluteTimeout * a : Asterisk extension * o : Operator = Asterisk dialplans - handling incoming calls = What is a Channel? A channel is a connection which brings in a call to the Asterisk PBX. A channel could be a connection to an ordinary telephone handset or an ordinary telephone line, or to a logical call (like an Internet phone call). Asterisk makes no distinction between "FXO" and "FXS" style channels (that is, it doesn't distinguish between telephone lines and telephones). Every call is placed or received on a distinct channel. = Asterisk dialplans - handling outgoing calls = = Where to go from here= cd463184c07ec5fa5ed8c139d7b446c23ffa5329 1838 1830 2008-10-19T21:09:47Z Saruman! 2 /* What is a dialplan? */ reworked wikitext text/x-wiki =What is a dialplan?= When first starting with Asterisk, you might be intimidated by the sheer complexity of the dialplan. But we find it is actually very simple - so simple that it's getting difficult, as it were :-) Think of it this way: you've got a PBX, and that can do just about one thing: handle calls. And what is a call? Two endpoints, connected together to enable communication (''voice'' communication, we're inclined to think). So Asterisk must handle calls. And we must tell it how - using something that's called a "dialplan". That's all there is to it, really. Now, for any call, there's an element of "dialing", where the initiating endpoint feeds information into the telephony system about who he/she wants to reach. This initiates the call, but the call is not actually set up until the other side "picks up" - either because the target endpoint has accepted the call, or because a PBX on the target endpoint site has picked up the phone. In the latter case, it might be necessary to feed additional info into the call, like in answering a "voice menu". From this element of dialing, the call handling configuration file derives its name, but it might help you to keep in mind that the dial plan is actually handling calls, not just dialing. We can observe that calls come in three varieties: * incoming, where one side of the call is already totally set up to communicate. This is the case when someone "outside" your premises tries to contact someone "inside" * outgoing, where the PBX must also make a connection, but the receiving party is not on a channel attached to the PBX, but "somewhere out there". * passing through, where the PBX accepts an incoming connection, but then dials out to reach the intended recipient. However, the more you think about these three kinds of calls, the more you'll see that they're almost the same. The most notable difference is in who is paying for the call.... So all of these calls go through the dial plan, and we must cater for all use cases that these calls can follow. When we create a dialplan for our Asterisk PBX, what exactly must we do? Not much, only to create little recipes for each perceivable call that Asterisk must handle for us. As such, creating a dial plan is much like programming - only the language that we have to program in is a bit clumsy and limited (at least with Asterisk 1.4). So we have to learn this call programming stuff - and how hard can that be? =Dialplan elements= Any dialplan contains the following building blocks: * Applications * Extensions * Contexts =Applications= = Extensions = An extension can be one of two types: a literal or a pattern. A literal extension can be a number, like 123, and it can also contain the standard symbols * and # that appear on ordinary telephones, so 12#89* is a valid extension. A single extension can also match patterns. In the extensions.conf file, an extension name is a pattern if it starts with the underscore symbol (_). In an extension pattern, the following characters have special meanings: X matches any digit from 0-9 Z matches any digit from 1-9 N matches any digit from 2-9 [1237-9] matches any digit or letter in the brackets (in this example, 1,2,3,7,8,9) . wildcard, matches one or more characters ! wildcard, matches zero or more characters immediately Asterisk uses some extension names for special purposes: * i : Invalid * s : Start * h : Hangup * t : Timeout * T : AbsoluteTimeout * a : Asterisk extension * o : Operator = Asterisk dialplans - handling incoming calls = What is a Channel? A channel is a connection which brings in a call to the Asterisk PBX. A channel could be a connection to an ordinary telephone handset or an ordinary telephone line, or to a logical call (like an Internet phone call). Asterisk makes no distinction between "FXO" and "FXS" style channels (that is, it doesn't distinguish between telephone lines and telephones). Every call is placed or received on a distinct channel. = Asterisk dialplans - handling outgoing calls = = Where to go from here= fa79939e023065aa7f749783b4d2806be9aead01 0 1482 1832 2008-10-19T14:17:13Z Insomnia 3 ndiswrapper wikitext text/x-wiki == NDISwrapper == NDISwrapper is a free software driver wrapper that enables the use of Microsoft Windows drivers for wireless network devices. 1 Download the windows driver wich contains the .inf file 2 Install with ndiswrapper -i drivername.inf 3 check the device id with lsusb or lspci -n 4 Now execute with ndiswrapper -a deviceid driver ndiswrapper -a 0bda:8197 net8187b check the installed drivers ndiswrapper -l Write the configuration for modprobe ndiswrapper -m And use the module modprobe ndiswrapper 75dacc9f6415f0e23c4a9d737510dd4301352cc0 1833 1832 2008-10-19T14:18:32Z Insomnia 3 wikitext text/x-wiki == NDISwrapper == NDISwrapper is a free software driver wrapper that enables the use of Microsoft Windows drivers for wireless network devices. Download the windows driver wich contains the .inf file Install with ndiswrapper -i drivername.inf check the device id with lsusb or lspci -n Now execute with ndiswrapper -a deviceid driver ndiswrapper -a 0bda:8197 net8187b check the installed drivers ndiswrapper -l Write the configuration for modprobe ndiswrapper -m And use the module modprobe ndiswrapper 804776b0647412a7ef712de680871f14ef50327a 1834 1833 2008-10-19T14:20:35Z Insomnia 3 /* NDISwrapper */ layout wikitext text/x-wiki == NDISwrapper == NDISwrapper is a free software driver wrapper that enables the use of Microsoft Windows drivers for wireless network devices. Download the windows driver wich contains the .inf file<br> Install with ndiswrapper -i drivername.inf<br> check the device id with lsusb or lspci -n<br> Now execute with ndiswrapper -a deviceid driver ndiswrapper -a 0bda:8197 net8187b check the installed drivers ndiswrapper -l Write the configuration for modprobe ndiswrapper -m And use the module modprobe ndiswrapper 03ba35cf04bb5b65837f70f3d20e3a28ccc0a6a8 0 1483 1836 2008-10-19T18:31:38Z Insomnia 3 Hostap wikitext text/x-wiki == Hardware == Requirements wireless-tools (for iwconfig) Bridge-utils Hostapd Hostap-utils ?? I used an old netgear wireless pci card. To see wich chipset it has type lspci 00:0e.0 Ethernet controller: Atheros Communications Inc. AR5212/AR5213 Multiprotocol MAC/baseband processor (rev 01) The atheros chip uses the madwifi driver http://sourceforge.net Download the driver and compile the module. make install modprobe ath_pci Now you should see the card thinner:/# iwconfig lo no wireless extensions. eth0 no wireless extensions. eth1 no wireless extensions. wifi0 no wireless extensions. ath0 IEEE 802.11g ESSID:"" Nickname:"" Mode:Managed Frequency:2.437 GHz Access Point: Not-Associated Bit Rate:0 kb/s Tx-Power:14 dBm Sensitivity=1/1 Retry:off RTS thr:off Fragment thr:off Encryption key:off Power Management:off Link Quality=0/70 Signal level=-96 dBm Noise level=-96 dBm Rx invalid nwid:4378 Rx invalid crypt:0 Rx invalid frag:0 Tx excessive retries:0 Invalid misc:0 Missed beacon:0 To bring the card up #ifconfig ath0 up And to scan for networks #wlanconfig ath0 list scan And for more info #iwlist ath0 scan #wlanconfig ath0 destroy #wlanconfig ath0 create wlandev wifi0 wlanmode ap ath0 IEEE 802.11g ESSID:"" Nickname:"" Mode:Master Frequency:2.412 GHz Access Point: 00:09:5B:C3:97:3E 9c145931d5bf1e9dc22fb248cfd1d1ef9cf768c8 1837 1836 2008-10-19T19:49:55Z Insomnia 3 wikitext text/x-wiki == Hardware == Requirements wireless-tools (for iwconfig) Bridge-utils Hostapd Hostap-utils ?? I used an old netgear wireless pci card. To see wich chipset it has type lspci 00:0e.0 Ethernet controller: Atheros Communications Inc. AR5212/AR5213 Multiprotocol MAC/baseband processor (rev 01) The atheros chip uses the madwifi driver http://sourceforge.net Download the driver and compile the module. make install modprobe ath_pci Now you should see the card thinner:/# iwconfig lo no wireless extensions. eth0 no wireless extensions. eth1 no wireless extensions. wifi0 no wireless extensions. ath0 IEEE 802.11g ESSID:"" Nickname:"" Mode:Managed Frequency:2.437 GHz Access Point: Not-Associated Bit Rate:0 kb/s Tx-Power:14 dBm Sensitivity=1/1 Retry:off RTS thr:off Fragment thr:off Encryption key:off Power Management:off Link Quality=0/70 Signal level=-96 dBm Noise level=-96 dBm Rx invalid nwid:4378 Rx invalid crypt:0 Rx invalid frag:0 Tx excessive retries:0 Invalid misc:0 Missed beacon:0 To bring the card up #ifconfig ath0 up And to scan for networks #wlanconfig ath0 list scan And for more info #iwlist ath0 scan #wlanconfig ath0 destroy #wlanconfig ath0 create wlandev wifi0 wlanmode ap ath0 IEEE 802.11g ESSID:"" Nickname:"" Mode:Master Frequency:2.412 GHz Access Point: 00:09:5B:C3:97:3E Now create a new text file named /etc/hostapd/wpa_psk and paste your pass phrase as: 00:00:00:00:00:00 PASSPHRASE c065207c06a2cc8711bc768a6cd78e750f00eebe 1839 1837 2008-10-19T22:27:59Z Insomnia 3 kernel support atheros wikitext text/x-wiki == Hardware == Requirements wireless-tools (for iwconfig) Bridge-utils Hostapd Hostap-utils ?? I used an old netgear wireless pci card. To see wich chipset it has type lspci 00:0e.0 Ethernet controller: Atheros Communications Inc. AR5212/AR5213 Multiprotocol MAC/baseband processor (rev 01) The atheros chip uses the madwifi driver http://sourceforge.net Download the driver and compile the module. Or use the 2.6.27.2 kernel where the atheros chip is supported as a module. Use modprobe ath9k make install modprobe ath_pci Now you should see the card thinner:/# iwconfig lo no wireless extensions. eth0 no wireless extensions. eth1 no wireless extensions. wifi0 no wireless extensions. ath0 IEEE 802.11g ESSID:"" Nickname:"" Mode:Managed Frequency:2.437 GHz Access Point: Not-Associated Bit Rate:0 kb/s Tx-Power:14 dBm Sensitivity=1/1 Retry:off RTS thr:off Fragment thr:off Encryption key:off Power Management:off Link Quality=0/70 Signal level=-96 dBm Noise level=-96 dBm Rx invalid nwid:4378 Rx invalid crypt:0 Rx invalid frag:0 Tx excessive retries:0 Invalid misc:0 Missed beacon:0 To bring the card up #ifconfig ath0 up And to scan for networks #wlanconfig ath0 list scan And for more info #iwlist ath0 scan #wlanconfig ath0 destroy #wlanconfig ath0 create wlandev wifi0 wlanmode ap ath0 IEEE 802.11g ESSID:"" Nickname:"" Mode:Master Frequency:2.412 GHz Access Point: 00:09:5B:C3:97:3E Now create a new text file named /etc/hostapd/wpa_psk and paste your pass phrase as: 00:00:00:00:00:00 PASSPHRASE 1f34913e3be586ba0edfb4e66535b6d0f3a43c26 0 1435 1898 1506 2008-10-26T11:04:44Z Saruman! 2 changed actual location for PHP file to "official" extension directory wikitext text/x-wiki The sourcecode for the extension can be found [[websiteFrame.php Source Code | here]]. To add the extension: copy the souce code in a file named ''websiteFrame.php'', and put it in directory ''/usr/share/mediawiki-extensions''. Then create a symlink to this source code in directory ''/etc/mediawiki-extensions/extensions-available''. Finally, create a symlink in ''/etc/mediawiki-extensions/extensions-enabled'' to this previous symlink. To bring this about, execute the following commands: vi /usr/share/mediawiki-extensions/websiteFrame.php ln -s /usr/share/mediawiki-extensions/websiteFrame.php /etc/mediawiki-extensions/extensions-available/websiteFrame.php ln -s /etc/mediawiki-extensions/extensions-available/websiteFrame.php /etc/mediawiki-extensions/extensions-enabled/websiteFrame.php Of course, in the first line, you're put in your favourite text editor [[vim]], where you'll need to type or paste the actual source code. As an example, you can use an iFrame by putting in code like this: <pre> &lt;websiteFrame&gt; website=http://www.google.com/talk/service/badge/Show?tk&amp;#61;z01q6a-longcode-8k5lm1&amp;amp;w=200&amp;amp;h=60 border=0 height=60 width=200 name=GoogleChatwithSaruman! allowtransparency=true &lt;/websiteFrame&gt; </pre> Note that the "=" sign is replaced with ''&amp;#61;'' and the &amp; sign by ''&amp;amp;'' because the PHP script doesn't like them literally. 0b1fee2e586e4712ae83a2bcb4a2c66b7c3e9e5f 4 1485 1900 2008-10-26T15:26:29Z Saruman! 2 Page started wikitext text/x-wiki <big>'''The Big Picture'''</big> The SaruWiki is mainly ment as a reference for the members of the Saruwiki Admin Team themselves. If, however, other people can benefit from our experiences, then so much the better :-) <big>''The Admin Team''</big> These are the principal members of the SaruWiki Admin Team: * Jan '''"Saruman!"''' S.<br> Jan works as a technical consultant infrastructure at a large IT company. As such, he helps customers with Unix and Linux servers, networks, security, virtualization and documentation. In his spare time (if any), he listens to progressive rock music and organizes his way-too-big iTunes library, rides a hi-tech hybrid car, reads sci-fi and fantasy, and plays a bit with a digital camera. He is married and has a daughter. * Henri '''"Insomnia"''' S.<br> Henri works as a system and network engineer at a medium sized county. This means he has to pick up every technical problems his collegues do not feel comfortable with. In his spare time Henri flies model helicopters, rides a motorcycle, tinkers with various cars, remodels his house, and entertains his family. Henri's married and has two daughters. d16a1fdb99269f488069a2dea1201e88cab884f0 2 1410 1901 1415 2008-10-26T15:27:20Z Saruman! 2 changed link to saruteam wikitext text/x-wiki <big>'''Saruman!'''</big> I'm part of the [[Saruwiki:about | Administrators team]] of this site. As you can read under the team description, I work as a technical consultant infrastructure at a large IT company. As such, I help customers with Unix and Linux servers, networks, security, virtualization and documentation - although occasionally I have to work with Microsoft Windows networks as well. My qualifications are, amongst others, [http://www.lpi.org/ LPI certifications] ([http://www.lpi.org/en/lpi/english/certification/the_lpic_program LPIC1 and LPIC2] - LPIC 3 is too difficult for me, I fear) In my spare time (if any), I listen to progressive rock music (especially work by [http://www.the-company.com/ Fish]), organize my music in my oversized iTunes library, ride a hi-tech hybrid car, read sci-fi and fantasy (not nearly often enough, though :-(, and play a bit with my digital camera, a [http://www.canon-europe.com/For_Home/Product_Finder/Cameras/Digital_SLR/EOS_20th_Anniversary/2004-2007.asp Canon EOS350D]. I'm married and have one daughter. 88b6d0b8e3cb01558b2dbd4995ac78c714ff6bd3 0 1 1902 1737 2008-10-26T15:29:01Z Saruman! 2 Changed link to SaruTeam wikitext text/x-wiki <big>'''Welcome to SaruWiki.'''</big> This Wiki is intended to document bits and bobs about [http://www.kernel.org/ Linux] (and some Unix) in general, and [http://www.debian.org Debian] in particular. In it, [[SaruTeam|we]] wish to collect the tips and tricks of both [[SaruWiki:About|our own team of Linux admins]] and those of other interested users. Consult the [http://meta.wikimedia.org/wiki/Help:Contents User's Guide] for information on using this wiki's software. ---- <big>'''Main Content'''</big> * Setting up a [[Debian Lenny base server]] is a howto on the installation of a very basic Linux box under Lenny (it's actually not even a server yet). * The use of [[APT and aptitude]] is crucial to the concept of a Debian machine. * [[Roll your own kernel]] discusses the pros and cons of compiling your own kernel, and how to do it. * [[Essential system software]] lists all (sets of) packages that we deem, well, essential. * [[Database 101]] introduces you to MySQL. * [[OpenLDAP]] is a rudimentary howto about getting OpenLDAP to be your central user repository. * The [[Installing SaMBa with OpenLDAP support | SaMBa section]] explains how to install SaMBa with OpenLDAP as user backend. * [[Add an X11 server]] to your server, if you need one * The [[Asterisk section]] is about all things re: telephony on Debian Lenny. * The [[system boot procedure]] section explains what we can customise in the standard ways Debian boots. * The [[networking section]] treats subjects like setting persistent routes. * The [[firewall section]] is where we discuss "IPtables" (netfilter) and how we use it for firewalling. * The [[native IPsec tunnel]] section describes how to configure an IPsec tunnel. * Using ''md'' for [[software RAID]] contains our ideas and observations on redundancy. * [[Hardware monitoring]] is important for your server's health and reliability. * [[Vmware_server|VMware Server basics]] gives some pointers on how to install VMware Server on a Debian server box. * Make your server a [[Microsoft PPTP server | Microsoft client compatible VPN Server ]]. * How to install [[Mediawiki Installation | Mediawiki]] on your Debian server - like what you're looking at now. ---- '''Note''': the Wiki admins reserve the right to edit or remove any content they feel is not suitable for this site, not relevant, (too) inaccurate or otherwise not in line with the intentions and spirit of the admin team. ---- <websiteFrame> website=http://www.google.com/talk/service/badge/Show?tk&#61;z01q6amlqld8jocej2ca891jl9dunqqra83nhehaoqpednb5skkur0fv70jsuavce4ii9ms5e9afdr8qmpsc1d9upni4jom8g1em3p1cvq1p5eo1ugv162fosgprdv867iuememlcogfle8n3dmcf97durjld85avnh8k5lm1&amp;w=200&amp;h=60 border=0 height=60 width=200 name=GoogleChatwithSaruman! allowtransparency=true </websiteFrame> 7e130bd02f01afd1bab2ca043cb584dc21e58dc5 1909 1902 2008-10-26T17:59:29Z Saruman! 2 added Certificates wikitext text/x-wiki <big>'''Welcome to SaruWiki.'''</big> This Wiki is intended to document bits and bobs about [http://www.kernel.org/ Linux] (and some Unix) in general, and [http://www.debian.org Debian] in particular. In it, [[SaruTeam|we]] wish to collect the tips and tricks of both [[SaruWiki:About|our own team of Linux admins]] and those of other interested users. Consult the [http://meta.wikimedia.org/wiki/Help:Contents User's Guide] for information on using this wiki's software. ---- <big>'''Main Content'''</big> * Setting up a [[Debian Lenny base server]] is a howto on the installation of a very basic Linux box under Lenny (it's actually not even a server yet). * The use of [[APT and aptitude]] is crucial to the concept of a Debian machine. * [[Roll your own kernel]] discusses the pros and cons of compiling your own kernel, and how to do it. * [[Essential system software]] lists all (sets of) packages that we deem, well, essential. * [[Certificate fundamentals | The "certificates" section]] explains how you create your own Certificate Authority (CA) and the neat things you can do with it. * [[Database 101]] introduces you to MySQL. * [[OpenLDAP]] is a rudimentary howto about getting OpenLDAP to be your central user repository. * The [[Installing SaMBa with OpenLDAP support | SaMBa section]] explains how to install SaMBa with OpenLDAP as user backend. * [[Add an X11 server]] to your server, if you need one * The [[Asterisk section]] is about all things re: telephony on Debian Lenny. * The [[system boot procedure]] section explains what we can customise in the standard ways Debian boots. * The [[networking section]] treats subjects like setting persistent routes. * The [[firewall section]] is where we discuss "IPtables" (netfilter) and how we use it for firewalling. * The [[native IPsec tunnel]] section describes how to configure an IPsec tunnel. * Using ''md'' for [[software RAID]] contains our ideas and observations on redundancy. * [[Hardware monitoring]] is important for your server's health and reliability. * [[Vmware_server|VMware Server basics]] gives some pointers on how to install VMware Server on a Debian server box. * Make your server a [[Microsoft PPTP server | Microsoft client compatible VPN Server ]]. * How to install [[Mediawiki Installation | Mediawiki]] on your Debian server - like what you're looking at now. ---- '''Note''': the Wiki admins reserve the right to edit or remove any content they feel is not suitable for this site, not relevant, (too) inaccurate or otherwise not in line with the intentions and spirit of the admin team. ---- <websiteFrame> website=http://www.google.com/talk/service/badge/Show?tk&#61;z01q6amlqld8jocej2ca891jl9dunqqra83nhehaoqpednb5skkur0fv70jsuavce4ii9ms5e9afdr8qmpsc1d9upni4jom8g1em3p1cvq1p5eo1ugv162fosgprdv867iuememlcogfle8n3dmcf97durjld85avnh8k5lm1&amp;w=200&amp;h=60 border=0 height=60 width=200 name=GoogleChatwithSaruman! allowtransparency=true </websiteFrame> c23659106c5c6feab02e03d202e546d63b280099 1953 1909 2008-10-29T15:59:03Z Saruman! 2 added confirmedit note + postfix link wikitext text/x-wiki <big>'''Welcome to SaruWiki.'''</big> This Wiki is intended to document bits and bobs about [http://www.kernel.org/ Linux] (and some Unix) in general, and [http://www.debian.org Debian] in particular. In it, [[SaruTeam|we]] wish to collect the tips and tricks of both [[SaruWiki:About|our own team of Linux admins]] and those of other interested users. Consult the [http://meta.wikimedia.org/wiki/Help:Contents User's Guide] for information on using this wiki's software. <big>NOTE:</big> '''you must confirm edits''' when you're not logged in with a user account. Thanks to the Mediawiki ConfirmEdit extension we've cut our wikispam considerably. Sorry to make you anonymous contributors jump through this little hoop for every edit, but there you are. ---- <big>'''Main Content'''</big> * Setting up a [[Debian Lenny base server]] is a howto on the installation of a very basic Linux box under Lenny (it's actually not even a server yet). * The use of [[APT and aptitude]] is crucial to the concept of a Debian machine. * [[Roll your own kernel]] discusses the pros and cons of compiling your own kernel, and how to do it. * [[Essential system software]] lists all (sets of) packages that we deem, well, essential. * [[Certificate fundamentals | The "certificates" section]] explains how you create your own Certificate Authority (CA) and the neat things you can do with it. * [[Database 101]] introduces you to MySQL. * [[OpenLDAP]] is a rudimentary howto about getting OpenLDAP to be your central user repository. * The [[Installing SaMBa with OpenLDAP support | SaMBa section]] explains how to install SaMBa with OpenLDAP as user backend. * [[Add an X11 server]] to your server, if you need one. * Of course we have a [[e-mail server section]], where we focus on Postfix and virtual mail domains, and add in a whiff of MySQL and OpenLDAP. * The [[Asterisk section]] is about all things re: telephony on Debian Lenny. * The [[system boot procedure]] section explains what we can customise in the standard ways Debian boots. * The [[networking section]] treats subjects like setting persistent routes. * The [[firewall section]] is where we discuss "IPtables" (netfilter) and how we use it for firewalling. * The [[native IPsec tunnel]] section describes how to configure an IPsec tunnel. * Using ''md'' for [[software RAID]] contains our ideas and observations on redundancy. * [[Hardware monitoring]] is important for your server's health and reliability. * [[Vmware_server|VMware Server basics]] gives some pointers on how to install VMware Server on a Debian server box. * Make your server a [[Microsoft PPTP server | Microsoft client compatible VPN Server ]]. * How to install [[Mediawiki Installation | Mediawiki]] on your Debian server - like what you're looking at now. ---- '''Note''': the Wiki admins reserve the right to edit or remove any content they feel is not suitable for this site, not relevant, (too) inaccurate or otherwise not in line with the intentions and spirit of the admin team. ---- <websiteFrame> website=http://www.google.com/talk/service/badge/Show?tk&#61;z01q6amlqld8jocej2ca891jl9dunqqra83nhehaoqpednb5skkur0fv70jsuavce4ii9ms5e9afdr8qmpsc1d9upni4jom8g1em3p1cvq1p5eo1ugv162fosgprdv867iuememlcogfle8n3dmcf97durjld85avnh8k5lm1&amp;w=200&amp;h=60 border=0 height=60 width=200 name=GoogleChatwithSaruman! allowtransparency=true </websiteFrame> 86e48581121817b3e54e98d8ca97f69c4d476150 1985 1953 2008-11-05T09:59:44Z Saruman! 2 added PAM wikitext text/x-wiki <big>'''Welcome to SaruWiki.'''</big> This Wiki is intended to document bits and bobs about [http://www.kernel.org/ Linux] (and some Unix) in general, and [http://www.debian.org Debian] in particular. In it, [[SaruWiki:About|we]] wish to collect the tips and tricks of both [[SaruWiki:About|our own team of Linux admins]] and those of other interested users. Consult the [http://meta.wikimedia.org/wiki/Help:Contents User's Guide] for information on using this wiki's software. <big>NOTE:</big> '''you must confirm edits''' when you're not logged in with a user account. Thanks to the Mediawiki ConfirmEdit extension we've cut our wikispam considerably. Sorry to make you anonymous contributors jump through this little hoop for every edit, but there you are. ---- <big>'''Main Content'''</big> * Setting up a [[Debian Lenny base server]] is a howto on the installation of a very basic Linux box under Lenny (it's actually not even a server yet). * The use of [[APT and aptitude]] is crucial to the concept of a Debian machine. * [[Roll your own kernel]] discusses the pros and cons of compiling your own kernel, and how to do it. * [[Essential system software]] lists all (sets of) packages that we deem, well, essential. * [[Pluggable Authentication Modules (PAM)]] is a great way to secure your server and arrange logins - if you get to understand them * [[Certificate fundamentals | The "certificates" section]] explains how you create your own Certificate Authority (CA) and the neat things you can do with it. * [[Database 101]] introduces you to MySQL. * [[OpenLDAP]] is a rudimentary howto about getting OpenLDAP to be your central user repository. * The [[Installing SaMBa with OpenLDAP support | SaMBa section]] explains how to install SaMBa with OpenLDAP as user backend. * [[Add an X11 server]] to your server, if you need one. * Of course we have a [[e-mail server section]], where we focus on Postfix and virtual mail domains, and add in a whiff of MySQL and OpenLDAP. * The [[Asterisk section]] is about all things re: telephony on Debian Lenny. * The [[system boot procedure]] section explains what we can customise in the standard ways Debian boots. * The [[networking section]] treats subjects like setting persistent routes. * The [[firewall section]] is where we discuss "IPtables" (netfilter) and how we use it for firewalling. * The [[native IPsec tunnel]] section describes how to configure an IPsec tunnel. * Using ''md'' for [[software RAID]] contains our ideas and observations on redundancy. * [[Hardware monitoring]] is important for your server's health and reliability. * [[Vmware_server|VMware Server basics]] gives some pointers on how to install VMware Server on a Debian server box. * Make your server a [[Microsoft PPTP server | Microsoft client compatible VPN Server ]]. * How to install [[Mediawiki Installation | Mediawiki]] on your Debian server - like what you're looking at now. ---- '''Note''': the Wiki admins reserve the right to edit or remove any content they feel is not suitable for this site, not relevant, (too) inaccurate or otherwise not in line with the intentions and spirit of the admin team. ---- <websiteFrame> website=http://www.google.com/talk/service/badge/Show?tk&#61;z01q6amlqld8jocej2ca891jl9dunqqra83nhehaoqpednb5skkur0fv70jsuavce4ii9ms5e9afdr8qmpsc1d9upni4jom8g1em3p1cvq1p5eo1ugv162fosgprdv867iuememlcogfle8n3dmcf97durjld85avnh8k5lm1&amp;w=200&amp;h=60 border=0 height=60 width=200 name=GoogleChatwithSaruman! allowtransparency=true </websiteFrame> 582a9468e98a372a1693ea0855fd0a7938d723f7 0 1486 1903 2008-10-26T15:38:14Z 82.161.20.132 0 VSFTPD wikitext text/x-wiki Very secure ftp server. To install apt-get install vsftpd To configure got to /etc/vsftpd.conf vi /etc/vsftpd.conf [Optional] Disable Anonymous account by finding the line that says anonymous_enable=YES and make it anonymous_enable=NO [Optional] Turn off or on write access (upload access). Find and uncomment the following line: write_enable=YES [Optional] Add you banner when people log in. Find and uncomment this #ftpd_banner=Welcome to blah FTP service. line and make it: ftpd_banner=Welcome to Insomnia FTP service. Enjoy. [Optional] Allow local users to log in. Uncomment the following line: local_enable=YES d7a73afa394bf75856469cf9759fc09ac04506a0 0 1487 1912 2008-10-26T18:44:12Z Saruman! 2 Page started wikitext text/x-wiki ==Certificates, an introduction== Digital certificates are an extremely important means to identify identities (of users, as well as of servers) on the Internet, or indeed on most any network. For instance, we use them to encrypt network traffic when we use the HTTPS protocol. Thus, we really need certificates. Now, as [http://www.debian-administration.org/articles/618 this article] explains, you can either buy your certificates from a certificate authority like [http://www.verisign.com/ VeriSign], [http://www.thawte.com/ Thawte] or [http://www.equifaxsecure.co.uk/index.html Equifax Secure], but these certificates cost more than a couple of Euro's, and also need to be renewed (usually every year). So the other route, the one we'll be taking, is to create our own Certificate Authority, and use that to sign certificates for our needs (secure webserver, secure mailserver etcetera). ==Installation of the Certificate Authority (CA)== Now, "installing a CA" sounds like grave configuration work, but in fact a CA does not have to be an actual service, demon or program. A CA is more like a concept, at the heart of which lies the CA "root certificate". So if we obtain a little set of tools and generate our own root certificate, then we're in business. To generate the root CA for our own little organization, we first need tools. These tools under Debian come with the OpenSSL software - which you'll usually find already installed. Now to generate the CA root certificate, we'll use a shell script from the OpenSSL package: ''/usr/lib/ssl/misc/CA.sh'', which together with the configuration file ''/etc/ssl/openssl.cnf'' can create our CA root certificate. To that end, we'll first need to decide on some parameters. '''How strong''' do we want our root certificate? 1024 bits is the default, but the stronger, the better. We suggest 2048 bits. How long should our '''CA root certificate remain valid'''? The longer, the more convenient - but maybe some day in the future, you feel you don't want certificates from ten years earlies to wander around, expired but otherwise valid. Expiry of the root certificate that goes along with that certificate might help you. So what's an appropriate time for your root CA? That depends. For our home CA, we use 15 years. For a business, the cost of providing new root certificates to all computers, employees, and maybe customers, can be so high that you'd rather have 25 years - or maybe security is paramount, and 5 years is long enough for you. We can't say - but our home CA's use 15 years, because we feel that that's a nice intermediate value. 15 years, including about 4 leap days, comes to 5479 days. '''Where do we want to store''' our CA root certificate? By default, the ''CA.sh'' script feels it must store all generated certificates in ''./demoCA''. That's not very handy for us. We rather have a central location like ''/etc/ssl/ca'' on our central server. How long should '''any generated certificate be valid'''? The default value that the ''CA.sh'' script provides is one year. We find that enough - although we add 7 days to accomodate some overlap when having to regenerate the So the information we've decided upon is like this: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Parameter !style="background:#ffdead;"|value |- |root certificate encryption |2048 bits |- |root certificate validity |5479 days (15 years) |- |certificate store |''/etc/ssl/ca'' |- |default certificate validity |370 days (1 year) |- |} Now edit ''/usr/lib/ssl/misc/CA.sh''; find the two lines near the top that define the variables ''DAYS'' and ''CADAYS'', and set these to what we want them to be. A little further down, we find the default location ''CATOP=./demoCA''. Change this (relative) path to the (absolute) path we've decided upon. DAYS="-days 370" # 1 year CADAYS="-days 5479" # 15 years CATOP=/etc/ssl/ca 2ef3cd9bf4bb08739f9ce50c6e2d3af8f18e1c56 1914 1912 2008-10-26T20:24:37Z Saruman! 2 upto CA cert generation wikitext text/x-wiki ==Certificates, an introduction== Digital certificates are an extremely important means to identify identities (of users, as well as of servers) on the Internet, or indeed on most any network. For instance, we use them to encrypt network traffic when we use the HTTPS protocol. Thus, we really need certificates. Now, as [http://www.debian-administration.org/articles/618 this article] explains, you can either buy your certificates from a certificate authority like [http://www.verisign.com/ VeriSign], [http://www.thawte.com/ Thawte] or [http://www.equifaxsecure.co.uk/index.html Equifax Secure], but these certificates cost more than a couple of Euro's, and also need to be renewed (usually every year). So the other route, the one we'll be taking, is to create our own Certificate Authority (CA), and use that to sign certificates for our needs (secure webserver, secure mailserver etcetera). Now, "creating a CA" sounds like grave installation and configuration work, but in fact a CA does not have to be an actual service, demon or program. A CA is more like a concept, at the heart of which lies the CA "root certificate". So if we obtain a little set of tools and generate our own root certificate, then we're in business. ==Creating the Certificate Authority (CA) - preparations== To generate the root CA for our own little organization, we first need tools. These tools under Debian come with the OpenSSL software - which you'll usually find already installed. Now to generate the CA root certificate, we'll use a shell script from the OpenSSL package: ''/usr/lib/ssl/misc/CA.sh'', which together with the configuration file ''/etc/ssl/openssl.cnf'' can create our CA root certificate. To that end, we'll first need to decide on some parameters. ===Deciding on CA parameters=== '''How strong''' do we want our root certificate? 1024 bits is the default, but the stronger, the better. We suggest 2048 bits. How long should our '''CA root certificate remain valid'''? The longer, the more convenient - but maybe some day in the future, you feel you don't want certificates from ten years earlies to wander around, expired but otherwise valid. Expiry of the root certificate that goes along with that certificate might help you. So what's an appropriate time for your root CA? That depends. For our home CA, we use 15 years. For a business, the cost of providing new root certificates to all computers, employees, and maybe customers, can be so high that you'd rather have 25 years - or maybe security is paramount, and 5 years is long enough for you. We can't say - but our home CA's use 15 years, because we feel that that's a nice intermediate value. 15 years, including about 4 leap days, comes to 5479 days. '''Where do we want to store''' our CA root certificate? By default, the ''CA.sh'' script feels it must store all generated certificates in ''./demoCA''. That's not very handy for us. We rather have a central location like ''/etc/ssl/ca'' on our central server. How long should '''any generated certificate be valid'''? The default value that the ''CA.sh'' script provides is one year. We find that enough - although we add 7 days to accomodate some overlap when having to regenerate the certificate upon nearing the expiry date (note: we really want to replace certificates ''prior'' to expiry :-) '''What "company" data''' will we enter in the certificate? Several fields must be entered, some of which you could fill out at will. However, it's not exactly clear why you would want to confuse people trying to authenticate you, your webserver or some other connection by filling out, for example, the country with an incorrect or even non-existent code. On the other hand, you can keep your own privacy in mind, and not fill in your full name, but rather your website's name, at the "common name" section of your CA root certificate. Again, this depends on what you're going to use your CA for. We at [https://www.saruman.biz saruman.biz] decided to use the following values: * Organization name: Saruman.biz. We're private persons, not companies, but we want to maintain a minimum of privacy, so we've put this fake entity name here. * Province: Utrecht. Yep, that's a province in the Netherlands, and we live pretty close to it. * Country: NL (that's the Netherlands) Maybe you want to provide more default information to your CA setup; just look further down on how to. So the information we've decided upon is like this: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Parameter !style="background:#ffdead;"|value |- |root certificate encryption |2048 bits |- |root certificate validity |5479 days (15 years) |- |certificate store |''/etc/ssl/ca'' |- |default certificate validity |370 days (1 year) |- |Organization name |Saruman.biz |- |Certificate province/county name (default) |Utrecht |- |Certificate country name (default) |NL |- |} === Editing the ''CA.sh'' script === Actually, you don't need to use the ''CA.sh'' shell script. There's also a ''CA.pl'' perl script. However, if you're more into shell scripting than perl programming, go for the shell script. Now edit ''/usr/lib/ssl/misc/CA.sh''; find the two lines near the top that define the variables ''DAYS'' and ''CADAYS'', and set these to what we want them to be. A little further down, we find the default location ''CATOP=./demoCA''. Change this (relative) path to the (absolute) path we've decided upon. Then, a lot further down, we find the line that's responsible for creating the CA root certificate itself, it's the line that goes ''$REQ -new -keyout ${CATOP}/private/$CAKEY -out ${CATOP}/$CAREQ'' (well actually it's split out over two lines). Here, we change ''-new'' to ''-newkey rsa:2048''. With all these changes, the three relevant sections in ''CA.sh'' will be changed to something like this: DAYS="-days 370" # 1 year CADAYS="-days 5479" # 15 years ... CATOP=/etc/ssl/ca ... echo "Making CA certificate ..." $REQ -newkey rsa:2048 -keyout ${CATOP}/private/$CAKEY \ -out ${CATOP}/$CAREQ === Editing the ''openssl.cnf'' configuration file=== When generating certificates, the OpenSSL tools check the configuration file ''/etc/ssl/openssl.cnf''. It is necessary to match the parameters in there with the choices and changes of the previous sections, and also it's handy to change some of the default parameters that certificates require upon generation. It's important to remember that these parameters will be asked every time you generate a certificate, but it's ofcourse pretty handy if the default value is set for your situation, so you can just hit that big &lt;enter> key. First up, we'll change the ''dir'' variable in section ''[ CA_default ]'' to match the dir from the ''CA.sh'' script. Then we find ''default_days'' and change it to our default certificate lifetime: 370 days. Furthermore, we find the certificate strengt in the ''[ req ]'' section; we can change it to our preferred value of 2048 bits. Now we can put in the optional bits: the default values. Not necessary, but handy. We go to section ''[ req_distinguished_name ]'' and fill them in. For this, we again use the table we've previously compounded. So the changes we've made will amount to something like this: [ CA_default ] dir = /etc/ssl/ca ... default_days = 370 ... [ req ] default_bits = 2048 ... [ req_distinguished_name ] 0.organizationName_default = Saruman.biz stateOrProvinceName_default = Utrecht countryName_default = NL Especially the last section is, again, a pretty arbitrary choice. You could choose not to provide customized default answers (in which case you're stuck with Internet Widgets Pty from Some-State, AU as the default answers). There are more default values in that section of the ''openssl.cnf'' configuration file; go in there and decide what you want. ==the Certificate Authority root certificate== Now with the basic information in place, we can go about generating the certificate itself, and putting it to use. Well, actually we're not going to generate ''one'' certificate, but ''two'': the public one, that we give out to anyone that might want to check the validity of any certificate that claims to have been issued by the Saruman.biz CA, and the private one, with which we can digitally sign certificates so as to prove that they're really issued by said Saruman.biz CA. This is also referred to as a "key pair". To generate the CA's public and private root certificate, as root, execute /usr/lib/ssl/misc/CA.sh -newca With the defaults set as given above, you still get some questions. One is "CA certificate filename". If you do not provide a name but just hit &lt;enter>, the private CA root certificate will be named cakey.pem. Next question is for the PEM passphrase. Make that a strong passphrase or password, keep it very secret, and '''don't forget it!''' (and DON'T write it on a piece of paper; use something like [http://keepass.info keepass] to store your secret passwords).<br> For the next set of questions, you probably have filled in some of the defaults. If you want to leave some entry blank, fill in a period ('''.'''). You'll have to provide the country code, province or state, locality (like city; Saruman.biz leaves this empty), Organization Name, Organizational Unit name (again, empty), and finally the Common Name. This last question is pretty important: the name you put in here is the name under which your CA will go for the next 15 years!! So don't put in a "funny" name, a bland name, or whatever. We put in "Saruman.biz Root CA", somewhat like official root CA's like "Equifax Secure Global eBusiness CA-1" or "Macao Post eSignTrust Root Certification Authority". The script also asks for an email address, which you may or may not provide, a challenge password, and an "optional company name", both of which you can leave blank. The second set of questions concern 9f59d2e5a288f6aa70e254241d56051021750a9f 1916 1914 2008-10-26T20:57:57Z Saruman! 2 /* Editing the CA.sh script */ changed 2048-bit option wikitext text/x-wiki ==Certificates, an introduction== Digital certificates are an extremely important means to identify identities (of users, as well as of servers) on the Internet, or indeed on most any network. For instance, we use them to encrypt network traffic when we use the HTTPS protocol. Thus, we really need certificates. Now, as [http://www.debian-administration.org/articles/618 this article] explains, you can either buy your certificates from a certificate authority like [http://www.verisign.com/ VeriSign], [http://www.thawte.com/ Thawte] or [http://www.equifaxsecure.co.uk/index.html Equifax Secure], but these certificates cost more than a couple of Euro's, and also need to be renewed (usually every year). So the other route, the one we'll be taking, is to create our own Certificate Authority (CA), and use that to sign certificates for our needs (secure webserver, secure mailserver etcetera). Now, "creating a CA" sounds like grave installation and configuration work, but in fact a CA does not have to be an actual service, demon or program. A CA is more like a concept, at the heart of which lies the CA "root certificate". So if we obtain a little set of tools and generate our own root certificate, then we're in business. ==Creating the Certificate Authority (CA) - preparations== To generate the root CA for our own little organization, we first need tools. These tools under Debian come with the OpenSSL software - which you'll usually find already installed. Now to generate the CA root certificate, we'll use a shell script from the OpenSSL package: ''/usr/lib/ssl/misc/CA.sh'', which together with the configuration file ''/etc/ssl/openssl.cnf'' can create our CA root certificate. To that end, we'll first need to decide on some parameters. ===Deciding on CA parameters=== '''How strong''' do we want our root certificate? 1024 bits is the default, but the stronger, the better. We suggest 2048 bits. How long should our '''CA root certificate remain valid'''? The longer, the more convenient - but maybe some day in the future, you feel you don't want certificates from ten years earlies to wander around, expired but otherwise valid. Expiry of the root certificate that goes along with that certificate might help you. So what's an appropriate time for your root CA? That depends. For our home CA, we use 15 years. For a business, the cost of providing new root certificates to all computers, employees, and maybe customers, can be so high that you'd rather have 25 years - or maybe security is paramount, and 5 years is long enough for you. We can't say - but our home CA's use 15 years, because we feel that that's a nice intermediate value. 15 years, including about 4 leap days, comes to 5479 days. '''Where do we want to store''' our CA root certificate? By default, the ''CA.sh'' script feels it must store all generated certificates in ''./demoCA''. That's not very handy for us. We rather have a central location like ''/etc/ssl/ca'' on our central server. How long should '''any generated certificate be valid'''? The default value that the ''CA.sh'' script provides is one year. We find that enough - although we add 7 days to accomodate some overlap when having to regenerate the certificate upon nearing the expiry date (note: we really want to replace certificates ''prior'' to expiry :-) '''What "company" data''' will we enter in the certificate? Several fields must be entered, some of which you could fill out at will. However, it's not exactly clear why you would want to confuse people trying to authenticate you, your webserver or some other connection by filling out, for example, the country with an incorrect or even non-existent code. On the other hand, you can keep your own privacy in mind, and not fill in your full name, but rather your website's name, at the "common name" section of your CA root certificate. Again, this depends on what you're going to use your CA for. We at [https://www.saruman.biz saruman.biz] decided to use the following values: * Organization name: Saruman.biz. We're private persons, not companies, but we want to maintain a minimum of privacy, so we've put this fake entity name here. * Province: Utrecht. Yep, that's a province in the Netherlands, and we live pretty close to it. * Country: NL (that's the Netherlands) Maybe you want to provide more default information to your CA setup; just look further down on how to. So the information we've decided upon is like this: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Parameter !style="background:#ffdead;"|value |- |root certificate encryption |2048 bits |- |root certificate validity |5479 days (15 years) |- |certificate store |''/etc/ssl/ca'' |- |default certificate validity |370 days (1 year) |- |Organization name |Saruman.biz |- |Certificate province/county name (default) |Utrecht |- |Certificate country name (default) |NL |- |} === Editing the ''CA.sh'' script === Actually, you don't need to use the ''CA.sh'' shell script. There's also a ''CA.pl'' perl script. However, if you're more into shell scripting than perl programming, go for the shell script. Now edit ''/usr/lib/ssl/misc/CA.sh''; find the two lines near the top that define the variables ''DAYS'' and ''CADAYS'', and set these to what we want them to be. A little further down, we find the default location ''CATOP=./demoCA''. Change this (relative) path to the (absolute) path we've decided upon. Then, a lot further down, we find the line that's responsible for creating the CA root certificate itself, it's the line that goes ''$REQ -new -keyout ${CATOP}/private/$CAKEY -out ${CATOP}/$CAREQ'' (well actually it's split out over two lines). Here, right after ''-new'' we add ''-newkey rsa:2048''. With all these changes, the three relevant sections in ''CA.sh'' will be changed to something like this: DAYS="-days 370" # 1 year CADAYS="-days 5479" # 15 years ... CATOP=/etc/ssl/ca ... echo "Making CA certificate ..." $REQ -new -newkey rsa:2048 -keyout ${CATOP}/private/$CAKEY \ -out ${CATOP}/$CAREQ === Editing the ''openssl.cnf'' configuration file=== When generating certificates, the OpenSSL tools check the configuration file ''/etc/ssl/openssl.cnf''. It is necessary to match the parameters in there with the choices and changes of the previous sections, and also it's handy to change some of the default parameters that certificates require upon generation. It's important to remember that these parameters will be asked every time you generate a certificate, but it's ofcourse pretty handy if the default value is set for your situation, so you can just hit that big &lt;enter> key. First up, we'll change the ''dir'' variable in section ''[ CA_default ]'' to match the dir from the ''CA.sh'' script. Then we find ''default_days'' and change it to our default certificate lifetime: 370 days. Furthermore, we find the certificate strengt in the ''[ req ]'' section; we can change it to our preferred value of 2048 bits. Now we can put in the optional bits: the default values. Not necessary, but handy. We go to section ''[ req_distinguished_name ]'' and fill them in. For this, we again use the table we've previously compounded. So the changes we've made will amount to something like this: [ CA_default ] dir = /etc/ssl/ca ... default_days = 370 ... [ req ] default_bits = 2048 ... [ req_distinguished_name ] 0.organizationName_default = Saruman.biz stateOrProvinceName_default = Utrecht countryName_default = NL Especially the last section is, again, a pretty arbitrary choice. You could choose not to provide customized default answers (in which case you're stuck with Internet Widgets Pty from Some-State, AU as the default answers). There are more default values in that section of the ''openssl.cnf'' configuration file; go in there and decide what you want. ==the Certificate Authority root certificate== Now with the basic information in place, we can go about generating the certificate itself, and putting it to use. Well, actually we're not going to generate ''one'' certificate, but ''two'': the public one, that we give out to anyone that might want to check the validity of any certificate that claims to have been issued by the Saruman.biz CA, and the private one, with which we can digitally sign certificates so as to prove that they're really issued by said Saruman.biz CA. This is also referred to as a "key pair". To generate the CA's public and private root certificate, as root, execute /usr/lib/ssl/misc/CA.sh -newca With the defaults set as given above, you still get some questions. One is "CA certificate filename". If you do not provide a name but just hit &lt;enter>, the private CA root certificate will be named cakey.pem. Next question is for the PEM passphrase. Make that a strong passphrase or password, keep it very secret, and '''don't forget it!''' (and DON'T write it on a piece of paper; use something like [http://keepass.info keepass] to store your secret passwords).<br> For the next set of questions, you probably have filled in some of the defaults. If you want to leave some entry blank, fill in a period ('''.'''). You'll have to provide the country code, province or state, locality (like city; Saruman.biz leaves this empty), Organization Name, Organizational Unit name (again, empty), and finally the Common Name. This last question is pretty important: the name you put in here is the name under which your CA will go for the next 15 years!! So don't put in a "funny" name, a bland name, or whatever. We put in "Saruman.biz Root CA", somewhat like official root CA's like "Equifax Secure Global eBusiness CA-1" or "Macao Post eSignTrust Root Certification Authority". The script also asks for an email address, which you may or may not provide, a challenge password, and an "optional company name", both of which you can leave blank. The second set of questions concern c6637474070c59af47df8788a83ab1ca84fd4392 1918 1916 2008-10-26T21:42:56Z Saruman! 2 /* the Certificate Authority root certificate */ added inspection wikitext text/x-wiki ==Certificates, an introduction== Digital certificates are an extremely important means to identify identities (of users, as well as of servers) on the Internet, or indeed on most any network. For instance, we use them to encrypt network traffic when we use the HTTPS protocol. Thus, we really need certificates. Now, as [http://www.debian-administration.org/articles/618 this article] explains, you can either buy your certificates from a certificate authority like [http://www.verisign.com/ VeriSign], [http://www.thawte.com/ Thawte] or [http://www.equifaxsecure.co.uk/index.html Equifax Secure], but these certificates cost more than a couple of Euro's, and also need to be renewed (usually every year). So the other route, the one we'll be taking, is to create our own Certificate Authority (CA), and use that to sign certificates for our needs (secure webserver, secure mailserver etcetera). Now, "creating a CA" sounds like grave installation and configuration work, but in fact a CA does not have to be an actual service, demon or program. A CA is more like a concept, at the heart of which lies the CA "root certificate". So if we obtain a little set of tools and generate our own root certificate, then we're in business. ==Creating the Certificate Authority (CA) - preparations== To generate the root CA for our own little organization, we first need tools. These tools under Debian come with the OpenSSL software - which you'll usually find already installed. Now to generate the CA root certificate, we'll use a shell script from the OpenSSL package: ''/usr/lib/ssl/misc/CA.sh'', which together with the configuration file ''/etc/ssl/openssl.cnf'' can create our CA root certificate. To that end, we'll first need to decide on some parameters. ===Deciding on CA parameters=== '''How strong''' do we want our root certificate? 1024 bits is the default, but the stronger, the better. We suggest 2048 bits. How long should our '''CA root certificate remain valid'''? The longer, the more convenient - but maybe some day in the future, you feel you don't want certificates from ten years earlies to wander around, expired but otherwise valid. Expiry of the root certificate that goes along with that certificate might help you. So what's an appropriate time for your root CA? That depends. For our home CA, we use 15 years. For a business, the cost of providing new root certificates to all computers, employees, and maybe customers, can be so high that you'd rather have 25 years - or maybe security is paramount, and 5 years is long enough for you. We can't say - but our home CA's use 15 years, because we feel that that's a nice intermediate value. 15 years, including about 4 leap days, comes to 5479 days. '''Where do we want to store''' our CA root certificate? By default, the ''CA.sh'' script feels it must store all generated certificates in ''./demoCA''. That's not very handy for us. We rather have a central location like ''/etc/ssl/ca'' on our central server. How long should '''any generated certificate be valid'''? The default value that the ''CA.sh'' script provides is one year. We find that enough - although we add 7 days to accomodate some overlap when having to regenerate the certificate upon nearing the expiry date (note: we really want to replace certificates ''prior'' to expiry :-) '''What "company" data''' will we enter in the certificate? Several fields must be entered, some of which you could fill out at will. However, it's not exactly clear why you would want to confuse people trying to authenticate you, your webserver or some other connection by filling out, for example, the country with an incorrect or even non-existent code. On the other hand, you can keep your own privacy in mind, and not fill in your full name, but rather your website's name, at the "common name" section of your CA root certificate. Again, this depends on what you're going to use your CA for. We at [https://www.saruman.biz saruman.biz] decided to use the following values: * Organization name: Saruman.biz. We're private persons, not companies, but we want to maintain a minimum of privacy, so we've put this fake entity name here. * Province: Utrecht. Yep, that's a province in the Netherlands, and we live pretty close to it. * Country: NL (that's the Netherlands) Maybe you want to provide more default information to your CA setup; just look further down on how to. So the information we've decided upon is like this: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Parameter !style="background:#ffdead;"|value |- |root certificate encryption |2048 bits |- |root certificate validity |5479 days (15 years) |- |certificate store |''/etc/ssl/ca'' |- |default certificate validity |370 days (1 year) |- |Organization name |Saruman.biz |- |Certificate province/county name (default) |Utrecht |- |Certificate country name (default) |NL |- |} === Editing the ''CA.sh'' script === Actually, you don't need to use the ''CA.sh'' shell script. There's also a ''CA.pl'' perl script. However, if you're more into shell scripting than perl programming, go for the shell script. Now edit ''/usr/lib/ssl/misc/CA.sh''; find the two lines near the top that define the variables ''DAYS'' and ''CADAYS'', and set these to what we want them to be. A little further down, we find the default location ''CATOP=./demoCA''. Change this (relative) path to the (absolute) path we've decided upon. Then, a lot further down, we find the line that's responsible for creating the CA root certificate itself, it's the line that goes ''$REQ -new -keyout ${CATOP}/private/$CAKEY -out ${CATOP}/$CAREQ'' (well actually it's split out over two lines). Here, right after ''-new'' we add ''-newkey rsa:2048''. With all these changes, the three relevant sections in ''CA.sh'' will be changed to something like this: DAYS="-days 370" # 1 year CADAYS="-days 5479" # 15 years ... CATOP=/etc/ssl/ca ... echo "Making CA certificate ..." $REQ -new -newkey rsa:2048 -keyout ${CATOP}/private/$CAKEY \ -out ${CATOP}/$CAREQ === Editing the ''openssl.cnf'' configuration file=== When generating certificates, the OpenSSL tools check the configuration file ''/etc/ssl/openssl.cnf''. It is necessary to match the parameters in there with the choices and changes of the previous sections, and also it's handy to change some of the default parameters that certificates require upon generation. It's important to remember that these parameters will be asked every time you generate a certificate, but it's ofcourse pretty handy if the default value is set for your situation, so you can just hit that big &lt;enter> key. First up, we'll change the ''dir'' variable in section ''[ CA_default ]'' to match the dir from the ''CA.sh'' script. Then we find ''default_days'' and change it to our default certificate lifetime: 370 days. Furthermore, we find the certificate strengt in the ''[ req ]'' section; we can change it to our preferred value of 2048 bits. Now we can put in the optional bits: the default values. Not necessary, but handy. We go to section ''[ req_distinguished_name ]'' and fill them in. For this, we again use the table we've previously compounded. So the changes we've made will amount to something like this: [ CA_default ] dir = /etc/ssl/ca ... default_days = 370 ... [ req ] default_bits = 2048 ... [ req_distinguished_name ] 0.organizationName_default = Saruman.biz stateOrProvinceName_default = Utrecht countryName_default = NL Especially the last section is, again, a pretty arbitrary choice. You could choose not to provide customized default answers (in which case you're stuck with Internet Widgets Pty from Some-State, AU as the default answers). There are more default values in that section of the ''openssl.cnf'' configuration file; go in there and decide what you want. ==the Certificate Authority root certificate key pair== Now with the basic information in place, we can go about generating the certificate itself, and putting it to use. Well, actually we're not going to generate ''one'' certificate, but ''two'': the public one, that we give out to anyone that might want to check the validity of any certificate that claims to have been issued by the Saruman.biz CA, and the private one, with which we can digitally sign certificates so as to prove that they're really issued by said Saruman.biz CA. This is also referred to as a "key pair". To generate the CA's public and private root certificate, as root, execute /usr/lib/ssl/misc/CA.sh -newca With the defaults set as given above, you still get some questions. One is "CA certificate filename". This actually requests from you another certificate with which to sign the one we're creating. However, we're generating our root certificate, so we leave this empty and just hit &lt;enter>. Next question is for the PEM passphrase. Make that a strong passphrase or password, keep it very secret, and '''don't forget it!''' (and DON'T write it on a piece of paper; use something like [http://keepass.info keepass] to store your secret passwords). For the next set of questions, you probably have filled in some of the defaults. If you want to leave some entry blank, fill in a period ('''.'''). You'll have to provide the country code, province or state, locality (like city; Saruman.biz leaves this empty), Organization Name, Organizational Unit name (again, empty), and finally the Common Name. This last question is pretty important: the name you put in here is the name under which your CA will go for the next 15 years!! So don't put in a "funny" name, a bland name, or whatever. We put in "Saruman.biz Root CA", somewhat like official root CA's like "Equifax Secure Global eBusiness CA-1" or "Macao Post eSignTrust Root Certification Authority". The script also asks for an email address, which you may or may not provide, a challenge password, and an "optional company name", both of which you can leave blank because we're not sending a certificate signing request out to someone else, but signing it ourselves.<br> Having provided this information, we've actually already created one half of the key pair, namely the private key. It'll be ''/etc/openssl/ca/private/ca.pem'', and is protected by our chosen very strong password. However, we now need the public key, self-signed with the private key. The next step in our CA creation process thus ''again'' asks for the passphrase. Since this is the second step in a two-step process, we again put in the passphrase we've already provided. However, now the shellscript uses this to unlock the private key we've (already) created, and then use it to sign the public key we're now creating. However, the passphrase is ''all'' that it asks. It now generates a signing request (''/etc/openssl/ca/careq.pem''), then uses the private key to sign it, and then generate the public key, to be found in ''/etc/openssl/ca/cacert.pem''. You can remove ''careq.pem'' after you've inspected the ''cacert.pem''. So now we've got two root certificates, namely '''private''' key ''/etc/openssl/ca/private/ca.pem'' and '''public''' key ''/etc/openssl/ca/cacert.pem''. NEVER send your public key out to ANYONE! Protect that key, and its passphrase, with your life. If you lose the file, lose the passphrase, or the key gets compromised (lost to an unknown party) then you've got to replace your root certificates AND you'll have to re-issue ALL certificates that you've ever signed (we're not going into certificate revocation here). You can inspect your certificates (when you're in directory ''/etc/openssl/ca'') with commands like this: openssl x509 -in cacert.pem -noout -text openssl x509 -in cacert.pem -noout -dates openssl x509 -in cacert.pem -noout -purpose Note from the last command that this certificate is obviously a root certificate: it can sign everything but the kitchen sink. 8277f806d04259c1dab62c7f8f03e55e818583c6 1921 1918 2008-10-26T21:50:18Z Saruman! 2 /* the Certificate Authority root certificate key pair */ added link to "creating certificates" section wikitext text/x-wiki ==Certificates, an introduction== Digital certificates are an extremely important means to identify identities (of users, as well as of servers) on the Internet, or indeed on most any network. For instance, we use them to encrypt network traffic when we use the HTTPS protocol. Thus, we really need certificates. Now, as [http://www.debian-administration.org/articles/618 this article] explains, you can either buy your certificates from a certificate authority like [http://www.verisign.com/ VeriSign], [http://www.thawte.com/ Thawte] or [http://www.equifaxsecure.co.uk/index.html Equifax Secure], but these certificates cost more than a couple of Euro's, and also need to be renewed (usually every year). So the other route, the one we'll be taking, is to create our own Certificate Authority (CA), and use that to sign certificates for our needs (secure webserver, secure mailserver etcetera). Now, "creating a CA" sounds like grave installation and configuration work, but in fact a CA does not have to be an actual service, demon or program. A CA is more like a concept, at the heart of which lies the CA "root certificate". So if we obtain a little set of tools and generate our own root certificate, then we're in business. ==Creating the Certificate Authority (CA) - preparations== To generate the root CA for our own little organization, we first need tools. These tools under Debian come with the OpenSSL software - which you'll usually find already installed. Now to generate the CA root certificate, we'll use a shell script from the OpenSSL package: ''/usr/lib/ssl/misc/CA.sh'', which together with the configuration file ''/etc/ssl/openssl.cnf'' can create our CA root certificate. To that end, we'll first need to decide on some parameters. ===Deciding on CA parameters=== '''How strong''' do we want our root certificate? 1024 bits is the default, but the stronger, the better. We suggest 2048 bits. How long should our '''CA root certificate remain valid'''? The longer, the more convenient - but maybe some day in the future, you feel you don't want certificates from ten years earlies to wander around, expired but otherwise valid. Expiry of the root certificate that goes along with that certificate might help you. So what's an appropriate time for your root CA? That depends. For our home CA, we use 15 years. For a business, the cost of providing new root certificates to all computers, employees, and maybe customers, can be so high that you'd rather have 25 years - or maybe security is paramount, and 5 years is long enough for you. We can't say - but our home CA's use 15 years, because we feel that that's a nice intermediate value. 15 years, including about 4 leap days, comes to 5479 days. '''Where do we want to store''' our CA root certificate? By default, the ''CA.sh'' script feels it must store all generated certificates in ''./demoCA''. That's not very handy for us. We rather have a central location like ''/etc/ssl/ca'' on our central server. How long should '''any generated certificate be valid'''? The default value that the ''CA.sh'' script provides is one year. We find that enough - although we add 7 days to accomodate some overlap when having to regenerate the certificate upon nearing the expiry date (note: we really want to replace certificates ''prior'' to expiry :-) '''What "company" data''' will we enter in the certificate? Several fields must be entered, some of which you could fill out at will. However, it's not exactly clear why you would want to confuse people trying to authenticate you, your webserver or some other connection by filling out, for example, the country with an incorrect or even non-existent code. On the other hand, you can keep your own privacy in mind, and not fill in your full name, but rather your website's name, at the "common name" section of your CA root certificate. Again, this depends on what you're going to use your CA for. We at [https://www.saruman.biz saruman.biz] decided to use the following values: * Organization name: Saruman.biz. We're private persons, not companies, but we want to maintain a minimum of privacy, so we've put this fake entity name here. * Province: Utrecht. Yep, that's a province in the Netherlands, and we live pretty close to it. * Country: NL (that's the Netherlands) Maybe you want to provide more default information to your CA setup; just look further down on how to. So the information we've decided upon is like this: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Parameter !style="background:#ffdead;"|value |- |root certificate encryption |2048 bits |- |root certificate validity |5479 days (15 years) |- |certificate store |''/etc/ssl/ca'' |- |default certificate validity |370 days (1 year) |- |Organization name |Saruman.biz |- |Certificate province/county name (default) |Utrecht |- |Certificate country name (default) |NL |- |} === Editing the ''CA.sh'' script === Actually, you don't need to use the ''CA.sh'' shell script. There's also a ''CA.pl'' perl script. However, if you're more into shell scripting than perl programming, go for the shell script. Now edit ''/usr/lib/ssl/misc/CA.sh''; find the two lines near the top that define the variables ''DAYS'' and ''CADAYS'', and set these to what we want them to be. A little further down, we find the default location ''CATOP=./demoCA''. Change this (relative) path to the (absolute) path we've decided upon. Then, a lot further down, we find the line that's responsible for creating the CA root certificate itself, it's the line that goes ''$REQ -new -keyout ${CATOP}/private/$CAKEY -out ${CATOP}/$CAREQ'' (well actually it's split out over two lines). Here, right after ''-new'' we add ''-newkey rsa:2048''. With all these changes, the three relevant sections in ''CA.sh'' will be changed to something like this: DAYS="-days 370" # 1 year CADAYS="-days 5479" # 15 years ... CATOP=/etc/ssl/ca ... echo "Making CA certificate ..." $REQ -new -newkey rsa:2048 -keyout ${CATOP}/private/$CAKEY \ -out ${CATOP}/$CAREQ === Editing the ''openssl.cnf'' configuration file=== When generating certificates, the OpenSSL tools check the configuration file ''/etc/ssl/openssl.cnf''. It is necessary to match the parameters in there with the choices and changes of the previous sections, and also it's handy to change some of the default parameters that certificates require upon generation. It's important to remember that these parameters will be asked every time you generate a certificate, but it's ofcourse pretty handy if the default value is set for your situation, so you can just hit that big &lt;enter> key. First up, we'll change the ''dir'' variable in section ''[ CA_default ]'' to match the dir from the ''CA.sh'' script. Then we find ''default_days'' and change it to our default certificate lifetime: 370 days. Furthermore, we find the certificate strengt in the ''[ req ]'' section; we can change it to our preferred value of 2048 bits. Now we can put in the optional bits: the default values. Not necessary, but handy. We go to section ''[ req_distinguished_name ]'' and fill them in. For this, we again use the table we've previously compounded. So the changes we've made will amount to something like this: [ CA_default ] dir = /etc/ssl/ca ... default_days = 370 ... [ req ] default_bits = 2048 ... [ req_distinguished_name ] 0.organizationName_default = Saruman.biz stateOrProvinceName_default = Utrecht countryName_default = NL Especially the last section is, again, a pretty arbitrary choice. You could choose not to provide customized default answers (in which case you're stuck with Internet Widgets Pty from Some-State, AU as the default answers). There are more default values in that section of the ''openssl.cnf'' configuration file; go in there and decide what you want. ==the Certificate Authority root certificate== Now with the basic information in place, we can go about generating the certificate itself, and putting it to use. Well, actually we're not going to generate ''one'' certificate, but ''two'': the public one, that we give out to anyone that might want to check the validity of any certificate that claims to have been issued by the Saruman.biz CA, and the private one, with which we can digitally sign certificates so as to prove that they're really issued by said Saruman.biz CA. This is also referred to as a "key pair". ===Creating the CA root certificate key pair=== To generate the CA's public and private root certificate, as root, execute /usr/lib/ssl/misc/CA.sh -newca With the defaults set as given above, you still get some questions. One is "CA certificate filename". This actually requests from you another certificate with which to sign the one we're creating. However, we're generating our root certificate, so we leave this empty and just hit &lt;enter>. Next question is for the PEM passphrase. Make that a strong passphrase or password, keep it very secret, and '''don't forget it!''' (and DON'T write it on a piece of paper; use something like [http://keepass.info keepass] to store your secret passwords). For the next set of questions, you probably have filled in some of the defaults. If you want to leave some entry blank, fill in a period ('''.'''). You'll have to provide the country code, province or state, locality (like city; Saruman.biz leaves this empty), Organization Name, Organizational Unit name (again, empty), and finally the Common Name. This last question is pretty important: the name you put in here is the name under which your CA will go for the next 15 years!! So don't put in a "funny" name, a bland name, or whatever. We put in "Saruman.biz Root CA", somewhat like official root CA's like "Equifax Secure Global eBusiness CA-1" or "Macao Post eSignTrust Root Certification Authority". The script also asks for an email address, which you may or may not provide, a challenge password, and an "optional company name", both of which you can leave blank because we're not sending a certificate signing request out to someone else, but signing it ourselves.<br> Having provided this information, we've actually already created one half of the key pair, namely the private key. It'll be ''/etc/openssl/ca/private/ca.pem'', and is protected by our chosen very strong password. However, we now need the public key, self-signed with the private key. The next step in our CA creation process thus ''again'' asks for the passphrase. Since this is the second step in a two-step process, we again put in the passphrase we've already provided. However, now the shellscript uses this to unlock the private key we've (already) created, and then use it to sign the public key we're now creating. However, the passphrase is ''all'' that it asks. It now generates a signing request (''/etc/openssl/ca/careq.pem''), then uses the private key to sign it, and then generate the public key, to be found in ''/etc/openssl/ca/cacert.pem''. You can remove ''careq.pem'' after you've inspected the ''cacert.pem''. So now we've got two root certificates, namely '''private''' key ''/etc/openssl/ca/private/ca.pem'' and '''public''' key ''/etc/openssl/ca/cacert.pem''. NEVER send your public key out to ANYONE! Protect that key, and its passphrase, with your life. If you lose the file, lose the passphrase, or the key gets compromised (lost to an unknown party) then you've got to replace your root certificates AND you'll have to re-issue ALL certificates that you've ever signed (we're not going into certificate revocation here). You can inspect your certificates (when you're in directory ''/etc/openssl/ca'') with commands like this: openssl x509 -in cacert.pem -noout -text openssl x509 -in cacert.pem -noout -dates openssl x509 -in cacert.pem -noout -purpose Note from the last command that this certificate is obviously a root certificate: it can sign everything but the kitchen sink. ===We've got the CA certificate, now what?=== With the root CA certificates available to us, we've got two things to do: * guard very carefully the public and (especially) the private key file * sign certificates for our own use The first means we've got to keep a copy of the private key file in some other, safe location, and we've got to secure the private key on the server where it sits - both the machine and the file. It might even be wise to remove the private key, and keep it on a USB stick, and only read it when signing certificates. The second thing means we've got to generate keys for SSL and TLS connections, just as we need them. This is covered in our [[Creating digital certificates with our root certificate | creating digital certificates]] section. dac613d070b85a42f33e84713bfa9dce4a59df05 1937 1921 2008-10-27T17:44:15Z Saruman! 2 /* Creating the CA root certificate key pair */ edited key name wikitext text/x-wiki ==Certificates, an introduction== Digital certificates are an extremely important means to identify identities (of users, as well as of servers) on the Internet, or indeed on most any network. For instance, we use them to encrypt network traffic when we use the HTTPS protocol. Thus, we really need certificates. Now, as [http://www.debian-administration.org/articles/618 this article] explains, you can either buy your certificates from a certificate authority like [http://www.verisign.com/ VeriSign], [http://www.thawte.com/ Thawte] or [http://www.equifaxsecure.co.uk/index.html Equifax Secure], but these certificates cost more than a couple of Euro's, and also need to be renewed (usually every year). So the other route, the one we'll be taking, is to create our own Certificate Authority (CA), and use that to sign certificates for our needs (secure webserver, secure mailserver etcetera). Now, "creating a CA" sounds like grave installation and configuration work, but in fact a CA does not have to be an actual service, demon or program. A CA is more like a concept, at the heart of which lies the CA "root certificate". So if we obtain a little set of tools and generate our own root certificate, then we're in business. ==Creating the Certificate Authority (CA) - preparations== To generate the root CA for our own little organization, we first need tools. These tools under Debian come with the OpenSSL software - which you'll usually find already installed. Now to generate the CA root certificate, we'll use a shell script from the OpenSSL package: ''/usr/lib/ssl/misc/CA.sh'', which together with the configuration file ''/etc/ssl/openssl.cnf'' can create our CA root certificate. To that end, we'll first need to decide on some parameters. ===Deciding on CA parameters=== '''How strong''' do we want our root certificate? 1024 bits is the default, but the stronger, the better. We suggest 2048 bits. How long should our '''CA root certificate remain valid'''? The longer, the more convenient - but maybe some day in the future, you feel you don't want certificates from ten years earlies to wander around, expired but otherwise valid. Expiry of the root certificate that goes along with that certificate might help you. So what's an appropriate time for your root CA? That depends. For our home CA, we use 15 years. For a business, the cost of providing new root certificates to all computers, employees, and maybe customers, can be so high that you'd rather have 25 years - or maybe security is paramount, and 5 years is long enough for you. We can't say - but our home CA's use 15 years, because we feel that that's a nice intermediate value. 15 years, including about 4 leap days, comes to 5479 days. '''Where do we want to store''' our CA root certificate? By default, the ''CA.sh'' script feels it must store all generated certificates in ''./demoCA''. That's not very handy for us. We rather have a central location like ''/etc/ssl/ca'' on our central server. How long should '''any generated certificate be valid'''? The default value that the ''CA.sh'' script provides is one year. We find that enough - although we add 7 days to accomodate some overlap when having to regenerate the certificate upon nearing the expiry date (note: we really want to replace certificates ''prior'' to expiry :-) '''What "company" data''' will we enter in the certificate? Several fields must be entered, some of which you could fill out at will. However, it's not exactly clear why you would want to confuse people trying to authenticate you, your webserver or some other connection by filling out, for example, the country with an incorrect or even non-existent code. On the other hand, you can keep your own privacy in mind, and not fill in your full name, but rather your website's name, at the "common name" section of your CA root certificate. Again, this depends on what you're going to use your CA for. We at [https://www.saruman.biz saruman.biz] decided to use the following values: * Organization name: Saruman.biz. We're private persons, not companies, but we want to maintain a minimum of privacy, so we've put this fake entity name here. * Province: Utrecht. Yep, that's a province in the Netherlands, and we live pretty close to it. * Country: NL (that's the Netherlands) Maybe you want to provide more default information to your CA setup; just look further down on how to. So the information we've decided upon is like this: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Parameter !style="background:#ffdead;"|value |- |root certificate encryption |2048 bits |- |root certificate validity |5479 days (15 years) |- |certificate store |''/etc/ssl/ca'' |- |default certificate validity |370 days (1 year) |- |Organization name |Saruman.biz |- |Certificate province/county name (default) |Utrecht |- |Certificate country name (default) |NL |- |} === Editing the ''CA.sh'' script === Actually, you don't need to use the ''CA.sh'' shell script. There's also a ''CA.pl'' perl script. However, if you're more into shell scripting than perl programming, go for the shell script. Now edit ''/usr/lib/ssl/misc/CA.sh''; find the two lines near the top that define the variables ''DAYS'' and ''CADAYS'', and set these to what we want them to be. A little further down, we find the default location ''CATOP=./demoCA''. Change this (relative) path to the (absolute) path we've decided upon. Then, a lot further down, we find the line that's responsible for creating the CA root certificate itself, it's the line that goes ''$REQ -new -keyout ${CATOP}/private/$CAKEY -out ${CATOP}/$CAREQ'' (well actually it's split out over two lines). Here, right after ''-new'' we add ''-newkey rsa:2048''. With all these changes, the three relevant sections in ''CA.sh'' will be changed to something like this: DAYS="-days 370" # 1 year CADAYS="-days 5479" # 15 years ... CATOP=/etc/ssl/ca ... echo "Making CA certificate ..." $REQ -new -newkey rsa:2048 -keyout ${CATOP}/private/$CAKEY \ -out ${CATOP}/$CAREQ === Editing the ''openssl.cnf'' configuration file=== When generating certificates, the OpenSSL tools check the configuration file ''/etc/ssl/openssl.cnf''. It is necessary to match the parameters in there with the choices and changes of the previous sections, and also it's handy to change some of the default parameters that certificates require upon generation. It's important to remember that these parameters will be asked every time you generate a certificate, but it's ofcourse pretty handy if the default value is set for your situation, so you can just hit that big &lt;enter> key. First up, we'll change the ''dir'' variable in section ''[ CA_default ]'' to match the dir from the ''CA.sh'' script. Then we find ''default_days'' and change it to our default certificate lifetime: 370 days. Furthermore, we find the certificate strengt in the ''[ req ]'' section; we can change it to our preferred value of 2048 bits. Now we can put in the optional bits: the default values. Not necessary, but handy. We go to section ''[ req_distinguished_name ]'' and fill them in. For this, we again use the table we've previously compounded. So the changes we've made will amount to something like this: [ CA_default ] dir = /etc/ssl/ca ... default_days = 370 ... [ req ] default_bits = 2048 ... [ req_distinguished_name ] 0.organizationName_default = Saruman.biz stateOrProvinceName_default = Utrecht countryName_default = NL Especially the last section is, again, a pretty arbitrary choice. You could choose not to provide customized default answers (in which case you're stuck with Internet Widgets Pty from Some-State, AU as the default answers). There are more default values in that section of the ''openssl.cnf'' configuration file; go in there and decide what you want. ==the Certificate Authority root certificate== Now with the basic information in place, we can go about generating the certificate itself, and putting it to use. Well, actually we're not going to generate ''one'' certificate, but ''two'': the public one, that we give out to anyone that might want to check the validity of any certificate that claims to have been issued by the Saruman.biz CA, and the private one, with which we can digitally sign certificates so as to prove that they're really issued by said Saruman.biz CA. This is also referred to as a "key pair". ===Creating the CA root certificate key pair=== To generate the CA's public and private root certificate, as root, execute /usr/lib/ssl/misc/CA.sh -newca With the defaults set as given above, you still get some questions. One is "CA certificate filename". This actually requests from you another certificate with which to sign the one we're creating. However, we're generating our root certificate, so we leave this empty and just hit &lt;enter>. Next question is for the PEM passphrase. Make that a strong passphrase or password, keep it very secret, and '''don't forget it!''' (and DON'T write it on a piece of paper; use something like [http://keepass.info keepass] to store your secret passwords). For the next set of questions, you probably have filled in some of the defaults. If you want to leave some entry blank, fill in a period ('''.'''). You'll have to provide the country code, province or state, locality (like city; Saruman.biz leaves this empty), Organization Name, Organizational Unit name (again, empty), and finally the Common Name. This last question is pretty important: the name you put in here is the name under which your CA will go for the next 15 years!! So don't put in a "funny" name, a bland name, or whatever. We put in "Saruman.biz Root CA", somewhat like official root CA's like "Equifax Secure Global eBusiness CA-1" or "Macao Post eSignTrust Root Certification Authority". The script also asks for an email address, which you may or may not provide, a challenge password, and an "optional company name", both of which you can leave blank because we're not sending a certificate signing request out to someone else, but signing it ourselves.<br> Having provided this information, we've actually already created one half of the key pair, namely the private key. It'll be ''/etc/openssl/ca/private/ca.pem'', and is protected by our chosen very strong password. However, we now need the public key, self-signed with the private key. The next step in our CA creation process thus ''again'' asks for the passphrase. Since this is the second step in a two-step process, we again put in the passphrase we've already provided. However, now the shellscript uses this to unlock the private key we've (already) created, and then use it to sign the public key we're now creating. However, the passphrase is ''all'' that it asks. It now generates a signing request (''/etc/openssl/ca/careq.pem''), then uses the private key to sign it, and then generate the public key, to be found in ''/etc/openssl/ca/cacert.pem''. You can remove ''careq.pem'' after you've inspected the ''cacert.pem''. So now we've got two root certificates, namely '''private''' key ''/etc/openssl/ca/private/cakey.pem'' and '''public''' key ''/etc/openssl/ca/cacert.pem''. NEVER send your public key out to ANYONE! Protect that key, and its passphrase, with your life. If you lose the file, lose the passphrase, or the key gets compromised (lost to an unknown party) then you've got to replace your root certificates AND you'll have to re-issue ALL certificates that you've ever signed (we're not going into certificate revocation here). You can inspect your certificates (when you're in directory ''/etc/openssl/ca'') with commands like this: openssl x509 -in cacert.pem -noout -text openssl x509 -in cacert.pem -noout -dates openssl x509 -in cacert.pem -noout -purpose Note from the last command that this certificate is obviously a root certificate: it can sign everything but the kitchen sink. ===We've got the CA certificate, now what?=== With the root CA certificates available to us, we've got two things to do: * guard very carefully the public and (especially) the private key file * sign certificates for our own use The first means we've got to keep a copy of the private key file in some other, safe location, and we've got to secure the private key on the server where it sits - both the machine and the file. It might even be wise to remove the private key, and keep it on a USB stick, and only read it when signing certificates. The second thing means we've got to generate keys for SSL and TLS connections, just as we need them. This is covered in our [[Creating digital certificates with our root certificate | creating digital certificates]] section. c59bad099448799c49d1356b76d00a64be1c692c 0 1483 1915 1839 2008-10-26T20:38:03Z Insomnia 3 routing wikitext text/x-wiki == Hardware == Requirements wireless-tools (for iwconfig) Bridge-utils Hostapd Hostap-utils ?? I used an old netgear wireless pci card. To see wich chipset it has type lspci 00:0e.0 Ethernet controller: Atheros Communications Inc. AR5212/AR5213 Multiprotocol MAC/baseband processor (rev 01) The atheros chip uses the madwifi driver http://sourceforge.net Download the driver and compile the module. Or use the 2.6.27.2 kernel where the atheros chip is supported as a module. Use modprobe ath9k make install modprobe ath_pci Now you should see the card thinner:/# iwconfig lo no wireless extensions. eth0 no wireless extensions. eth1 no wireless extensions. wifi0 no wireless extensions. ath0 IEEE 802.11g ESSID:"" Nickname:"" Mode:Managed Frequency:2.437 GHz Access Point: Not-Associated Bit Rate:0 kb/s Tx-Power:14 dBm Sensitivity=1/1 Retry:off RTS thr:off Fragment thr:off Encryption key:off Power Management:off Link Quality=0/70 Signal level=-96 dBm Noise level=-96 dBm Rx invalid nwid:4378 Rx invalid crypt:0 Rx invalid frag:0 Tx excessive retries:0 Invalid misc:0 Missed beacon:0 To bring the card up #ifconfig ath0 up And to scan for networks #wlanconfig ath0 list scan And for more info #iwlist ath0 scan #wlanconfig ath0 destroy #wlanconfig ath0 create wlandev wifi0 wlanmode ap ath0 IEEE 802.11g ESSID:"" Nickname:"" Mode:Master Frequency:2.412 GHz Access Point: 00:09:5B:C3:97:3E Now create a new text file named /etc/hostapd/wpa_psk and paste your pass phrase as: 00:00:00:00:00:00 PASSPHRASE Turn on the routing engine echo 1 > /proc/sys/net/ipv4/ip_forward Create the routing rule route add -net 192.168.70.0 netmask 255.255.255.0 gateway 192.168.70.7 dev eth0 914ff083a788d23c0bfc23d502d36856a98d874f 1917 1915 2008-10-26T21:30:32Z Insomnia 3 wikitext text/x-wiki We want to build a wireless access point (AP) on a debian based server. You can use any wireless pci adapter as long as it supports ''iwconfig ath0 mode master'' If you get a error try another driver. I use the madwifi driver for my atheros based card. == Hardware == Requirements wireless-tools (for iwconfig) Bridge-utils Hostapd Hostap-utils ?? I used an old netgear wireless pci card. To see wich chipset it has type lspci 00:0e.0 Ethernet controller: Atheros Communications Inc. AR5212/AR5213 Multiprotocol MAC/baseband processor (rev 01) The atheros chip uses the madwifi driver http://sourceforge.net Download the driver and compile the module. Or use the 2.6.27.2 kernel where the atheros chip is supported as a module. Use modprobe ath9k make install modprobe ath_pci Now you should see the card thinner:/# iwconfig lo no wireless extensions. eth0 no wireless extensions. eth1 no wireless extensions. wifi0 no wireless extensions. ath0 IEEE 802.11g ESSID:"" Nickname:"" Mode:Managed Frequency:2.437 GHz Access Point: Not-Associated Bit Rate:0 kb/s Tx-Power:14 dBm Sensitivity=1/1 Retry:off RTS thr:off Fragment thr:off Encryption key:off Power Management:off Link Quality=0/70 Signal level=-96 dBm Noise level=-96 dBm Rx invalid nwid:4378 Rx invalid crypt:0 Rx invalid frag:0 Tx excessive retries:0 Invalid misc:0 Missed beacon:0 To bring the card up #ifconfig ath0 up And to scan for networks #wlanconfig ath0 list scan And for more info #iwlist ath0 scan #wlanconfig ath0 destroy #wlanconfig ath0 create wlandev wifi0 wlanmode ap ath0 IEEE 802.11g ESSID:"" Nickname:"" Mode:Master Frequency:2.412 GHz Access Point: 00:09:5B:C3:97:3E Now create a new text file named /etc/hostapd/wpa_psk and paste your pass phrase as: 00:00:00:00:00:00 PASSPHRASE Turn on the routing engine echo 1 > /proc/sys/net/ipv4/ip_forward Create the routing rule route add -net 192.168.70.0 netmask 255.255.255.0 gateway 192.168.70.7 dev eth0 500b2a3f99043844c078959b18b865af69d5e5e4 1978 1917 2008-11-02T00:15:03Z Insomnia 3 Firmware update wikitext text/x-wiki We want to build a wireless access point (AP) on a debian based server. You can use any wireless pci adapter as long as it supports ''iwconfig ath0 mode master'' If you get a error try another driver. I use the madwifi driver for my atheros based card. == Hardware == Requirements wireless-tools (for iwconfig) Bridge-utils Hostapd Hostap-utils ?? I used an old netgear wireless pci card. To see wich chipset it has type lspci 00:0e.0 Ethernet controller: Atheros Communications Inc. AR5212/AR5213 Multiprotocol MAC/baseband processor (rev 01) The atheros chip uses the madwifi driver http://sourceforge.net Download the driver and compile the module. Or use the 2.6.27.2 kernel where the atheros chip is supported as a module. Use modprobe ath9k make install modprobe ath_pci Now you should see the card thinner:/# iwconfig lo no wireless extensions. eth0 no wireless extensions. eth1 no wireless extensions. wifi0 no wireless extensions. ath0 IEEE 802.11g ESSID:"" Nickname:"" Mode:Managed Frequency:2.437 GHz Access Point: Not-Associated Bit Rate:0 kb/s Tx-Power:14 dBm Sensitivity=1/1 Retry:off RTS thr:off Fragment thr:off Encryption key:off Power Management:off Link Quality=0/70 Signal level=-96 dBm Noise level=-96 dBm Rx invalid nwid:4378 Rx invalid crypt:0 Rx invalid frag:0 Tx excessive retries:0 Invalid misc:0 Missed beacon:0 To bring the card up #ifconfig ath0 up And to scan for networks #wlanconfig ath0 list scan And for more info #iwlist ath0 scan #wlanconfig ath0 destroy #wlanconfig ath0 create wlandev wifi0 wlanmode ap ath0 IEEE 802.11g ESSID:"" Nickname:"" Mode:Master Frequency:2.412 GHz Access Point: 00:09:5B:C3:97:3E Now create a new text file named /etc/hostapd/wpa_psk and paste your pass phrase as: 00:00:00:00:00:00 PASSPHRASE Turn on the routing engine echo 1 > /proc/sys/net/ipv4/ip_forward Create the routing rule route add -net 192.168.70.0 netmask 255.255.255.0 gateway 192.168.70.7 dev eth0 == Firmware update == Prism2/2.5/3 cards and Host AP driver support two different mechanism of upgrading the card firmware. Firmware images (primary and station) can be downloaded either into volatile memory (RAM download) or non-volatile memory (flash upgrade). Firmware images downloaded into volatile memory are lost when the card is resetted, so they are quite safe. Flash upgrade with incorrect images may cause permanent problems (i.e., render the card useless), so certain amount of caution is always recommended for this. Check your existing firmware hostap_diag wlan0 329144de894c019e99ee538c9cd6d14dbc4c9f65 0 1452 1944 1555 2008-10-27T21:01:46Z 82.161.20.132 0 wikitext text/x-wiki == The Documentation Project== spamerdespam [www.linuz.nl] Documentation in ICT projects is a tough cookie (maybe outside of ICT as well, but that's no concern of ours at this moment). What the ICT profession seems to lack is * a thorough understanding of the fundamental problems that surround ICT documentation * taxonomies of the different documentation purposes, target audiences (with their experience levels), and document types * a methodology to create, review and maintain ICT documentation of sufficient quality, against reasonable cost * templates, guidelines and best practices to assist such a methodology * some sort of overview of the different documentation management solutions that exist, ranging from the venerable binders with photocopies and printouts, through fileshares full of text documents, through the anarchistic wiki system, all the way to Enterprise Content Management (ECM) systems with integrated document scanners, archivers, ILM-components and what have you not * an appreciation for the specific skills that are needed in the so-called "technical writers" * an embedded process for documentation in the business processes; if not in projects, then most surely in day-to-day system administration. What we'll attempt to do here is to systematically address all issues surrounding ICT documentation, and develop the lacking taxonomies, methodologies etcetera. 3f946ace47400bc00b71f15e47a39e931cd388ff 1945 1944 2008-10-27T21:02:19Z 82.161.20.132 0 wikitext text/x-wiki == The Documentation Project== spamerdespam [[www.linuz.nl]] Documentation in ICT projects is a tough cookie (maybe outside of ICT as well, but that's no concern of ours at this moment). What the ICT profession seems to lack is * a thorough understanding of the fundamental problems that surround ICT documentation * taxonomies of the different documentation purposes, target audiences (with their experience levels), and document types * a methodology to create, review and maintain ICT documentation of sufficient quality, against reasonable cost * templates, guidelines and best practices to assist such a methodology * some sort of overview of the different documentation management solutions that exist, ranging from the venerable binders with photocopies and printouts, through fileshares full of text documents, through the anarchistic wiki system, all the way to Enterprise Content Management (ECM) systems with integrated document scanners, archivers, ILM-components and what have you not * an appreciation for the specific skills that are needed in the so-called "technical writers" * an embedded process for documentation in the business processes; if not in projects, then most surely in day-to-day system administration. What we'll attempt to do here is to systematically address all issues surrounding ICT documentation, and develop the lacking taxonomies, methodologies etcetera. ecd9938c3a6ecf33166c161575730f884f708fed 1946 1945 2008-10-27T21:04:21Z 82.161.20.132 0 wikitext text/x-wiki == The Documentation Project== spamerdespam [http://www.linuz.nl] Documentation in ICT projects is a tough cookie (maybe outside of ICT as well, but that's no concern of ours at this moment). What the ICT profession seems to lack is * a thorough understanding of the fundamental problems that surround ICT documentation * taxonomies of the different documentation purposes, target audiences (with their experience levels), and document types * a methodology to create, review and maintain ICT documentation of sufficient quality, against reasonable cost * templates, guidelines and best practices to assist such a methodology * some sort of overview of the different documentation management solutions that exist, ranging from the venerable binders with photocopies and printouts, through fileshares full of text documents, through the anarchistic wiki system, all the way to Enterprise Content Management (ECM) systems with integrated document scanners, archivers, ILM-components and what have you not * an appreciation for the specific skills that are needed in the so-called "technical writers" * an embedded process for documentation in the business processes; if not in projects, then most surely in day-to-day system administration. What we'll attempt to do here is to systematically address all issues surrounding ICT documentation, and develop the lacking taxonomies, methodologies etcetera. 29ede6a26e461241b6138c715af81797699b673e 1947 1946 2008-10-27T21:06:31Z 82.161.20.132 0 Undo revision 1946 by [[Special:Contributions/82.161.20.132|82.161.20.132]] ([[User talk:82.161.20.132|Talk]]) wikitext text/x-wiki == The Documentation Project== spamerdespam [[www.linuz.nl]] Documentation in ICT projects is a tough cookie (maybe outside of ICT as well, but that's no concern of ours at this moment). What the ICT profession seems to lack is * a thorough understanding of the fundamental problems that surround ICT documentation * taxonomies of the different documentation purposes, target audiences (with their experience levels), and document types * a methodology to create, review and maintain ICT documentation of sufficient quality, against reasonable cost * templates, guidelines and best practices to assist such a methodology * some sort of overview of the different documentation management solutions that exist, ranging from the venerable binders with photocopies and printouts, through fileshares full of text documents, through the anarchistic wiki system, all the way to Enterprise Content Management (ECM) systems with integrated document scanners, archivers, ILM-components and what have you not * an appreciation for the specific skills that are needed in the so-called "technical writers" * an embedded process for documentation in the business processes; if not in projects, then most surely in day-to-day system administration. What we'll attempt to do here is to systematically address all issues surrounding ICT documentation, and develop the lacking taxonomies, methodologies etcetera. ecd9938c3a6ecf33166c161575730f884f708fed 1948 1947 2008-10-27T21:08:58Z Saruman! 2 Reverted edits by [[Special:Contributions/82.161.20.132|82.161.20.132]] ([[User talk:82.161.20.132|Talk]]); changed back to last version by [[User:Saruman!|Saruman!]] wikitext text/x-wiki == The Documentation Project== Documentation in ICT projects is a tough cookie (maybe outside of ICT as well, but that's no concern of ours at this moment). What the ICT profession seems to lack is * a thorough understanding of the fundamental problems that surround ICT documentation * taxonomies of the different documentation purposes, target audiences (with their experience levels), and document types * a methodology to create, review and maintain ICT documentation of sufficient quality, against reasonable cost * templates, guidelines and best practices to assist such a methodology * some sort of overview of the different documentation management solutions that exist, ranging from the venerable binders with photocopies and printouts, through fileshares full of text documents, through the anarchistic wiki system, all the way to Enterprise Content Management (ECM) systems with integrated document scanners, archivers, ILM-components and what have you not * an appreciation for the specific skills that are needed in the so-called "technical writers" * an embedded process for documentation in the business processes; if not in projects, then most surely in day-to-day system administration. What we'll attempt to do here is to systematically address all issues surrounding ICT documentation, and develop the lacking taxonomies, methodologies etcetera. bedc8612a25f6d367876f014072ce9ecb178ab5c 0 1488 1949 2008-10-27T23:20:21Z Saruman! 2 Page started wikitext text/x-wiki ==Preparing for certificate creation== When we're going to create certificates, we're going to use the ''openssl'' command twice: * once to create a "certificate signing request", in which we define all information to be included in the certificate, and actually generate the public and private key parts of the key pair, and * once to instruct the OpenSSL package to sign the certificate with our CA root certificate. The first step thus '''creates''' the actual keypair, and the second step '''signs''' the public key. However, we're going to need to input a lot of parameters on the ''openssl'' command line. We can make things a bit easier for us by specifying these in the ''openssl.cnf'' file, just as we have added some values when creating the CA itself. To be precise, we're going to add '''X.509 V3 extensions''' By default OpenSSL generates V1 certificates, but if we're not extremely worried about offending certain ancient web browsers, we can add V3 extensions, and even make ''openssl'' do that by default. To do this, we find in ''openssl.cnf'' the following line in the section ''[ req ]'', which is likely present but commented out: req_extensions = v3_req # The extensions to add to a certificate request Simply remove the # sign in front of it, so that it appears as given above. This by default enables V3 extensions. Furthermore, check the section ''[ v3_req ]''. It should look like this: [ v3_req ] # Extensions to add to a certificate request basicConstraints = CA:FALSE keyUsage = nonRepudiation, digitalSignature, keyEncipherment subjectKeyIdentifier = hash What is added is the last line, with ''subjectKeyIdentifier''; this line specifies how to identify the public key being certified, so that distinct keys used by the same subject can be differentiated (e.g. as key updating occurs, for example). Four values are possible, but the IETF Public Key Infrastructure (PKIX) working group recommends the setting ''subjectKeyIdentifier=hash'' ==Creating an SSL certificate== Now we can create an SSL certificate for a web server. For the Common Name of the certificate, we need the '''exact''' name of the web server that'll offer the SSL connections. However, some servers run different websites as Virtual Hosts, so they could be running, for example, www.saruman.biz, as well as shop.saruman.biz. That might present a problem, because if the certificate is issued for www.saruman.biz, then each visitor of shop.saruman.biz will get a warning along the lines of "Warning: The website you're trying to visit is shop.saruman.biz, but the certificate offered is for www.saruman.biz". To prevent that, we could use the wildcard character in the name of the certificate, so as to generate a certificate for *.saruman.biz. So with that out of the way, we now perform the first step in our certificate generation: we create a signing request with all the information that we want in our SSL certificate. We run the magic incantation openssl req -new -nodes -keyout saruman.biz.mykey.pem -out saruman.biz.req.pem This generates a new private key (named ''saruman.biz.mykey.pem''), and a new, non-encrypted (because of ''-nodes''), key signing request named ''saruman.biz.req.pem''. We can leave out terms like ''-newkey rsa:2048'' and ''-days 370'' since we've put that in the configuration file. And naturally you're free to choose your own names for the keys. a8093ec262f4ef9f9086c49375e6336064410772 1952 1949 2008-10-28T08:09:57Z Saruman! 2 Finished CA cert creation part wikitext text/x-wiki ==Preparing for certificate creation== When we're going to create certificates, we're going to use the ''openssl'' command twice: * once to create a "certificate signing request", in which we define all information to be included in the certificate, and actually generate the public and private key parts of the key pair, and * once to instruct the OpenSSL package to sign the certificate with our CA root certificate. The first step thus '''creates''' the actual keypair, and the second step '''signs''' the public key. However, we're going to need to input a lot of parameters on the ''openssl'' command line. We can make things a bit easier for us by specifying these in the ''openssl.cnf'' file, just as we have added some values when creating the CA itself. To be precise, we're going to add '''X.509 V3 extensions''' By default OpenSSL generates V1 certificates, but if we're not extremely worried about offending certain ancient web browsers, we can add V3 extensions, and even make ''openssl'' do that by default. To do this, we find in ''openssl.cnf'' the following line in the section ''[ req ]'', which is likely present but commented out: req_extensions = v3_req # The extensions to add to a certificate request Simply remove the # sign in front of it, so that it appears as given above. This by default enables V3 extensions. Furthermore, check the section ''[ v3_req ]''. It should look like this: [ v3_req ] # Extensions to add to a certificate request basicConstraints = CA:FALSE keyUsage = nonRepudiation, digitalSignature, keyEncipherment subjectKeyIdentifier = hash What is added is the last line, with ''subjectKeyIdentifier''; this line specifies how to identify the public key being certified, so that distinct keys used by the same subject can be differentiated (e.g. as key updating occurs, for example). Four values are possible, but the IETF Public Key Infrastructure (PKIX) working group recommends the setting ''subjectKeyIdentifier=hash'' ==Creating an SSL certificate== Now we can create an SSL certificate for a web server. For the Common Name of the certificate, we need the '''exact''' name of the web server that'll offer the SSL connections. However, some servers run different websites as Virtual Hosts, so they could be running, for example, www.saruman.biz, as well as shop.saruman.biz. That might present a problem, because if the certificate is issued for www.saruman.biz, then each visitor of shop.saruman.biz will get a warning along the lines of "Warning: The website you're trying to visit is shop.saruman.biz, but the certificate offered is for www.saruman.biz". To prevent that, we could use the wildcard character in the name of the certificate, so as to generate a certificate for *.saruman.biz. === CA.sh - certificate creation made easy=== Since we have the ''openssl.cnf'' set up just right, and the ''CA.sh'' script primed, generating an SSL certificate is not very hard. From any old directory, run as root /usr/lib/ssl/misc/CA.sh -newreq This will create the signing request. The questions it'll ask, are * a PEM passphrase, with which to protect the private key of the key pair * Country/State/Locality/Organization/Organizational Unit; just as with the CA root certificate creation, these have your preprogrammed defaults that you may or may not change. * Common Name; here we MUST give the DNS name of the host that is going to use the certificate, e.g. ''shop.saruman.biz'', or ''*.saruman.biz''. * Challenge password; leave it blank, it's just to protect your signing request while en-route to the CA - but that's you anyway :-) * Optional company name; leave that blank too, it's also extra information for the CA. Now your private key and your certificate signing request (CSR) are ready; they're called ''newkey.pem'' and ''newreq.pem'' by default, and are located in your working directory. Time to do some signing! From that same working directory, run /usr/lib/ssl/misc/CA.sh -sign The script will show that it's using the config file ''/usr/lib/ssl/openssl.cnf'' (as we indeed wish), and then ask for the super-duper-secret passphrase to the CA private key (provided you've left that in directory ''/etc/ssl/ca/private''). Feed the script the passphrase, and it'll get to work. It'll check the request, then show you the details of the certificate you're about to sign. An example would be Certificate Details: Serial Number: 1 (0x1) Validity Not Before: Oct 27 09:34:00 2008 GMT Not After : Nov 1 09:34:00 2009 GMT Subject: countryName = NL stateOrProvinceName = Utrecht organizationName = Saruman.biz organizationalUnitName = Internet Dept. commonName = shop.saruman.biz emailAddress = webmaster@saruman.biz X509v3 extensions: X509v3 Basic Constraints: CA:FALSE Netscape Comment: OpenSSL Generated Certificate X509v3 Subject Key Identifier: 30:F2:61:80:AA:CF:1B:F0:3E:44:41:D6:38:CC:31:F0:94:28:BD:2B X509v3 Authority Key Identifier: keyid:80:41:F8:A5:1F:C2:27:6E:CF:A9:28:8E:8A:EF:83:E7:FD:8A:D5:26 Certificate is to be certified until Nov 1 09:34:00 2009 GMT (370 days) Sign the certificate? [y/n]: After doing your CA duty and diligently checking all the data, just press ''y''. The script certifies the request, and asks if it is to commit the request. This means it'll update it's own database, by saving a copy of the signed certificate in ''/etc/ssl/ca/newcerts'' named after its serial number (''01.pem'' for this example). Furthermore the script will record the serial and ID's of the generated certificate so that the next certificate will have a new serial number. And now: hey presto! We have a ''newcert.pem'' in our working directory! For good measure: delete ''newreq.pem'', rename ''newkey.pem'' to ''shop.saruman.biz.key.pem'', and rename ''newcert.pem'' to ''shop.saruman.biz.pem''. Save the private key and its PEM passphrase in a safe place (e.g. Keepass database), and deploy your certificate! (more on that in another section). === openssl - the hard way to certificate creation=== We don't actually need to use the ''CA.sh'' script, because we can do manually what the ''CA.sh'' script does. That gives us more control, but also more work. Let's see what we've got to do. We will now perform the first step in our "manual" certificate generation: we create a signing request with all the information that we want in our SSL certificate. We run the magic incantation - note how we already openssl req -new -nodes -keyout webmail.saruman.biz.key.pem -out webmail.saruman.biz.req.pem This generates a new private key (named ''webmail.saruman.biz.key.pem''), and a new, non-encrypted (because of ''-nodes''), key signing request named ''webmail.saruman.biz.req.pem''. We can leave out terms like ''-newkey rsa:2048'' and ''-days 370'' since we've put that in the configuration file. And naturally you're free to choose your own names for the keys. FIXME - need the full process here === Validating the generated certificates=== Again, we can use the ''openssl'' command to validate the keys we've generated. For instance, the ''CA.sh'' generated certificate, after renaming, is verified with openssl x509 -in shop.saruman.biz.pem -noout -purpose Certificate purposes: SSL client : Yes SSL client CA : No SSL server : Yes SSL server CA : No Netscape SSL server : Yes Netscape SSL server CA : No S/MIME signing : Yes S/MIME signing CA : No S/MIME encryption : Yes S/MIME encryption CA : No CRL signing : Yes CRL signing CA : No Any Purpose : Yes Any Purpose CA : Yes OCSP helper : Yes OCSP helper CA : No Notice that the certificate is valid for everything except CA tasks. Likewise, using ''-dates'' instead of ''-purpose'' lets you see the validity time period, and ''-text'' gives the whole text of the certificate. Note the line marked "issuer", and see how your own CA is referenced there. f667562fea9e8b59419c6976c7f46d329e872c5a 0 1441 1950 1881 2008-10-28T06:43:18Z 94.102.49.87 0 /* Routes under Debian */ wikitext text/x-wiki Hello ==DNS resolution under Debian== One headache you might encounter when configuring a Debian server is how to let every program know how to resolve DNS names. Before a program can connect to an external network resource (say, for example, a web server), it must have a means of converting DNS names (e.g. www.saruman.biz) into the corresponding IP addresses (e.g. 192.168.67.10). This process is called "name resolution". The need for name resolution means that every program needs to know about the available means by which to do this name resolution. From the good old days comes the configuration file ''resolv.conf'', normally found in ''/etc''. It contains information about the nameservers to be used by the system, be they actual servers or lookup files. However, more and more programs have the need to dynamically modify the ''resolv.conf'' configuration file. This means that frequently they step on each other, and the ''resolv.conf'' file can become out-of-sync. The ''resolvconf'' program addresses this problem. It acts as an intermediary between programs that supply nameserver information (e.g. DHCP clients) and programs that use nameserver information (e.g. resolver). When ''resolvconf'' is properly installed, the file ''/etc/resolv.conf'' is replaced by a symbolic link to ''/etc/resolvconf/run/resolv.conf'', and any resolver thus uses the dynamically generated resolver configuration file at ''/etc/resolvconf/run/resolv.conf''. The ''resolvconf'' program is only necessary when a system has multiple programs that need to dynamically modify the nameserver information. In a simple system where the nameservers do not change often or are only changed by one program, the standard ''/etc/resolv.conf'' configuration file is adequate. == VLANs under Debian == Debian can support network traffic over VLANs (ethernet 802.1q) - and we don't mean the normal "untagged" network ports (hey, VLANs are transparent that way, anybody and anything can use untagged network ports). No, we mean that Debian can accept network traffic in from, and send traffic out to, a VLAN tagged switchport. Suppose you have a layer 2 switch with support for 802.1q VLANs, and want to route traffic from one VLAN to another. For this you can use a Debian router with a single network interface, using VLAN support (this is called "router on a stick" because the routing takes place over only one cable). First, as root, run apt-get install vlan modprobe 8021q The first line is to install the vlan package, which contains all necessary tools to create and manipulate VLAN-enabled network ports. The second line loads the module that enables VLAN tagging for your ethernet network cards. Note: if you don't have the stock Debian kernel, but compiled your own, then you might have chosen not to compile the 8021q module. In that case, compile the module. Also note, that if you've compiled the 8021q code into the kernel itself, then you don't need to load the module and that second line is unnecessary for you. You'll find this kernel compile option (depending on your kernel version) under Networking -> Networking Options -> "802.1Q VLAN Support". This option has been in the Linux kernel since version 2.4.14. ifconfig eth0 down vconfig add eth0 2 vconfig add eth0 3 The first command brings down your network on eth0 (not the thing to do if you're working remote, then :-). The next two commands create two virtual interfaces ''eth0.2'' and ''eth0.3'', which have VLAN tags 2 and 3 (don't use VLAN tag 1 if you can help it; on many devices VLAN1 is a special hardware management VLAN). The virtual interfaces run on top of your ''eth0'' interface.<br> Now because your VLAN interfaces run on top of ''eth0'', you've got to bring ''eth0'' itself up, even if you don't want to run network traffic over it. Furthermore, you've got to configure the two virtual interfaces you've created. Let's suppose you want to run IP subnet 192.168.1.0/24 on VLAN2, and 192.168.2.0/24 on VLAN3. You can do so with ifconfig eth0 0.0.0.0 up ifconfig eth0.2 192.168.1.1 broadcast 192.168.1.255 netmask 255.255.255.0 up ifconfig eth0.3 192.168.2.1 broadcast 192.168.2.255 netmask 255.255.255.0 up Now that you've this done, you must still configure one of your switch ports to belong to VLAN 2 and 3 at the same time (tagged port), and connect ''eth0'' from your linux box to that port. This enables your box to run network traffic on both VLANs. To round things up: if you haven't yet enabled forwarding, you can do so now. Furthermore, you might wish to augment your route table so that the routing engine in your server knows how to handle packets that it needs to forward from one VLAN to the other: echo 1 > /proc/sys/net/ipv4/ip_forward route add -net 10.1.1.0 netmask 255.255.255.0 gw eth0.2 route add -net 10.1.2.0 netmask 255.255.255.0 gw eth0.3 This is it; nothing to it, right? 593fbe16e9f68578136866b7cad0221be7c18a03 1951 1950 2008-10-28T07:10:43Z Saruman! 2 Reverted edits by [[Special:Contributions/94.102.49.87|94.102.49.87]] ([[User talk:94.102.49.87|Talk]]); changed back to last version by [[User:Saruman!|Saruman!]] wikitext text/x-wiki ==Routes under Debian== When you need to add a networking route, there generally are two ways to do it: # manually adding a route at the command prompt: this means that the machine will "understand" the route for as long as it is running. However, when you reboot the machine, it will have "forgotten" the route. This is called a non-persistent route. # adding a route to the networking configuration files, so that it will be in place regardless of reboots or network restarts. This is called a persistent route. ===Manipulating non-persistent routes=== From the days of yore, the venerable ''route'' command enables us to view, add, change and delete routes. Its most known use is for printing the current routing table: #route -n Kernel IP routing table Destination Gateway Genmask Flags Metric Ref Use Iface 192.168.70.0 212.214.172.50 255.255.255.0 UG 0 0 0 eth1 192.168.67.0 * 255.255.255.0 U 0 0 0 eth0 212.214.172.0 * 255.255.255.0 U 0 0 0 eth1 default 212.214.172.1 0.0.0.0 UG 0 0 0 eth1 The addition of -n makes sure the ''route'' command does not try to substitute DNS names for IP addresses it knows. The second most used incarnation of ''route'' lies in the addition of a route, as has happened in the previous example. The route was added to the routing table using something like this: #route add -net 192.168.70.0 netmask 255.255.255.0 gw 212.214.172.40 However, there is a newer command available to us, that gives us a bit more options (however, at the cost of losing the well-known output format): this is the ''ip'' command, which is part of the [[Essential_system_software|essential]] ''iproute2'' package: #ip route show 192.168.70.0/24 via 212.214.172.50 dev eth1 src 192.168.67.10 192.168.67.0/24 dev eth0 proto kernel scope link src 192.168.67.10 212.214.172.0/24 dev eth1 proto kernel scope link src 212.214.172.50 default via 212.214.172.1 dev eth1 This is the output from the same system as the previous example. However, we see something interesting here: "ip" is capable of adding extra information to the route, like the first line shows (it's using "via"). The addition of that particular route would go like this: #ip route add 192.168.70.0/24 via 212.214.172.50 src 192.168.67.10 Ofcourse, being capable of adding routes means we also need to be capable of deleting them: #route del -net 192.168.70.0 netmask 255.255.255.0 #ip route del 192.168.70.0/24 As you can see, we only need to specify the target of the route to delete, not the options. ===Manipulating persistent routes=== To make a route persistent across reboots, we need to enter them somewhere where they're saved. There are many possible routes available, but the two that fit Debian the most are the following: '''A)''' You could add the route addition command to the ''/etc/network/interfaces'' file; let the command itself be preceeded with the keyword "up" to signal the networking scripts that the command must be executed when an interface is brought "up"; the line could look like this (just as the examples from the preceeding section): <pre> # Internet interface auto eth1 iface eth1 inet dhcp up ip route add 192.168.70.0/24 via 212.214.172.50 src 192.168.67.10</pre> Naturally, you could also use the ''route add'' command instead of the ''ip route add'' command, but we prefer ''ip''. Note: it matters --where-- in the ''interfaces'' file you put this line: it should be put in the same stanza as the interface it operates on. In this example, the external interface of the server is 212.214.172.50, which belongs with interface ''eth1''. Therefore, the "up" line appears in the stanza for ''eth1''. '''B)''' You could create a script that sets the route(s), and put it in the directory ''/etc/network/if-up.d''. Since all scripts that reside there get called when any interface goes "up", your route setting script would be called when ''any'' interface comes up, including ''lo''. This in turn means that a script for setting a route that belongs with a particular interface, should check on invocation which is the interface that goes up. At this moment in time, we don't employ any such script, so no example here, but if you look at the existing scripts in ''/etc/network/if-up.d'' you'll see how other programmers have done this. ==DNS resolution under Debian== One headache you might encounter when configuring a Debian server is how to let every program know how to resolve DNS names. Before a program can connect to an external network resource (say, for example, a web server), it must have a means of converting DNS names (e.g. www.saruman.biz) into the corresponding IP addresses (e.g. 192.168.67.10). This process is called "name resolution". The need for name resolution means that every program needs to know about the available means by which to do this name resolution. From the good old days comes the configuration file ''resolv.conf'', normally found in ''/etc''. It contains information about the nameservers to be used by the system, be they actual servers or lookup files. However, more and more programs have the need to dynamically modify the ''resolv.conf'' configuration file. This means that frequently they step on each other, and the ''resolv.conf'' file can become out-of-sync. The ''resolvconf'' program addresses this problem. It acts as an intermediary between programs that supply nameserver information (e.g. DHCP clients) and programs that use nameserver information (e.g. resolver). When ''resolvconf'' is properly installed, the file ''/etc/resolv.conf'' is replaced by a symbolic link to ''/etc/resolvconf/run/resolv.conf'', and any resolver thus uses the dynamically generated resolver configuration file at ''/etc/resolvconf/run/resolv.conf''. The ''resolvconf'' program is only necessary when a system has multiple programs that need to dynamically modify the nameserver information. In a simple system where the nameservers do not change often or are only changed by one program, the standard ''/etc/resolv.conf'' configuration file is adequate. == VLANs under Debian == Debian can support network traffic over VLANs (ethernet 802.1q) - and we don't mean the normal "untagged" network ports (hey, VLANs are transparent that way, anybody and anything can use untagged network ports). No, we mean that Debian can accept network traffic in from, and send traffic out to, a VLAN tagged switchport. Suppose you have a layer 2 switch with support for 802.1q VLANs, and want to route traffic from one VLAN to another. For this you can use a Debian router with a single network interface, using VLAN support (this is called "router on a stick" because the routing takes place over only one cable). First, as root, run apt-get install vlan modprobe 8021q The first line is to install the vlan package, which contains all necessary tools to create and manipulate VLAN-enabled network ports. The second line loads the module that enables VLAN tagging for your ethernet network cards. Note: if you don't have the stock Debian kernel, but compiled your own, then you might have chosen not to compile the 8021q module. In that case, compile the module. Also note, that if you've compiled the 8021q code into the kernel itself, then you don't need to load the module and that second line is unnecessary for you. You'll find this kernel compile option (depending on your kernel version) under Networking -> Networking Options -> "802.1Q VLAN Support". This option has been in the Linux kernel since version 2.4.14. ifconfig eth0 down vconfig add eth0 2 vconfig add eth0 3 The first command brings down your network on eth0 (not the thing to do if you're working remote, then :-). The next two commands create two virtual interfaces ''eth0.2'' and ''eth0.3'', which have VLAN tags 2 and 3 (don't use VLAN tag 1 if you can help it; on many devices VLAN1 is a special hardware management VLAN). The virtual interfaces run on top of your ''eth0'' interface.<br> Now because your VLAN interfaces run on top of ''eth0'', you've got to bring ''eth0'' itself up, even if you don't want to run network traffic over it. Furthermore, you've got to configure the two virtual interfaces you've created. Let's suppose you want to run IP subnet 192.168.1.0/24 on VLAN2, and 192.168.2.0/24 on VLAN3. You can do so with ifconfig eth0 0.0.0.0 up ifconfig eth0.2 192.168.1.1 broadcast 192.168.1.255 netmask 255.255.255.0 up ifconfig eth0.3 192.168.2.1 broadcast 192.168.2.255 netmask 255.255.255.0 up Now that you've this done, you must still configure one of your switch ports to belong to VLAN 2 and 3 at the same time (tagged port), and connect ''eth0'' from your linux box to that port. This enables your box to run network traffic on both VLANs. To round things up: if you haven't yet enabled forwarding, you can do so now. Furthermore, you might wish to augment your route table so that the routing engine in your server knows how to handle packets that it needs to forward from one VLAN to the other: echo 1 > /proc/sys/net/ipv4/ip_forward route add -net 10.1.1.0 netmask 255.255.255.0 gw eth0.2 route add -net 10.1.2.0 netmask 255.255.255.0 gw eth0.3 This is it; nothing to it, right? 0eee61c8c8d0a43496c965f729db633ca12252dd 1962 1951 2008-10-31T04:23:37Z 94.102.49.88 0 /* Routes under Debian */ wikitext text/x-wiki ==DNS resolution under Debian== One headache you might encounter when configuring a Debian server is how to let every program know how to resolve DNS names. Before a program can connect to an external network resource (say, for example, a web server), it must have a means of converting DNS names (e.g. www.saruman.biz) into the corresponding IP addresses (e.g. 192.168.67.10). This process is called "name resolution". The need for name resolution means that every program needs to know about the available means by which to do this name resolution. From the good old days comes the configuration file ''resolv.conf'', normally found in ''/etc''. It contains information about the nameservers to be used by the system, be they actual servers or lookup files. However, more and more programs have the need to dynamically modify the ''resolv.conf'' configuration file. This means that frequently they step on each other, and the ''resolv.conf'' file can become out-of-sync. The ''resolvconf'' program addresses this problem. It acts as an intermediary between programs that supply nameserver information (e.g. DHCP clients) and programs that use nameserver information (e.g. resolver). When ''resolvconf'' is properly installed, the file ''/etc/resolv.conf'' is replaced by a symbolic link to ''/etc/resolvconf/run/resolv.conf'', and any resolver thus uses the dynamically generated resolver configuration file at ''/etc/resolvconf/run/resolv.conf''. The ''resolvconf'' program is only necessary when a system has multiple programs that need to dynamically modify the nameserver information. In a simple system where the nameservers do not change often or are only changed by one program, the standard ''/etc/resolv.conf'' configuration file is adequate. == VLANs under Debian == Debian can support network traffic over VLANs (ethernet 802.1q) - and we don't mean the normal "untagged" network ports (hey, VLANs are transparent that way, anybody and anything can use untagged network ports). No, we mean that Debian can accept network traffic in from, and send traffic out to, a VLAN tagged switchport. Suppose you have a layer 2 switch with support for 802.1q VLANs, and want to route traffic from one VLAN to another. For this you can use a Debian router with a single network interface, using VLAN support (this is called "router on a stick" because the routing takes place over only one cable). First, as root, run apt-get install vlan modprobe 8021q The first line is to install the vlan package, which contains all necessary tools to create and manipulate VLAN-enabled network ports. The second line loads the module that enables VLAN tagging for your ethernet network cards. Note: if you don't have the stock Debian kernel, but compiled your own, then you might have chosen not to compile the 8021q module. In that case, compile the module. Also note, that if you've compiled the 8021q code into the kernel itself, then you don't need to load the module and that second line is unnecessary for you. You'll find this kernel compile option (depending on your kernel version) under Networking -> Networking Options -> "802.1Q VLAN Support". This option has been in the Linux kernel since version 2.4.14. ifconfig eth0 down vconfig add eth0 2 vconfig add eth0 3 The first command brings down your network on eth0 (not the thing to do if you're working remote, then :-). The next two commands create two virtual interfaces ''eth0.2'' and ''eth0.3'', which have VLAN tags 2 and 3 (don't use VLAN tag 1 if you can help it; on many devices VLAN1 is a special hardware management VLAN). The virtual interfaces run on top of your ''eth0'' interface.<br> Now because your VLAN interfaces run on top of ''eth0'', you've got to bring ''eth0'' itself up, even if you don't want to run network traffic over it. Furthermore, you've got to configure the two virtual interfaces you've created. Let's suppose you want to run IP subnet 192.168.1.0/24 on VLAN2, and 192.168.2.0/24 on VLAN3. You can do so with ifconfig eth0 0.0.0.0 up ifconfig eth0.2 192.168.1.1 broadcast 192.168.1.255 netmask 255.255.255.0 up ifconfig eth0.3 192.168.2.1 broadcast 192.168.2.255 netmask 255.255.255.0 up Now that you've this done, you must still configure one of your switch ports to belong to VLAN 2 and 3 at the same time (tagged port), and connect ''eth0'' from your linux box to that port. This enables your box to run network traffic on both VLANs. To round things up: if you haven't yet enabled forwarding, you can do so now. Furthermore, you might wish to augment your route table so that the routing engine in your server knows how to handle packets that it needs to forward from one VLAN to the other: echo 1 > /proc/sys/net/ipv4/ip_forward route add -net 10.1.1.0 netmask 255.255.255.0 gw eth0.2 route add -net 10.1.2.0 netmask 255.255.255.0 gw eth0.3 This is it; nothing to it, right? a79fd213b1321d7985c12d73bb99379428d5ee3a 1963 1962 2008-10-31T07:34:44Z Saruman! 2 Reverted edits by [[Special:Contributions/94.102.49.88|94.102.49.88]] ([[User talk:94.102.49.88|Talk]]); changed back to last version by [[User:Saruman!|Saruman!]] wikitext text/x-wiki ==Routes under Debian== When you need to add a networking route, there generally are two ways to do it: # manually adding a route at the command prompt: this means that the machine will "understand" the route for as long as it is running. However, when you reboot the machine, it will have "forgotten" the route. This is called a non-persistent route. # adding a route to the networking configuration files, so that it will be in place regardless of reboots or network restarts. This is called a persistent route. ===Manipulating non-persistent routes=== From the days of yore, the venerable ''route'' command enables us to view, add, change and delete routes. Its most known use is for printing the current routing table: #route -n Kernel IP routing table Destination Gateway Genmask Flags Metric Ref Use Iface 192.168.70.0 212.214.172.50 255.255.255.0 UG 0 0 0 eth1 192.168.67.0 * 255.255.255.0 U 0 0 0 eth0 212.214.172.0 * 255.255.255.0 U 0 0 0 eth1 default 212.214.172.1 0.0.0.0 UG 0 0 0 eth1 The addition of -n makes sure the ''route'' command does not try to substitute DNS names for IP addresses it knows. The second most used incarnation of ''route'' lies in the addition of a route, as has happened in the previous example. The route was added to the routing table using something like this: #route add -net 192.168.70.0 netmask 255.255.255.0 gw 212.214.172.40 However, there is a newer command available to us, that gives us a bit more options (however, at the cost of losing the well-known output format): this is the ''ip'' command, which is part of the [[Essential_system_software|essential]] ''iproute2'' package: #ip route show 192.168.70.0/24 via 212.214.172.50 dev eth1 src 192.168.67.10 192.168.67.0/24 dev eth0 proto kernel scope link src 192.168.67.10 212.214.172.0/24 dev eth1 proto kernel scope link src 212.214.172.50 default via 212.214.172.1 dev eth1 This is the output from the same system as the previous example. However, we see something interesting here: "ip" is capable of adding extra information to the route, like the first line shows (it's using "via"). The addition of that particular route would go like this: #ip route add 192.168.70.0/24 via 212.214.172.50 src 192.168.67.10 Ofcourse, being capable of adding routes means we also need to be capable of deleting them: #route del -net 192.168.70.0 netmask 255.255.255.0 #ip route del 192.168.70.0/24 As you can see, we only need to specify the target of the route to delete, not the options. ===Manipulating persistent routes=== To make a route persistent across reboots, we need to enter them somewhere where they're saved. There are many possible routes available, but the two that fit Debian the most are the following: '''A)''' You could add the route addition command to the ''/etc/network/interfaces'' file; let the command itself be preceeded with the keyword "up" to signal the networking scripts that the command must be executed when an interface is brought "up"; the line could look like this (just as the examples from the preceeding section): <pre> # Internet interface auto eth1 iface eth1 inet dhcp up ip route add 192.168.70.0/24 via 212.214.172.50 src 192.168.67.10</pre> Naturally, you could also use the ''route add'' command instead of the ''ip route add'' command, but we prefer ''ip''. Note: it matters --where-- in the ''interfaces'' file you put this line: it should be put in the same stanza as the interface it operates on. In this example, the external interface of the server is 212.214.172.50, which belongs with interface ''eth1''. Therefore, the "up" line appears in the stanza for ''eth1''. '''B)''' You could create a script that sets the route(s), and put it in the directory ''/etc/network/if-up.d''. Since all scripts that reside there get called when any interface goes "up", your route setting script would be called when ''any'' interface comes up, including ''lo''. This in turn means that a script for setting a route that belongs with a particular interface, should check on invocation which is the interface that goes up. At this moment in time, we don't employ any such script, so no example here, but if you look at the existing scripts in ''/etc/network/if-up.d'' you'll see how other programmers have done this. ==DNS resolution under Debian== One headache you might encounter when configuring a Debian server is how to let every program know how to resolve DNS names. Before a program can connect to an external network resource (say, for example, a web server), it must have a means of converting DNS names (e.g. www.saruman.biz) into the corresponding IP addresses (e.g. 192.168.67.10). This process is called "name resolution". The need for name resolution means that every program needs to know about the available means by which to do this name resolution. From the good old days comes the configuration file ''resolv.conf'', normally found in ''/etc''. It contains information about the nameservers to be used by the system, be they actual servers or lookup files. However, more and more programs have the need to dynamically modify the ''resolv.conf'' configuration file. This means that frequently they step on each other, and the ''resolv.conf'' file can become out-of-sync. The ''resolvconf'' program addresses this problem. It acts as an intermediary between programs that supply nameserver information (e.g. DHCP clients) and programs that use nameserver information (e.g. resolver). When ''resolvconf'' is properly installed, the file ''/etc/resolv.conf'' is replaced by a symbolic link to ''/etc/resolvconf/run/resolv.conf'', and any resolver thus uses the dynamically generated resolver configuration file at ''/etc/resolvconf/run/resolv.conf''. The ''resolvconf'' program is only necessary when a system has multiple programs that need to dynamically modify the nameserver information. In a simple system where the nameservers do not change often or are only changed by one program, the standard ''/etc/resolv.conf'' configuration file is adequate. == VLANs under Debian == Debian can support network traffic over VLANs (ethernet 802.1q) - and we don't mean the normal "untagged" network ports (hey, VLANs are transparent that way, anybody and anything can use untagged network ports). No, we mean that Debian can accept network traffic in from, and send traffic out to, a VLAN tagged switchport. Suppose you have a layer 2 switch with support for 802.1q VLANs, and want to route traffic from one VLAN to another. For this you can use a Debian router with a single network interface, using VLAN support (this is called "router on a stick" because the routing takes place over only one cable). First, as root, run apt-get install vlan modprobe 8021q The first line is to install the vlan package, which contains all necessary tools to create and manipulate VLAN-enabled network ports. The second line loads the module that enables VLAN tagging for your ethernet network cards. Note: if you don't have the stock Debian kernel, but compiled your own, then you might have chosen not to compile the 8021q module. In that case, compile the module. Also note, that if you've compiled the 8021q code into the kernel itself, then you don't need to load the module and that second line is unnecessary for you. You'll find this kernel compile option (depending on your kernel version) under Networking -> Networking Options -> "802.1Q VLAN Support". This option has been in the Linux kernel since version 2.4.14. ifconfig eth0 down vconfig add eth0 2 vconfig add eth0 3 The first command brings down your network on eth0 (not the thing to do if you're working remote, then :-). The next two commands create two virtual interfaces ''eth0.2'' and ''eth0.3'', which have VLAN tags 2 and 3 (don't use VLAN tag 1 if you can help it; on many devices VLAN1 is a special hardware management VLAN). The virtual interfaces run on top of your ''eth0'' interface.<br> Now because your VLAN interfaces run on top of ''eth0'', you've got to bring ''eth0'' itself up, even if you don't want to run network traffic over it. Furthermore, you've got to configure the two virtual interfaces you've created. Let's suppose you want to run IP subnet 192.168.1.0/24 on VLAN2, and 192.168.2.0/24 on VLAN3. You can do so with ifconfig eth0 0.0.0.0 up ifconfig eth0.2 192.168.1.1 broadcast 192.168.1.255 netmask 255.255.255.0 up ifconfig eth0.3 192.168.2.1 broadcast 192.168.2.255 netmask 255.255.255.0 up Now that you've this done, you must still configure one of your switch ports to belong to VLAN 2 and 3 at the same time (tagged port), and connect ''eth0'' from your linux box to that port. This enables your box to run network traffic on both VLANs. To round things up: if you haven't yet enabled forwarding, you can do so now. Furthermore, you might wish to augment your route table so that the routing engine in your server knows how to handle packets that it needs to forward from one VLAN to the other: echo 1 > /proc/sys/net/ipv4/ip_forward route add -net 10.1.1.0 netmask 255.255.255.0 gw eth0.2 route add -net 10.1.2.0 netmask 255.255.255.0 gw eth0.3 This is it; nothing to it, right? 0eee61c8c8d0a43496c965f729db633ca12252dd 0 1489 1954 2008-10-29T16:27:35Z Saruman! 2 Page started wikitext text/x-wiki ==E-mail server setup== What we want to accomplish here is the setup of a mail server with the following properties: * can serve multiple mail domains * can relay mail for other domains to other mail servers * can have one or more mailboxes per domain * users of these mailboxes can be virtual (do not need to have a Linux user account) * can have multiple aliases per mailbox * can forward mail for certain aliases to multiple mailboxes For this type of mail server setup, we owe a great thankyou to [http://workaround.org/articles/ispmail-etch/ Christoph Haas] ==Preparation== We'll assume that the server currently has no mailserver installed, at least no other than the default ''exim'' mailserver. Furthermore, the server is already fitted with MySQL, and this database is running without problems. The hostname of the server must be set correctly, so that ''hostname -f'' returns a valid DNS name, like ''lighthouse.saruman.biz.''. It might also be an internal name like ''lighthouse.saruman.lan.'' but that will require us to give extra attention to the name under which Postfix will contact its collegues on the Internet. Also, the server can correctly [Networking_section#DNS_resolution_under_Debian | resolve DNS names] like [http://www.debian.org www.debian.org], preferably by running it's own caching DNS server. The server is kept on the correct date and time using NTP, TCP port 25 is open on the server, the ISP will allow connections from Internet to this port, and if there's a firewall running on this server, then it has port 25 open so as to not block incoming e-mail. ==Software installation== As a first step, we use [[APT and aptitude|apt or aptitude]] to make sure that our server is up-to-date. Then we can install the necessary software packages. Under Debian 5.0 "Lenny", the packages are: * ''postfix'', the mail server itself * ''postfix-doc'', the accompanying documentation * ''postfix-mysql'', necessary to have Postfix talk to our MySQL server * ''postfix-tls'' so we can secure connections to Postfix with the TLS protocol * ''postfix-pcre'' to be able to parse regular expressions, which which we can combat spam At the same time we can purge the following packages: a49b676fe6e9882fbf38b8aedd61d4e50606bba7 1955 1954 2008-10-29T17:16:36Z Saruman! 2 installation procedure finished wikitext text/x-wiki ==E-mail server setup== What we want to accomplish here is the setup of a mail server with the following properties: * can serve multiple mail domains * can relay mail for other domains to other mail servers * can have one or more mailboxes per domain * users of these mailboxes can be virtual (do not need to have a Linux user account) * can have multiple aliases per mailbox * can forward mail for certain aliases to multiple mailboxes For this type of mail server setup, we owe a great thankyou to [http://workaround.org/articles/ispmail-etch/ Christoph Haas] ==Preparation== We'll assume that the server currently has no mailserver installed, at least no other than the default ''exim'' mailserver. Furthermore, the server is already fitted with MySQL, and this database is running without problems. The hostname of the server must be set correctly, so that ''hostname -f'' returns a valid DNS name, like ''lighthouse.saruman.biz.''. It might also be an internal name like ''lighthouse.saruman.lan.'' but that will require us to give extra attention to the name under which Postfix will contact its collegues on the Internet. Also, the server can correctly [Networking_section#DNS_resolution_under_Debian | resolve DNS names] like [http://www.debian.org www.debian.org], preferably by running it's own caching DNS server. The server is kept on the correct date and time using NTP, TCP port 25 is open on the server, the ISP will allow connections from Internet to this port, and if there's a firewall running on this server, then it has port 25 open so as to not block incoming e-mail. ==Software installation== As a first step, we use [[APT and aptitude|apt or aptitude]] to make sure that our server is up-to-date. Then we can install the necessary software packages. Under Debian 5.0 "Lenny", the (single) packages is: * ''postfix'', the mail server itself - this includes the "virtual package" postfix-tls, that we want to use to secure connections to Postfix with the TLS protocol At the same time we can - and must - purge the following packages: * exim4 * exim4-base * exim4-daemon-light * exim4-config In ''aptitude'', only press "go" when you've marked all four of these packages "purge", or you cannot install postfix. When installing the postfix package, the Debian installer script will ask you several questions, which you can answer like this: * General type of mail configuration: Internet site * System mail name: the FQDN of the mail server that you've verified in the previous section. Note that the script will try to guess the DNS name, but that might yield a DNS name with a trailing dot. That is technically correct, but the installation script will barf. Remove the trailing dot before hitting &lt;enter>! * Postmaster mail address: the address that all mail should go to that is addressed to "root" and "postmaster". * Domain list: give the list of all domains that the machine can consider itself the FINAL destination for. This should at a minimum include an empty value, "localhost" and the FQDN of the machine itself (no trailing dots!); however, if you're running your own mail domain, you can also add that (e.g. "saruman.biz"). Thus, the list could look like this: saruman.biz, lighthouse.saruman.lan, localhost.saruman.lan, , localhost * Force synchronous updates? We think that's not necessary, but please read the question and decide for yourself * Local networks: something like ''127.0.0.0/8 [::ffff:127.0.0.0]/104 [::1]/128 192.168.67.0/24'' (the default, augmented with your local IP range) * Mailbox size limits: you can give postfix a limit in bytes, but we're going to use one single big mailbox for all users, so we cannot let Postfix guard it. Leave it at 0 (zero) so we don't have a size limit. * Character for local address extension: we leave it at ''+'' * Internet protocols to use: currently we don't have IPv6 support, so there's no sense in letting Postfix try to serve IPv6. We choose ''ipv4'' only. With the above data, the Debian install script for Postfix can do its job and configure Postfix with some basic settings. Now that Postfix is installed, we can install some dependent packages (we could install them in the same run, but if anything goes amiss with the postfix installation, then these packages are going to remain unconfigured as well): * ''postfix-doc'', the accompanying documentation; * ''postfix-mysql'', necessary to have Postfix talk to our MySQL server; * ''postfix-pcre'' to be able to parse regular expressions, which which we can combat spam. ==Postfix configuration== f7cb3364d366dd7812c31764d377ed80a897953a 1956 1955 2008-10-30T20:50:04Z Saruman! 2 Started MySQL config wikitext text/x-wiki ==E-mail server setup== What we want to accomplish here is the setup of a mail server with the following properties: * can serve multiple mail domains * can relay mail for other domains to other mail servers * can have one or more mailboxes per domain * users of these mailboxes can be virtual (do not need to have a Linux user account) * can have multiple aliases per mailbox * can forward mail for certain aliases to multiple mailboxes For this type of mail server setup, we owe a great thankyou to [http://workaround.org/articles/ispmail-etch/ Christoph Haas] ==Preparation== We'll assume that the server currently has no mailserver installed, at least no other than the default ''exim'' mailserver. Furthermore, the server is already fitted with MySQL, and this database is running without problems. The hostname of the server must be set correctly, so that ''hostname -f'' returns a valid DNS name, like ''lighthouse.saruman.biz.''. It might also be an internal name like ''lighthouse.saruman.lan.'' but that will require us to give extra attention to the name under which Postfix will contact its collegues on the Internet. Also, the server can correctly [Networking_section#DNS_resolution_under_Debian | resolve DNS names] like [http://www.debian.org www.debian.org], preferably by running it's own caching DNS server. The server is kept on the correct date and time using NTP, TCP port 25 is open on the server, the ISP will allow connections from Internet to this port, and if there's a firewall running on this server, then it has port 25 open so as to not block incoming e-mail. ==Software installation== As a first step, we use [[APT and aptitude|apt or aptitude]] to make sure that our server is up-to-date. Then we can install the necessary software packages. Under Debian 5.0 "Lenny", the (single) packages is: * ''postfix'', the mail server itself - this includes the "virtual package" postfix-tls, that we want to use to secure connections to Postfix with the TLS protocol At the same time we can - and must - purge the following packages: * exim4 * exim4-base * exim4-daemon-light * exim4-config In ''aptitude'', only press "go" when you've marked all four of these packages "purge", or you cannot install postfix. When installing the postfix package, the Debian installer script will ask you several questions, which you can answer like this: * General type of mail configuration: Internet site * System mail name: the FQDN of the mail server that you've verified in the previous section. Note that the script will try to guess the DNS name, but that might yield a DNS name with a trailing dot. That is technically correct, but the installation script will barf. Remove the trailing dot before hitting &lt;enter>! * Postmaster mail address: the address that all mail should go to that is addressed to "root" and "postmaster". * Domain list: give the list of all domains that the machine can consider itself the FINAL destination for. This should at a minimum include an empty value, "localhost" and the FQDN of the machine itself (no trailing dots!); however, if you're running your own mail domain, you can also add that (e.g. "saruman.biz"). Thus, the list could look like this: saruman.biz, lighthouse.saruman.lan, localhost.saruman.lan, , localhost * Force synchronous updates? We think that's not necessary, but please read the question and decide for yourself * Local networks: something like ''127.0.0.0/8 [::ffff:127.0.0.0]/104 [::1]/128 192.168.67.0/24'' (the default, augmented with your local IP range) * Mailbox size limits: you can give postfix a limit in bytes, but we're going to use one single big mailbox for all users, so we cannot let Postfix guard it. Leave it at 0 (zero) so we don't have a size limit. * Character for local address extension: we leave it at ''+'' * Internet protocols to use: currently we don't have IPv6 support, so there's no sense in letting Postfix try to serve IPv6. We choose ''ipv4'' only. With the above data, the Debian install script for Postfix can do its job and configure Postfix with some basic settings. Now that Postfix is installed, we can install some dependent packages (we could install them in the same run, but if anything goes amiss with the postfix installation, then these packages are going to remain unconfigured as well): * ''postfix-doc'', the accompanying documentation; * ''postfix-mysql'', necessary to have Postfix talk to our MySQL server; * ''postfix-pcre'' to be able to parse regular expressions, which which we can combat spam; * ''dovecot-imapd'' is a daemon that will provide your users with IMAP access to their mail; * ''dovecot-pop3d'' is another daemon, but for the POP3 protocol. ==MySQL configuration== We will use the MySQL database to record data on our mail system, and then give our Postfix access to this database so that it can read its configuration from there. For starters, we'll create a MySQL database named "vmail", and a MySQL user named "vmail_admin" that can read all necessary data from that "vmail" database. Then, we create the necessary tables. We do this with the MySQL client ''mysql''. However, we're quite lazy, so we don't create this database by hand, but by use of a script [[create.vmail.sql]]. To this end, feed the [[create.vmail.sql]] script into the ''mysql'' client like this: mysql -u root -p < create.vmail.sql (This of course assumes you have ''create.vmail.sql'' in your current working directory; if not you can include the path to the file.) Simply give the MySQL root user password, and the script creates the database, the user, and the necessary tables. ==Postfix configuration== a1f189e684025ba748dc7b696f400c6e3da7e844 1961 1956 2008-10-31T01:15:31Z Saruman! 2 yes wikitext text/x-wiki ==E-mail server setup== What we want to accomplish here is the setup of a mail server with the following properties: * can serve multiple mail domains * can relay mail for other domains to other mail servers * can have one or more mailboxes per domain * users of these mailboxes can be virtual (do not need to have a Linux user account) * can have multiple aliases per mailbox * can forward mail for certain aliases to multiple mailboxes For this type of mail server setup, we owe a great thankyou to [http://workaround.org/articles/ispmail-etch/ Christoph Haas], whose advise has helped us create flexible and reliable mail servers since 2003. ==Preparation== We'll assume that the server currently has no mailserver installed, at least no other than the default ''exim'' mailserver. Furthermore, the server is already fitted with MySQL, and this database is running without problems. The hostname of the server must be set correctly, so that ''hostname -f'' returns a valid DNS name, like ''lighthouse.saruman.biz.''. It might also be an internal name like ''lighthouse.saruman.lan.'' but that will require us to give extra attention to the name under which Postfix will contact its collegues on the Internet. Also, the server can correctly [Networking_section#DNS_resolution_under_Debian | resolve DNS names] like [http://www.debian.org www.debian.org], preferably by running it's own caching DNS server. The server is kept on the correct date and time using NTP, TCP port 25 is open on the server, the ISP will allow connections from Internet to this port, and if there's a firewall running on this server, then it has port 25 open so as to not block incoming e-mail. ==Software installation== As a first step, we use [[APT and aptitude|apt or aptitude]] to make sure that our server is up-to-date. Then we can install the necessary software packages. Under Debian 5.0 "Lenny", the (single) packages is: * ''postfix'', the mail server itself - this includes the "virtual package" postfix-tls, that we want to use to secure connections to Postfix with the TLS protocol At the same time we can - and must - purge the following packages: * exim4 * exim4-base * exim4-daemon-light * exim4-config In ''aptitude'', only press "go" when you've marked all four of these packages "purge", or you cannot install postfix. When installing the postfix package, the Debian installer script will ask you several questions, which you can answer like this: * General type of mail configuration: Internet site * System mail name: the FQDN of the mail server that you've verified in the previous section. Note that the script will try to guess the DNS name, but that might yield a DNS name with a trailing dot. That is technically correct, but the installation script will barf. Remove the trailing dot before hitting &lt;enter>! * Postmaster mail address: the address that all mail should go to that is addressed to "root" and "postmaster". * Domain list: give the list of all domains that the machine can consider itself the FINAL destination for. This should at a minimum include an empty value, "localhost" and the FQDN of the machine itself (no trailing dots!); however, if you're running your own mail domain, you can also add that (e.g. "saruman.biz"). Thus, the list could look like this: saruman.biz, lighthouse.saruman.lan, localhost.saruman.lan, , localhost * Force synchronous updates? We think that's not necessary, but please read the question and decide for yourself * Local networks: something like ''127.0.0.0/8 [::ffff:127.0.0.0]/104 [::1]/128 192.168.67.0/24'' (the default, augmented with your local IP range) * Mailbox size limits: you can give postfix a limit in bytes, but we're going to use one single big mailbox for all users, so we cannot let Postfix guard it. Leave it at 0 (zero) so we don't have a size limit. * Character for local address extension: we leave it at ''+'' * Internet protocols to use: currently we don't have IPv6 support, so there's no sense in letting Postfix try to serve IPv6. We choose ''ipv4'' only. With the above data, the Debian install script for Postfix can do its job and configure Postfix with some basic settings. Now that Postfix is installed, we can install some dependent packages (we could install them in the same run, but if anything goes amiss with the postfix installation, then these packages are going to remain unconfigured as well): * ''postfix-doc'', the accompanying documentation; * ''postfix-mysql'', necessary to have Postfix talk to our MySQL server; * ''postfix-pcre'' to be able to parse regular expressions, which which we can combat spam; * ''dovecot-imapd'' is a daemon that will provide your users with IMAP access to their mail; * ''dovecot-pop3d'' is another daemon, but for the POP3 protocol. ==MySQL configuration== We will use the MySQL database to record data on our mail system, and then give our Postfix access to this database so that it can read its configuration from there. For starters, we'll create a MySQL database named "vmail", and a MySQL user named "vmail_admin" that can read all necessary data from that "vmail" database. Then, we create the necessary tables. We do this with the MySQL client ''mysql''. However, we're quite lazy, so we don't create this database by hand, but by use of a script [[create.vmail.sql]]. To this end, feed the [[create.vmail.sql]] script into the ''mysql'' client like this: mysql -u root -p < create.vmail.sql (This of course assumes you have ''create.vmail.sql'' in your current working directory; if not you can include the path to the file.) Simply give the MySQL root user password, and the script creates the database, the user, and the necessary tables. We're not going to fill the database tables just yet, but we ''are'' going to tell Postfix to use the ''vmail'' database, and also ''how'' to read the database. To this end, we're going to create ==Postfix configuration== a51bcc5f6dd73aa468cc986f234e4cf8d122a788 1964 1961 2008-10-31T08:36:13Z Saruman! 2 Added first mysql config file wikitext text/x-wiki ==E-mail server setup== What we want to accomplish here is the setup of a mail server with the following properties: * can serve multiple mail domains * can relay mail for other domains to other mail servers * can have one or more mailboxes per domain * users of these mailboxes can be virtual (do not need to have a Linux user account) * can have multiple aliases per mailbox * can forward mail for certain aliases to multiple mailboxes For this type of mail server setup, we owe a great thankyou to [http://workaround.org/articles/ispmail-etch/ Christoph Haas], whose advise has helped us create flexible and reliable mail servers since 2003. ==Preparation== We'll assume that the server currently has no mailserver installed, at least no other than the default ''exim'' mailserver. Furthermore, the server is already fitted with MySQL, and this database is running without problems. The hostname of the server must be set correctly, so that ''hostname -f'' returns a valid DNS name, like ''lighthouse.saruman.biz.''. It might also be an internal name like ''lighthouse.saruman.lan.'' but that will require us to give extra attention to the name under which Postfix will contact its collegues on the Internet. Also, the server can correctly [Networking_section#DNS_resolution_under_Debian | resolve DNS names] like [http://www.debian.org www.debian.org], preferably by running it's own caching DNS server. The server is kept on the correct date and time using NTP, TCP port 25 is open on the server, the ISP will allow connections from Internet to this port, and if there's a firewall running on this server, then it has port 25 open so as to not block incoming e-mail. ==Software installation== As a first step, we use [[APT and aptitude|apt or aptitude]] to make sure that our server is up-to-date. Then we can install the necessary software packages. Under Debian 5.0 "Lenny", the (single) packages is: * ''postfix'', the mail server itself - this includes the "virtual package" postfix-tls, that we want to use to secure connections to Postfix with the TLS protocol At the same time we can - and must - purge the following packages: * exim4 * exim4-base * exim4-daemon-light * exim4-config In ''aptitude'', only press "go" when you've marked all four of these packages "purge", or you cannot install postfix. When installing the postfix package, the Debian installer script will ask you several questions, which you can answer like this: * General type of mail configuration: Internet site * System mail name: the FQDN of the mail server that you've verified in the previous section. Note that the script will try to guess the DNS name, but that might yield a DNS name with a trailing dot. That is technically correct, but the installation script will barf. Remove the trailing dot before hitting &lt;enter>! * Postmaster mail address: the address that all mail should go to that is addressed to "root" and "postmaster". * Domain list: give the list of all domains that the machine can consider itself the FINAL destination for. This should at a minimum include an empty value, "localhost" and the FQDN of the machine itself (no trailing dots!); however, if you're running your own mail domain, you can also add that (e.g. "saruman.biz"). Thus, the list could look like this: saruman.biz, lighthouse.saruman.lan, localhost.saruman.lan, , localhost * Force synchronous updates? We think that's not necessary, but please read the question and decide for yourself * Local networks: something like ''127.0.0.0/8 [::ffff:127.0.0.0]/104 [::1]/128 192.168.67.0/24'' (the default, augmented with your local IP range) * Mailbox size limits: you can give postfix a limit in bytes, but we're going to use one single big mailbox for all users, so we cannot let Postfix guard it. Leave it at 0 (zero) so we don't have a size limit. * Character for local address extension: we leave it at ''+'' * Internet protocols to use: currently we don't have IPv6 support, so there's no sense in letting Postfix try to serve IPv6. We choose ''ipv4'' only. With the above data, the Debian install script for Postfix can do its job and configure Postfix with some basic settings. Now that Postfix is installed, we can install some dependent packages (we could install them in the same run, but if anything goes amiss with the postfix installation, then these packages are going to remain unconfigured as well): * ''postfix-doc'', the accompanying documentation; * ''postfix-mysql'', necessary to have Postfix talk to our MySQL server; * ''postfix-pcre'' to be able to parse regular expressions, which which we can combat spam; * ''dovecot-imapd'' is a daemon that will provide your users with IMAP access to their mail; * ''dovecot-pop3d'' is another daemon, but for the POP3 protocol. ==MySQL configuration== We will use the MySQL database to record data on our mail system, and then give our Postfix access to this database so that it can read its configuration from there. For starters, we'll create a MySQL database named "vmail", and a MySQL user named "vmail_admin" that can read all necessary data from that "vmail" database. Then, we create the necessary tables. We do this with the MySQL client ''mysql''. However, we're quite lazy, so we don't create this database by hand, but by use of a script [[create.vmail.sql]]. To this end, feed the [[create.vmail.sql]] script into the ''mysql'' client like this: mysql -u root -p < create.vmail.sql (This of course assumes you have ''create.vmail.sql'' in your current working directory; if not you can include the path to the file.) Simply give the MySQL root user password, and the script creates the database, the user, and the necessary tables. We're not going to fill the database tables just yet, but we ''are'' going to tell Postfix to use the ''vmail'' database, and also ''how'' to read the database. To this end, we're going to create three configuration files in directory ''/etc/postfix''. We'll start off with one configuration file, with which Postfix can determine if a domain name is among the domain(s) that it's actually hosting mailboxes for. Create file ''/etc/postfix/mysql-virtual-domains.cf'' with the following content: user = vmail_admin password = SuperSecret hosts = 127.0.0.1 dbname = vmail query = SELECT 1 FROM virtual_domains WHERE vdomain='%s' Next, we change the attributes on this configuration file so that it is secure. Also, we tell postfix to check this configuration file when it needs to check "virtual_mailbox_domains": chown root:postfix /etc/postfix/mysql-virtual-domains.cf chmod o=/etc/postfix/mysql-virtual-domains.cf postconf -e virtual_mailbox_domains=mysql:/etc/postfix/mysql-virtual-domains.cf Use of this configuration file in postfix has the effect of returning "yes" when checking our database for the domain part of an email address. Naturally, this configuration file has to be fitted with the actual ''vmail_admin'' password rather than our example "SuperSecret". Furthermore, we'll have to fill our database with all virtual domains that we're hosting, by running the mysql client and feeding it information like this: mysql -u root -p vmail mysql> INSERT INTO virtual_domains (id, vdomain) VALUES (1, 'saruman.biz'); mysql> INSERT INTO virtual_domains (vdomain) VALUES ('wiki.saruman.biz'); mysql> INSERT INTO virtual_domains (vdomain) VALUES ('shop.saruman.biz'); mysql> exit This has the effect of creating three entries. Only the first entry needs an ''id'' value, because in MySQL we've defined that field as AUTO_INCREMENT. After creating your first virtual domain in the table, you never have to use a statement like the first INSERT again, only statements like the other two. After creating data like this, postfix will be able to recognise that you have three virtual mail domains (namely the three domains in the VALUES section) for which it hosts virtual mailboxes. However, 12e7a538c781b178b41acf617e55a53127e51242 1969 1964 2008-11-01T09:41:51Z Saruman! 2 /* MySQL configuration */ added data addition wikitext text/x-wiki ==E-mail server setup== What we want to accomplish here is the setup of a mail server with the following properties: * can serve multiple mail domains * can relay mail for other domains to other mail servers * can have one or more mailboxes per domain * users of these mailboxes can be virtual (do not need to have a Linux user account) * can have multiple aliases per mailbox * can forward mail for certain aliases to multiple mailboxes For this type of mail server setup, we owe a great thankyou to [http://workaround.org/articles/ispmail-etch/ Christoph Haas], whose advise has helped us create flexible and reliable mail servers since 2003. ==Preparation== We'll assume that the server currently has no mailserver installed, at least no other than the default ''exim'' mailserver. Furthermore, the server is already fitted with MySQL, and this database is running without problems. The hostname of the server must be set correctly, so that ''hostname -f'' returns a valid DNS name, like ''lighthouse.saruman.biz.''. It might also be an internal name like ''lighthouse.saruman.lan.'' but that will require us to give extra attention to the name under which Postfix will contact its collegues on the Internet. Also, the server can correctly [Networking_section#DNS_resolution_under_Debian | resolve DNS names] like [http://www.debian.org www.debian.org], preferably by running it's own caching DNS server. The server is kept on the correct date and time using NTP, TCP port 25 is open on the server, the ISP will allow connections from Internet to this port, and if there's a firewall running on this server, then it has port 25 open so as to not block incoming e-mail. ==Software installation== As a first step, we use [[APT and aptitude|apt or aptitude]] to make sure that our server is up-to-date. Then we can install the necessary software packages. Under Debian 5.0 "Lenny", the (single) packages is: * ''postfix'', the mail server itself - this includes the "virtual package" postfix-tls, that we want to use to secure connections to Postfix with the TLS protocol At the same time we can - and must - purge the following packages: * exim4 * exim4-base * exim4-daemon-light * exim4-config In ''aptitude'', only press "go" when you've marked all four of these packages "purge", or you cannot install postfix. When installing the postfix package, the Debian installer script will ask you several questions, which you can answer like this: * General type of mail configuration: Internet site * System mail name: the FQDN of the mail server that you've verified in the previous section. Note that the script will try to guess the DNS name, but that might yield a DNS name with a trailing dot. That is technically correct, but the installation script will barf. Remove the trailing dot before hitting &lt;enter>! * Postmaster mail address: the address that all mail should go to that is addressed to "root" and "postmaster". * Domain list: give the list of all domains that the machine can consider itself the FINAL destination for. This should at a minimum include an empty value, "localhost" and the FQDN of the machine itself (no trailing dots!); however, if you're running your own mail domain, you can also add that (e.g. "saruman.biz"). Thus, the list could look like this: saruman.biz, lighthouse.saruman.lan, localhost.saruman.lan, , localhost * Force synchronous updates? We think that's not necessary, but please read the question and decide for yourself * Local networks: something like ''127.0.0.0/8 [::ffff:127.0.0.0]/104 [::1]/128 192.168.67.0/24'' (the default, augmented with your local IP range) * Mailbox size limits: you can give postfix a limit in bytes, but we're going to use one single big mailbox for all users, so we cannot let Postfix guard it. Leave it at 0 (zero) so we don't have a size limit. * Character for local address extension: we leave it at ''+'' * Internet protocols to use: currently we don't have IPv6 support, so there's no sense in letting Postfix try to serve IPv6. We choose ''ipv4'' only. With the above data, the Debian install script for Postfix can do its job and configure Postfix with some basic settings. Now that Postfix is installed, we can install some dependent packages (we could install them in the same run, but if anything goes amiss with the postfix installation, then these packages are going to remain unconfigured as well): * ''postfix-doc'', the accompanying documentation; * ''postfix-mysql'', necessary to have Postfix talk to our MySQL server; * ''postfix-pcre'' to be able to parse regular expressions, which which we can combat spam; * ''dovecot-imapd'' is a daemon that will provide your users with IMAP access to their mail; * ''dovecot-pop3d'' is another daemon, but for the POP3 protocol. ==Virtual Mailman creation== When we're done, we'll need a "system user", a sort of virtual mailman that is the owner of all mailboxes that we're serving. We suggest the name "vmail" for this user. Note: this user does not get his own mailbox (i.e. there's no mailbox at vmail@saruman.biz). To create this user, and his home directory, we can run the following commands: groupadd -g 120 vmail useradd -g vmail -u 120 vmail -d /data/vmail -m -s /bin/false As you see, we've chosen a group ID and user ID of 120 (after confirming that this ID was not taken by another group or user, by checking ''/etc/passwd'' and ''/etc/group''. Furthermore, we've decided to keep the ''vmail'' user's home directory not under ''/home/vmail'', but in a special place where we're going to expect server data to reside - in our server, the ''/data'' directory (which is a RAID-5 array mounted under root). By adding ''-m'', we've actually created the home directory, and adding ''-s /bin/false'' makes totally sure that the user ''vmail'' can never ever log in - even if we've not created a password for this user, so ''vmail'' shouldn't be able to log in anyway. Better safe than sorry. To tell Postfix that this ''vmail'' user is someone special, we run postconf -e virtual_uid_maps=static:120 postconf -e virtual_gid_maps=static:120 That makes postfix understand that all mail for the virtual mail domains must be written to disk with these specified user and group ID's. ==MySQL configuration== We will use the MySQL database to record data on our mail system, and then give our Postfix access to this database so that it can read its configuration from there. For starters, we'll create a MySQL database named "vmail", and a MySQL user named "vmail_admin" that can read all necessary data from that "vmail" database. Then, we create the necessary tables. We do this with the MySQL client ''mysql''. However, we're quite lazy, so we don't create this database by hand, but by use of a script [[create.vmail.sql]]. To this end, feed the [[create.vmail.sql]] script into the ''mysql'' client like this: mysql -u root -p < create.vmail.sql (This of course assumes you have ''create.vmail.sql'' in your current working directory; if not you can include the path to the file.) Simply give the MySQL root user password, and the script creates the database, the user, and the necessary tables. Next up, we fill the database with the first sets of values. We'll start off with the virtual domains that we're hosting, by running the mysql client and feeding it information like this: mysql -u root -p vmail mysql> INSERT INTO virtual_domains (id, vdomain) VALUES (1, 'saruman.biz'); mysql> INSERT INTO virtual_domains (vdomain) VALUES ('wiki.saruman.biz'); mysql> INSERT INTO virtual_domains (vdomain) VALUES ('shop.saruman.biz'); mysql> exit This has the effect of creating three entries. Now Postfix will be able to recognise that you have three virtual mail domains (namely the three domains in the VALUES section) for which it hosts virtual mailboxes. Note: only the first entry needs an ''id'' value, because in MySQL we've defined that field as AUTO_INCREMENT. After creating your first virtual domain in the table, you never have to use a statement like the first INSERT again, only statements like the other two. Whle still within the mysql client, we can now create users: mysql> INSERT INTO virtual_users (id, domain_id, user, passwd) VALUES (1, 1, 'jan', MD5('JanSecret')); mysql> INSERT INTO virtual_users (domain_id, user, passwd) VALUES (1, 'mike', MD5('MikeSecret')); mysql> INSERT INTO virtual_users (domain_id, user, passwd) VALUES (3, 'shopkeeper', MD5('ShopSecret')); This has the effect of creating three users "jan" (in domain saruman.biz), "mike" (in domain saruman.biz) and "shopkeeper" (in domain shop.saruman.biz). Again, the ''id'' value is only ever needed in the first statement, because from now on every user addition will auto-increment ''id''. The passwords shown are encrypted with MD5, and put in the ''passwd'' field. Later on, the users will be able to access their mailboxes using this password; we won't tell Postfix anything about them, because it doesn't need the passwords. Next, we're going to tell Postfix to use the ''vmail'' database, and also how to read the database (Postfix never writes the MySQL database). To this end, we're going to create three configuration files in directory ''/etc/postfix''. We'll start off with one configuration file, with which Postfix can determine if a domain name is among the domain(s) that it's actually hosting mailboxes for. Then we'll create the config file that checks the table that contains all the users that have a virtual mailbox, and finally we create the lookup for the table with all the aliases. ===Virtual mail domains lookup=== Create file ''/etc/postfix/mysql-virtual-domains.cf'' with the following content: user = vmail_admin password = SuperSecret hosts = 127.0.0.1 dbname = vmail query = SELECT 1 FROM virtual_domains WHERE vdomain='%s' Next, we change the attributes on this configuration file so that it is secure. Also, we tell postfix to check this configuration file when it needs to check "virtual_mailbox_domains": chown root:postfix /etc/postfix/mysql-virtual-domains.cf chmod o=/etc/postfix/mysql-virtual-domains.cf postconf -e virtual_mailbox_domains=mysql:/etc/postfix/mysql-virtual-domains.cf Use of this configuration file in postfix has the effect of returning "yes" when checking our database for the domain part of an email address. Naturally, this configuration file has to be fitted with the actual ''vmail_admin'' password rather than our example "SuperSecret". === Virtual mail user lookup=== Create the file ''/etc/postfix/mysql-virtual-mailbox-maps.cf'' with the following content: user = vmail_admin password = SuperSecret hosts = 127.0.0.1 dbname = vmail query = SELECT 1 FROM view_users WHERE email='%s' Next, we change the attributes on this configuration file so that it is secure. Also, we tell Postfix that this mapping file is supposed to be used for the ''virtual_mailbox_maps'' mapping: chown root:postfix /etc/postfix/mysql-virtual-mailbox-maps.cf chmod o=/etc/postfix/mysql-virtual-mailbox-maps.cf postconf -e virtual_mailbox_maps=mysql:/etc/postfix/mysql-virtual-mailbox-maps.cf However, the lookup of virtual mailboxes at present will not work (yet), because we need data in the ''users'' table. d770a980763aca48be0633ecf9e6832dd87a5841 1971 1969 2008-11-01T10:31:17Z Saruman! 2 /* MySQL configuration */ added virtual aliases wikitext text/x-wiki ==E-mail server setup== What we want to accomplish here is the setup of a mail server with the following properties: * can serve multiple mail domains * can relay mail for other domains to other mail servers * can have one or more mailboxes per domain * users of these mailboxes can be virtual (do not need to have a Linux user account) * can have multiple aliases per mailbox * can forward mail for certain aliases to multiple mailboxes For this type of mail server setup, we owe a great thankyou to [http://workaround.org/articles/ispmail-etch/ Christoph Haas], whose advise has helped us create flexible and reliable mail servers since 2003. ==Preparation== We'll assume that the server currently has no mailserver installed, at least no other than the default ''exim'' mailserver. Furthermore, the server is already fitted with MySQL, and this database is running without problems. The hostname of the server must be set correctly, so that ''hostname -f'' returns a valid DNS name, like ''lighthouse.saruman.biz.''. It might also be an internal name like ''lighthouse.saruman.lan.'' but that will require us to give extra attention to the name under which Postfix will contact its collegues on the Internet. Also, the server can correctly [Networking_section#DNS_resolution_under_Debian | resolve DNS names] like [http://www.debian.org www.debian.org], preferably by running it's own caching DNS server. The server is kept on the correct date and time using NTP, TCP port 25 is open on the server, the ISP will allow connections from Internet to this port, and if there's a firewall running on this server, then it has port 25 open so as to not block incoming e-mail. ==Software installation== As a first step, we use [[APT and aptitude|apt or aptitude]] to make sure that our server is up-to-date. Then we can install the necessary software packages. Under Debian 5.0 "Lenny", the (single) packages is: * ''postfix'', the mail server itself - this includes the "virtual package" postfix-tls, that we want to use to secure connections to Postfix with the TLS protocol At the same time we can - and must - purge the following packages: * exim4 * exim4-base * exim4-daemon-light * exim4-config In ''aptitude'', only press "go" when you've marked all four of these packages "purge", or you cannot install postfix. When installing the postfix package, the Debian installer script will ask you several questions, which you can answer like this: * General type of mail configuration: Internet site * System mail name: the FQDN of the mail server that you've verified in the previous section. Note that the script will try to guess the DNS name, but that might yield a DNS name with a trailing dot. That is technically correct, but the installation script will barf. Remove the trailing dot before hitting &lt;enter>! * Postmaster mail address: the address that all mail should go to that is addressed to "root" and "postmaster". * Domain list: give the list of all domains that the machine can consider itself the FINAL destination for. This should at a minimum include an empty value, "localhost" and the FQDN of the machine itself (no trailing dots!); however, if you're running your own mail domain, you can also add that (e.g. "saruman.biz"). Thus, the list could look like this: saruman.biz, lighthouse.saruman.lan, localhost.saruman.lan, , localhost * Force synchronous updates? We think that's not necessary, but please read the question and decide for yourself * Local networks: something like ''127.0.0.0/8 [::ffff:127.0.0.0]/104 [::1]/128 192.168.67.0/24'' (the default, augmented with your local IP range) * Mailbox size limits: you can give postfix a limit in bytes, but we're going to use one single big mailbox for all users, so we cannot let Postfix guard it. Leave it at 0 (zero) so we don't have a size limit. * Character for local address extension: we leave it at ''+'' * Internet protocols to use: currently we don't have IPv6 support, so there's no sense in letting Postfix try to serve IPv6. We choose ''ipv4'' only. With the above data, the Debian install script for Postfix can do its job and configure Postfix with some basic settings. Now that Postfix is installed, we can install some dependent packages (we could install them in the same run, but if anything goes amiss with the postfix installation, then these packages are going to remain unconfigured as well): * ''postfix-doc'', the accompanying documentation; * ''postfix-mysql'', necessary to have Postfix talk to our MySQL server; * ''postfix-pcre'' to be able to parse regular expressions, which which we can combat spam; * ''dovecot-imapd'' is a daemon that will provide your users with IMAP access to their mail; * ''dovecot-pop3d'' is another daemon, but for the POP3 protocol. ==Virtual Mailman creation== When we're done, we'll need a "system user", a sort of virtual mailman that is the owner of all mailboxes that we're serving. We suggest the name "vmail" for this user. Note: this user does not get his own mailbox (i.e. there's no mailbox at vmail@saruman.biz). To create this user, and his home directory, we can run the following commands: groupadd -g 120 vmail useradd -g vmail -u 120 vmail -d /data/vmail -m -s /bin/false As you see, we've chosen a group ID and user ID of 120 (after confirming that this ID was not taken by another group or user, by checking ''/etc/passwd'' and ''/etc/group''. Furthermore, we've decided to keep the ''vmail'' user's home directory not under ''/home/vmail'', but in a special place where we're going to expect server data to reside - in our server, the ''/data'' directory (which is a RAID-5 array mounted under root). By adding ''-m'', we've actually created the home directory, and adding ''-s /bin/false'' makes totally sure that the user ''vmail'' can never ever log in - even if we've not created a password for this user, so ''vmail'' shouldn't be able to log in anyway. Better safe than sorry. To tell Postfix that this ''vmail'' user is someone special, we run postconf -e virtual_uid_maps=static:120 postconf -e virtual_gid_maps=static:120 That makes postfix understand that all mail for the virtual mail domains must be written to disk with these specified user and group ID's. ==MySQL configuration== ===Database preparation=== We will use the MySQL database to record data on our mail system, and then give our Postfix access to this database so that it can read its configuration from there. For starters, we'll create a MySQL database named "vmail", and a MySQL user named "vmail_admin" that can read all necessary data from that "vmail" database. Then, we create the necessary tables, and a view that links these tables. We do this with the MySQL client ''mysql''. However, we're quite lazy, so we don't create this database by hand (that's error-prone), but by use of a script [[create.vmail.sql]]. To this end, feed the [[create.vmail.sql]] script into the ''mysql'' client like this: mysql -u root -p < create.vmail.sql (This of course assumes you have ''create.vmail.sql'' in your current working directory; if not you can include the path to the file.) Simply give the MySQL root user password, and the script creates the database, the user, the necessary tables, and the view.<br> A note of caution: it is never a good idea to just run scripts without a proper understanding of what it does. Especially with MySQL, it will be advantageous if you understand the SQL commands. Open the script in a text editor, open the [http://dev.mysql.com/doc/refman/5.0/en/ MySQL command reference], and trace back what the script does exactly. ===Inserting data=== Next up, we fill the database with the first sets of values (either test data or the first of our production data). We'll start off with the virtual domains that we're hosting, by running the mysql client and feeding it information like this: mysql -u root -p vmail mysql> INSERT INTO virtual_domains (id, vdomain) VALUES (1, 'saruman.biz'); mysql> INSERT INTO virtual_domains (vdomain) VALUES ('wiki.saruman.biz'); mysql> INSERT INTO virtual_domains (vdomain) VALUES ('shop.saruman.biz'); This has the effect of creating three entries. You can check that everything worked as planned by executing mysql> select * from virtual_domains; Note: only the first entry needs an ''id'' value, because in MySQL we've defined that field as AUTO_INCREMENT. After creating your first virtual domain in the table, you never have to use a statement like the first INSERT again, only statements like the other two. Now the MySQL database has the information needed by Postfix to recognise that you have three virtual mail domains (namely the three domains in the VALUES section) for which it hosts virtual mailboxes. Postfix cannot read this information yet, but that'll be taken care of in the next section. Whle still within the mysql client, we can now create users: mysql> INSERT INTO virtual_users (id, domain_id, user, passwd) VALUES (1, 1, 'jan', MD5('JanSecret')); mysql> INSERT INTO virtual_users (domain_id, user, passwd) VALUES (1, 'mike', MD5('MikeSecret')); mysql> INSERT INTO virtual_users (domain_id, user, passwd) VALUES (3, 'shopkeeper', MD5('ShopSecret')); This has the effect of creating three users "jan" (in domain saruman.biz), "mike" (in domain saruman.biz) and "shopkeeper" (in domain shop.saruman.biz). Again, the ''id'' value is only ever needed in the first statement, because from now on every user addition will auto-increment ''id''. The passwords shown are encrypted with MD5, and put in the ''passwd'' field. Later on, the users will be able to access their mailboxes using this password; we won't tell Postfix anything about them, because it doesn't need the passwords. You can check the content of the ''virtual_users'' table with the right "select" statement, and you can now also see that the view ''view-users'' works: mysql> select * from virtual_users; mysql> select * from view_users; Next up, we're going to add some aliases, which are alternative e-mail addresses for the users; their primary e-mail address can already be seen in the ''view_users'' view, but perhaps you also want mail to "webmaster@shop.saruman.biz" to arrive at one or more mailboxes, e.g. in the mailbox for user "shopkeeper" (within domain "shop.saruman.biz") and this guy's home address ("j.doe@example.com") mysql> INSERT INTO virtual_aliases (id, domain_id, source, destination) VALUES (1, 2, 'webmaster', 'shopkeeper@shop.saruman.biz'); mysql> INSERT INTO virtual_aliases (domain_id, source, destination) VALUES (2, 'webmaster', 'j.doe@example.com'); Again, we don't need to add the ''id'' value any more after the first ever insertion into this table. We can check the result by running a select statement against the ''virtual_aliases'' table and ''view_aliases'' view: mysql> select * from virtual_aliases; mysql> select * from view_aliases; == Postfix configuration for MySQL lookups== Next, we're going to tell Postfix to use the ''vmail'' database, and also how to read the database (Postfix never writes the MySQL database). To this end, we're going to create three configuration files in directory ''/etc/postfix''. We'll start off with one configuration file, with which Postfix can determine if a domain name is among the domain(s) that it's actually hosting mailboxes for. Then we'll create the config file that checks the table that contains all the users that have a virtual mailbox, and finally we create the lookup for the table with all the aliases. ===Virtual mail domains lookup=== Create file ''/etc/postfix/mysql-virtual-domains.cf'' with the following content: user = vmail_admin password = SuperSecret hosts = 127.0.0.1 dbname = vmail query = SELECT 1 FROM virtual_domains WHERE vdomain='%s' Next, we change the attributes on this configuration file so that it is secure. Also, we tell postfix to check this configuration file when it needs to check "virtual_mailbox_domains": chown root:postfix /etc/postfix/mysql-virtual-domains.cf chmod o=/etc/postfix/mysql-virtual-domains.cf postconf -e virtual_mailbox_domains=mysql:/etc/postfix/mysql-virtual-domains.cf Use of this configuration file in postfix has the effect of returning "yes" when checking our database for the domain part of an email address. Naturally, this configuration file has to be fitted with the actual ''vmail_admin'' password rather than our example "SuperSecret". === Virtual mail user lookup=== Create the file ''/etc/postfix/mysql-virtual-mailbox-maps.cf'' with the following content: user = vmail_admin password = SuperSecret hosts = 127.0.0.1 dbname = vmail query = SELECT 1 FROM view_users WHERE email='%s' Next, we change the attributes on this configuration file so that it is secure. Also, we tell Postfix that this mapping file is supposed to be used for the ''virtual_mailbox_maps'' mapping: chown root:postfix /etc/postfix/mysql-virtual-mailbox-maps.cf chmod o=/etc/postfix/mysql-virtual-mailbox-maps.cf postconf -e virtual_mailbox_maps=mysql:/etc/postfix/mysql-virtual-mailbox-maps.cf However, the lookup of virtual mailboxes at present will not work (yet), because we need data in the ''users'' table. 5f17a850a142c3d7741396a7d7066744f1d06ae9 1974 1971 2008-11-01T13:54:53Z Saruman! 2 added virtual alias lookup section wikitext text/x-wiki ==E-mail server setup== What we want to accomplish here is the setup of a mail server with the following properties: * can serve multiple mail domains * can relay mail for other domains to other mail servers * can have one or more mailboxes per domain * users of these mailboxes can be virtual (do not need to have a Linux user account) * can have multiple aliases per mailbox * can forward mail for certain aliases to multiple mailboxes For this type of mail server setup, we owe a great thankyou to [http://workaround.org/articles/ispmail-etch/ Christoph Haas], whose advise has helped us create flexible and reliable mail servers since 2003. ==Preparation== We'll assume that the server currently has no mailserver installed, at least no other than the default ''exim'' mailserver. Furthermore, the server is already fitted with MySQL, and this database is running without problems. The hostname of the server must be set correctly, so that ''hostname -f'' returns a valid DNS name, like ''lighthouse.saruman.biz.''. It might also be an internal name like ''lighthouse.saruman.lan.'' but that will require us to give extra attention to the name under which Postfix will contact its collegues on the Internet. Also, the server can correctly [Networking_section#DNS_resolution_under_Debian | resolve DNS names] like [http://www.debian.org www.debian.org], preferably by running it's own caching DNS server. The server is kept on the correct date and time using NTP, TCP port 25 is open on the server, the ISP will allow connections from Internet to this port, and if there's a firewall running on this server, then it has port 25 open so as to not block incoming e-mail. ==Software installation== As a first step, we use [[APT and aptitude|apt or aptitude]] to make sure that our server is up-to-date. Then we can install the necessary software packages. Under Debian 5.0 "Lenny", the (single) packages is: * ''postfix'', the mail server itself - this includes the "virtual package" postfix-tls, that we want to use to secure connections to Postfix with the TLS protocol At the same time we can - and must - purge the following packages: * exim4 * exim4-base * exim4-daemon-light * exim4-config In ''aptitude'', only press "go" when you've marked all four of these packages "purge", or you cannot install postfix. When installing the postfix package, the Debian installer script will ask you several questions, which you can answer like this: * General type of mail configuration: Internet site * System mail name: the FQDN of the mail server that you've verified in the previous section. Note that the script will try to guess the DNS name, but that might yield a DNS name with a trailing dot. That is technically correct, but the installation script will barf. Remove the trailing dot before hitting &lt;enter>! * Postmaster mail address: the address that all mail should go to that is addressed to "root" and "postmaster". * Domain list: give the list of all domains that the machine can consider itself the FINAL destination for. This should at a minimum include an empty value, "localhost" and the FQDN of the machine itself (no trailing dots!); however, if you're running your own mail domain, you can also add that (e.g. "saruman.biz"). Thus, the list could look like this: saruman.biz, lighthouse.saruman.lan, localhost.saruman.lan, , localhost * Force synchronous updates? We think that's not necessary, but please read the question and decide for yourself * Local networks: something like ''127.0.0.0/8 [::ffff:127.0.0.0]/104 [::1]/128 192.168.67.0/24'' (the default, augmented with your local IP range) * Mailbox size limits: you can give postfix a limit in bytes, but we're going to use one single big mailbox for all users, so we cannot let Postfix guard it. Leave it at 0 (zero) so we don't have a size limit. * Character for local address extension: we leave it at ''+'' * Internet protocols to use: currently we don't have IPv6 support, so there's no sense in letting Postfix try to serve IPv6. We choose ''ipv4'' only. With the above data, the Debian install script for Postfix can do its job and configure Postfix with some basic settings. Now that Postfix is installed, we can install some dependent packages (we could install them in the same run, but if anything goes amiss with the postfix installation, then these packages are going to remain unconfigured as well): * ''postfix-doc'', the accompanying documentation; * ''postfix-mysql'', necessary to have Postfix talk to our MySQL server; * ''postfix-pcre'' to be able to parse regular expressions, which which we can combat spam; * ''dovecot-imapd'' is a daemon that will provide your users with IMAP access to their mail; * ''dovecot-pop3d'' is another daemon, but for the POP3 protocol. ==Virtual Mailman creation== When we're done, we'll need a "system user", a sort of virtual mailman that is the owner of all mailboxes that we're serving. We suggest the name "vmail" for this user. Note: this user does not get his own mailbox (i.e. there's no mailbox at vmail@saruman.biz). To create this user, and his home directory, we can run the following commands: groupadd -g 120 vmail useradd -g vmail -u 120 vmail -d /data/vmail -m -s /bin/false As you see, we've chosen a group ID and user ID of 120 (after confirming that this ID was not taken by another group or user, by checking ''/etc/passwd'' and ''/etc/group''. Furthermore, we've decided to keep the ''vmail'' user's home directory not under ''/home/vmail'', but in a special place where we're going to expect server data to reside - in our server, the ''/data'' directory (which is a RAID-5 array mounted under root). By adding ''-m'', we've actually created the home directory, and adding ''-s /bin/false'' makes totally sure that the user ''vmail'' can never ever log in - even if we've not created a password for this user, so ''vmail'' shouldn't be able to log in anyway. Better safe than sorry. To tell Postfix that this ''vmail'' user is someone special, we run postconf -e virtual_uid_maps=static:120 postconf -e virtual_gid_maps=static:120 That makes postfix understand that all mail for the virtual mail domains must be written to disk with these specified user and group ID's. ==MySQL configuration== ===Database preparation=== We will use the MySQL database to record data on our mail system, and then give our Postfix access to this database so that it can read its configuration from there. For starters, we'll create a MySQL database named "vmail", and a MySQL user named "vmail_admin" that can read all necessary data from that "vmail" database. Then, we create the necessary tables, and a view that links these tables. We do this with the MySQL client ''mysql''. However, we're quite lazy, so we don't create this database by hand (that's error-prone), but by use of a script [[create.vmail.sql]]. To this end, feed the [[create.vmail.sql]] script into the ''mysql'' client like this: mysql -u root -p < create.vmail.sql (This of course assumes you have ''create.vmail.sql'' in your current working directory; if not you can include the path to the file.) Simply give the MySQL root user password, and the script creates the database, the user, the necessary tables, and the view.<br> A note of caution: it is never a good idea to just run scripts without a proper understanding of what it does. Especially with MySQL, it will be advantageous if you understand the SQL commands. Open the script in a text editor, open the [http://dev.mysql.com/doc/refman/5.0/en/ MySQL command reference], and trace back what the script does exactly. ===Inserting data=== Next up, we fill the database with the first sets of values (either test data or the first of our production data). We'll start off with the virtual domains that we're hosting, by running the mysql client and feeding it information like this: mysql -u root -p vmail mysql> INSERT INTO virtual_domains (id, vdomain) VALUES (1, 'saruman.biz'); mysql> INSERT INTO virtual_domains (vdomain) VALUES ('wiki.saruman.biz'); mysql> INSERT INTO virtual_domains (vdomain) VALUES ('shop.saruman.biz'); This has the effect of creating three entries. You can check that everything worked as planned by executing mysql> select * from virtual_domains; Note: only the first entry needs an ''id'' value, because in MySQL we've defined that field as AUTO_INCREMENT. After creating your first virtual domain in the table, you never have to use a statement like the first INSERT again, only statements like the other two. Now the MySQL database has the information needed by Postfix to recognise that you have three virtual mail domains (namely the three domains in the VALUES section) for which it hosts virtual mailboxes. Postfix cannot read this information yet, but that'll be taken care of in the next section. Whle still within the mysql client, we can now create users: mysql> INSERT INTO virtual_users (id, domain_id, user, passwd) VALUES (1, 1, 'jan', MD5('JanSecret')); mysql> INSERT INTO virtual_users (domain_id, user, passwd) VALUES (1, 'mike', MD5('MikeSecret')); mysql> INSERT INTO virtual_users (domain_id, user, passwd) VALUES (3, 'shopkeeper', MD5('ShopSecret')); This has the effect of creating three users "jan" (in domain saruman.biz), "mike" (in domain saruman.biz) and "shopkeeper" (in domain shop.saruman.biz). Again, the ''id'' value is only ever needed in the first statement, because from now on every user addition will auto-increment ''id''. The passwords shown are encrypted with MD5, and put in the ''passwd'' field. Later on, the users will be able to access their mailboxes using this password; we won't tell Postfix anything about them, because it doesn't need the passwords. You can check the content of the ''virtual_users'' table with the right "select" statement, and you can now also see that the view ''view-users'' works: mysql> select * from virtual_users; mysql> select * from view_users; Next up, we're going to add some aliases, which are alternative e-mail addresses for the users; their primary e-mail address can already be seen in the ''view_users'' view, but perhaps you also want mail to "webmaster@shop.saruman.biz" to arrive at one or more mailboxes, e.g. in the mailbox for user "shopkeeper" (within domain "shop.saruman.biz") and this guy's home address ("j.doe@example.com"). Furthermore, we'll define catchall-addresses for all domains, that'll send all mail for which no mailbox can be found to the mailbox of user Mike (for the first two domains) and Webmaster (for shop.saruman.biz; Webmaster himself is an alias yet again, that points to shopkeeper@shop.saruman.biz). To create the catchall, leave out a value for the source address. This creates the empty value for source that will be expanded (using source@domain) to "@domain". mysql> INSERT INTO virtual_aliases (id, domain_id, source, destination) VALUES (1, 2, 'webmaster', 'shopkeeper@shop.saruman.biz'); mysql> INSERT INTO virtual_aliases (domain_id, source, destination) VALUES (2, 'webmaster', 'j.doe@example.com'); mysql> INSERT INTO virtual_aliases (domain_id, destination) VALUES (1, 'mike@saruman.biz'); mysql> INSERT INTO virtual_aliases (domain_id, destination) VALUES (2, 'mike@saruman.biz'); mysql> INSERT INTO virtual_aliases (domain_id, destination) VALUES (3, 'webmaster@saruman.biz'); Again, we don't need to add the ''id'' value any more after the first ever insertion into this table. We can check the result by running a select statement against the ''virtual_aliases'' table and ''view_aliases'' view: mysql> select * from virtual_aliases; mysql> select * from view_aliases; == Postfix configuration for MySQL lookups== Next, we're going to tell Postfix to use the ''vmail'' database, and also how to read the database (Postfix never writes the MySQL database). To this end, we're going to create three configuration files in directory ''/etc/postfix''. We'll start off with one configuration file, with which Postfix can determine if a domain name is among the domain(s) that it's actually hosting mailboxes for. Then we'll create the config file that checks the table that contains all the users that have a virtual mailbox, and finally we create the lookup for the table with all the aliases. ===Virtual mail domains lookup=== Create file ''/etc/postfix/mysql-virtual-domains.cf'' with the following content: user = vmail_admin password = SuperSecret hosts = 127.0.0.1 dbname = vmail query = SELECT 1 FROM virtual_domains WHERE vdomain='%s' Next, we tell postfix to check this configuration file when it needs to check "virtual_mailbox_domains": postconf -e virtual_mailbox_domains=mysql:/etc/postfix/mysql-virtual-domains.cf Use of this configuration file in postfix has the effect of returning "yes" when checking our database for the domain part of an email address. Naturally, this configuration file has to be fitted with the actual ''vmail_admin'' password rather than our example "SuperSecret". === Virtual mail user lookup=== Create the file ''/etc/postfix/mysql-virtual-mailbox-maps.cf'' with the following content: user = vmail_admin password = SuperSecret hosts = 127.0.0.1 dbname = vmail query = SELECT 1 FROM view_users WHERE email='%s' Next, we tell Postfix that this mapping file is supposed to be used for the ''virtual_mailbox_maps'' mapping: postconf -e virtual_mailbox_maps=mysql:/etc/postfix/mysql-virtual-mailbox-maps.cf The lookup of virtual mailboxes should work with the data we've put into the database previously. i.e. postmap -q jan@saruman.biz mysql:/etc/postfix/mysql-virtual-mailbox-maps.cf should return a '''1''' to acknowledge that "jan@saruman.biz" is indeed a virtual mailbox in our Postfix configuration. === Virtual alias lookup=== Create another cf file at ''/etc/postfix/mysql-virtual-alias-maps.cf'': user = vmail_admin password = SuperSecret hosts = 127.0.0.1 dbname = vmail query = SELECT destination FROM view_aliases WHERE email='%s' And create yet another cf file at ''/etc/postfix/mysql-email2email.cf'': user = vmail_admin password = SuperSecret hosts = 127.0.0.1 dbname = vmail query = SELECT email FROM view_users WHERE email='%s' Again, we tell Postfix that this mapping file is supposed to be used for the ''virtual_alias_maps'' mapping: postconf -e virtual_alias_maps=mysql:/etc/postfix/mysql-virtual-alias-maps.cf,mysql:/etc/postfix/mysql-email2email.cf The lookup of virtual aliases should now work as designed: postmap -q shopkeeper@shop.saruman.biz mysql:/etc/postfix/mysql-virtual-alias-maps.cf postmap -q webmaster@shop.saruman.biz mysql:/etc/postfix/mysql-virtual-alias-maps.cf If you've put in the data from the previous section, then both commands should return the same result: ''shopkeeper@saruman.biz''. This shows that Postfix will deliver mail to shopkeeper or to webmaster to the mailbox of shopkeeper. ===Finishing up configuration files=== When everything works as planned, then we secure the configuration files against prying eyes. Remember, the configuration files contain the user/password combination which which to access the ''vmail'' SQL database. The ''vmail_admin'' user has only read rights, and passwords in there are encrypted, but nevertheless, this is information we need to protect. Thus: chown root:postfix /etc/postfix/mysql-*.cf chmod u=rw,g=r,o= /etc/postfix/mysql-*.cf This protects all four configuration files since only root can write them, members of group ''postfix'' can read them, and the rest of the world cannot access them at all. ==Configuring mail delivery through Dovecot LDA== E-mails get delivered to the virtual mailboxes by means of a Mail Delivery Agent (MDA). With Postfix, the standard MDA for delivery to virtual mailboxes is called ''virtual'', but we're not going to use that; we're going to use ''[http://wiki.dovecot.org/LDA Dovecot LDA]''. The abbreviation LDA stands for Local Delivery Agent, which of course means more or less the same as MDA. 59c9bf3461ff5dc6dd54b00e1c117a0ae60d414b 1975 1974 2008-11-01T14:28:24Z Saruman! 2 /* Configuring mail delivery through Dovecot LDA */ working on it... wikitext text/x-wiki ==E-mail server setup== What we want to accomplish here is the setup of a mail server with the following properties: * can serve multiple mail domains * can relay mail for other domains to other mail servers * can have one or more mailboxes per domain * users of these mailboxes can be virtual (do not need to have a Linux user account) * can have multiple aliases per mailbox * can forward mail for certain aliases to multiple mailboxes For this type of mail server setup, we owe a great thankyou to [http://workaround.org/articles/ispmail-etch/ Christoph Haas], whose advise has helped us create flexible and reliable mail servers since 2003. ==Preparation== We'll assume that the server currently has no mailserver installed, at least no other than the default ''exim'' mailserver. Furthermore, the server is already fitted with MySQL, and this database is running without problems. The hostname of the server must be set correctly, so that ''hostname -f'' returns a valid DNS name, like ''lighthouse.saruman.biz.''. It might also be an internal name like ''lighthouse.saruman.lan.'' but that will require us to give extra attention to the name under which Postfix will contact its collegues on the Internet. Also, the server can correctly [Networking_section#DNS_resolution_under_Debian | resolve DNS names] like [http://www.debian.org www.debian.org], preferably by running it's own caching DNS server. The server is kept on the correct date and time using NTP, TCP port 25 is open on the server, the ISP will allow connections from Internet to this port, and if there's a firewall running on this server, then it has port 25 open so as to not block incoming e-mail. ==Software installation== As a first step, we use [[APT and aptitude|apt or aptitude]] to make sure that our server is up-to-date. Then we can install the necessary software packages. Under Debian 5.0 "Lenny", the (single) packages is: * ''postfix'', the mail server itself - this includes the "virtual package" postfix-tls, that we want to use to secure connections to Postfix with the TLS protocol At the same time we can - and must - purge the following packages: * exim4 * exim4-base * exim4-daemon-light * exim4-config In ''aptitude'', only press "go" when you've marked all four of these packages "purge", or you cannot install postfix. When installing the postfix package, the Debian installer script will ask you several questions, which you can answer like this: * General type of mail configuration: Internet site * System mail name: the FQDN of the mail server that you've verified in the previous section. Note that the script will try to guess the DNS name, but that might yield a DNS name with a trailing dot. That is technically correct, but the installation script will barf. Remove the trailing dot before hitting &lt;enter>! * Postmaster mail address: the address that all mail should go to that is addressed to "root" and "postmaster". * Domain list: give the list of all domains that the machine can consider itself the FINAL destination for. This should at a minimum include an empty value, "localhost" and the FQDN of the machine itself (no trailing dots!); however, if you're running your own mail domain, you can also add that (e.g. "saruman.biz"). Thus, the list could look like this: saruman.biz, lighthouse.saruman.lan, localhost.saruman.lan, , localhost * Force synchronous updates? We think that's not necessary, but please read the question and decide for yourself * Local networks: something like ''127.0.0.0/8 [::ffff:127.0.0.0]/104 [::1]/128 192.168.67.0/24'' (the default, augmented with your local IP range) * Mailbox size limits: you can give postfix a limit in bytes, but we're going to use one single big mailbox for all users, so we cannot let Postfix guard it. Leave it at 0 (zero) so we don't have a size limit. * Character for local address extension: we leave it at ''+'' * Internet protocols to use: currently we don't have IPv6 support, so there's no sense in letting Postfix try to serve IPv6. We choose ''ipv4'' only. With the above data, the Debian install script for Postfix can do its job and configure Postfix with some basic settings. Now that Postfix is installed, we can install some dependent packages (we could install them in the same run, but if anything goes amiss with the postfix installation, then these packages are going to remain unconfigured as well): * ''postfix-doc'', the accompanying documentation; * ''postfix-mysql'', necessary to have Postfix talk to our MySQL server; * ''postfix-pcre'' to be able to parse regular expressions, which which we can combat spam; * ''dovecot-imapd'' is a daemon that will provide your users with IMAP access to their mail; * ''dovecot-pop3d'' is another daemon, but for the POP3 protocol. ==Virtual Mailman creation== When we're done, we'll need a "system user", a sort of virtual mailman that is the owner of all mailboxes that we're serving. We suggest the name "vmail" for this user. Note: this user does not get his own mailbox (i.e. there's no mailbox at vmail@saruman.biz). To create this user, and his home directory, we can run the following commands: groupadd -g 120 vmail useradd -g vmail -u 120 vmail -d /data/vmail -m -s /bin/false As you see, we've chosen a group ID and user ID of 120 (after confirming that this ID was not taken by another group or user, by checking ''/etc/passwd'' and ''/etc/group''. Furthermore, we've decided to keep the ''vmail'' user's home directory not under ''/home/vmail'', but in a special place where we're going to expect server data to reside - in our server, the ''/data'' directory (which is a RAID-5 array mounted under root). By adding ''-m'', we've actually created the home directory, and adding ''-s /bin/false'' makes totally sure that the user ''vmail'' can never ever log in - even if we've not created a password for this user, so ''vmail'' shouldn't be able to log in anyway. Better safe than sorry. To tell Postfix that this ''vmail'' user is someone special, we run postconf -e virtual_uid_maps=static:120 postconf -e virtual_gid_maps=static:120 That makes postfix understand that all mail for the virtual mail domains must be written to disk with these specified user and group ID's. ==MySQL configuration== ===Database preparation=== We will use the MySQL database to record data on our mail system, and then give our Postfix access to this database so that it can read its configuration from there. For starters, we'll create a MySQL database named "vmail", and a MySQL user named "vmail_admin" that can read all necessary data from that "vmail" database. Then, we create the necessary tables, and a view that links these tables. We do this with the MySQL client ''mysql''. However, we're quite lazy, so we don't create this database by hand (that's error-prone), but by use of a script [[create.vmail.sql]]. To this end, feed the [[create.vmail.sql]] script into the ''mysql'' client like this: mysql -u root -p < create.vmail.sql (This of course assumes you have ''create.vmail.sql'' in your current working directory; if not you can include the path to the file.) Simply give the MySQL root user password, and the script creates the database, the user, the necessary tables, and the view.<br> A note of caution: it is never a good idea to just run scripts without a proper understanding of what it does. Especially with MySQL, it will be advantageous if you understand the SQL commands. Open the script in a text editor, open the [http://dev.mysql.com/doc/refman/5.0/en/ MySQL command reference], and trace back what the script does exactly. ===Inserting data=== Next up, we fill the database with the first sets of values (either test data or the first of our production data). We'll start off with the virtual domains that we're hosting, by running the mysql client and feeding it information like this: mysql -u root -p vmail mysql> INSERT INTO virtual_domains (id, vdomain) VALUES (1, 'saruman.biz'); mysql> INSERT INTO virtual_domains (vdomain) VALUES ('wiki.saruman.biz'); mysql> INSERT INTO virtual_domains (vdomain) VALUES ('shop.saruman.biz'); This has the effect of creating three entries. You can check that everything worked as planned by executing mysql> select * from virtual_domains; Note: only the first entry needs an ''id'' value, because in MySQL we've defined that field as AUTO_INCREMENT. After creating your first virtual domain in the table, you never have to use a statement like the first INSERT again, only statements like the other two. Now the MySQL database has the information needed by Postfix to recognise that you have three virtual mail domains (namely the three domains in the VALUES section) for which it hosts virtual mailboxes. Postfix cannot read this information yet, but that'll be taken care of in the next section. Whle still within the mysql client, we can now create users: mysql> INSERT INTO virtual_users (id, domain_id, user, passwd) VALUES (1, 1, 'jan', MD5('JanSecret')); mysql> INSERT INTO virtual_users (domain_id, user, passwd) VALUES (1, 'mike', MD5('MikeSecret')); mysql> INSERT INTO virtual_users (domain_id, user, passwd) VALUES (3, 'shopkeeper', MD5('ShopSecret')); This has the effect of creating three users "jan" (in domain saruman.biz), "mike" (in domain saruman.biz) and "shopkeeper" (in domain shop.saruman.biz). Again, the ''id'' value is only ever needed in the first statement, because from now on every user addition will auto-increment ''id''. The passwords shown are encrypted with MD5, and put in the ''passwd'' field. Later on, the users will be able to access their mailboxes using this password; we won't tell Postfix anything about them, because it doesn't need the passwords. You can check the content of the ''virtual_users'' table with the right "select" statement, and you can now also see that the view ''view-users'' works: mysql> select * from virtual_users; mysql> select * from view_users; Next up, we're going to add some aliases, which are alternative e-mail addresses for the users; their primary e-mail address can already be seen in the ''view_users'' view, but perhaps you also want mail to "webmaster@shop.saruman.biz" to arrive at one or more mailboxes, e.g. in the mailbox for user "shopkeeper" (within domain "shop.saruman.biz") and this guy's home address ("j.doe@example.com"). Furthermore, we'll define catchall-addresses for all domains, that'll send all mail for which no mailbox can be found to the mailbox of user Mike (for the first two domains) and Webmaster (for shop.saruman.biz; Webmaster himself is an alias yet again, that points to shopkeeper@shop.saruman.biz). To create the catchall, leave out a value for the source address. This creates the empty value for source that will be expanded (using source@domain) to "@domain". mysql> INSERT INTO virtual_aliases (id, domain_id, source, destination) VALUES (1, 2, 'webmaster', 'shopkeeper@shop.saruman.biz'); mysql> INSERT INTO virtual_aliases (domain_id, source, destination) VALUES (2, 'webmaster', 'j.doe@example.com'); mysql> INSERT INTO virtual_aliases (domain_id, destination) VALUES (1, 'mike@saruman.biz'); mysql> INSERT INTO virtual_aliases (domain_id, destination) VALUES (2, 'mike@saruman.biz'); mysql> INSERT INTO virtual_aliases (domain_id, destination) VALUES (3, 'webmaster@saruman.biz'); Again, we don't need to add the ''id'' value any more after the first ever insertion into this table. We can check the result by running a select statement against the ''virtual_aliases'' table and ''view_aliases'' view: mysql> select * from virtual_aliases; mysql> select * from view_aliases; == Postfix configuration for MySQL lookups== Next, we're going to tell Postfix to use the ''vmail'' database, and also how to read the database (Postfix never writes the MySQL database). To this end, we're going to create three configuration files in directory ''/etc/postfix''. We'll start off with one configuration file, with which Postfix can determine if a domain name is among the domain(s) that it's actually hosting mailboxes for. Then we'll create the config file that checks the table that contains all the users that have a virtual mailbox, and finally we create the lookup for the table with all the aliases. ===Virtual mail domains lookup=== Create file ''/etc/postfix/mysql-virtual-domains.cf'' with the following content: user = vmail_admin password = SuperSecret hosts = 127.0.0.1 dbname = vmail query = SELECT 1 FROM virtual_domains WHERE vdomain='%s' Next, we tell postfix to check this configuration file when it needs to check "virtual_mailbox_domains": postconf -e virtual_mailbox_domains=mysql:/etc/postfix/mysql-virtual-domains.cf Use of this configuration file in postfix has the effect of returning "yes" when checking our database for the domain part of an email address. Naturally, this configuration file has to be fitted with the actual ''vmail_admin'' password rather than our example "SuperSecret". === Virtual mail user lookup=== Create the file ''/etc/postfix/mysql-virtual-mailbox-maps.cf'' with the following content: user = vmail_admin password = SuperSecret hosts = 127.0.0.1 dbname = vmail query = SELECT 1 FROM view_users WHERE email='%s' Next, we tell Postfix that this mapping file is supposed to be used for the ''virtual_mailbox_maps'' mapping: postconf -e virtual_mailbox_maps=mysql:/etc/postfix/mysql-virtual-mailbox-maps.cf The lookup of virtual mailboxes should work with the data we've put into the database previously. i.e. postmap -q jan@saruman.biz mysql:/etc/postfix/mysql-virtual-mailbox-maps.cf should return a '''1''' to acknowledge that "jan@saruman.biz" is indeed a virtual mailbox in our Postfix configuration. === Virtual alias lookup=== Create another cf file at ''/etc/postfix/mysql-virtual-alias-maps.cf'': user = vmail_admin password = SuperSecret hosts = 127.0.0.1 dbname = vmail query = SELECT destination FROM view_aliases WHERE email='%s' And create yet another cf file at ''/etc/postfix/mysql-email2email.cf'': user = vmail_admin password = SuperSecret hosts = 127.0.0.1 dbname = vmail query = SELECT email FROM view_users WHERE email='%s' Again, we tell Postfix that this mapping file is supposed to be used for the ''virtual_alias_maps'' mapping: postconf -e virtual_alias_maps=mysql:/etc/postfix/mysql-virtual-alias-maps.cf,mysql:/etc/postfix/mysql-email2email.cf The lookup of virtual aliases should now work as designed: postmap -q shopkeeper@shop.saruman.biz mysql:/etc/postfix/mysql-virtual-alias-maps.cf postmap -q webmaster@shop.saruman.biz mysql:/etc/postfix/mysql-virtual-alias-maps.cf If you've put in the data from the previous section, then both commands should return the same result: ''shopkeeper@saruman.biz''. This shows that Postfix will deliver mail to shopkeeper or to webmaster to the mailbox of shopkeeper. ===Finishing up configuration files=== When everything works as planned, then we secure the configuration files against prying eyes. Remember, the configuration files contain the user/password combination which which to access the ''vmail'' SQL database. The ''vmail_admin'' user has only read rights, and passwords in there are encrypted, but nevertheless, this is information we need to protect. Thus: chown root:postfix /etc/postfix/mysql-*.cf chmod u=rw,g=r,o= /etc/postfix/mysql-*.cf This protects all four configuration files since only root can write them, members of group ''postfix'' can read them, and the rest of the world cannot access them at all. ==Configuring mail delivery through Dovecot LDA== E-mails get delivered to the virtual mailboxes by means of a Mail Delivery Agent (MDA). With Postfix, the standard MDA for delivery to virtual mailboxes is called ''virtual'', but we're not going to use that; we're going to use ''[http://wiki.dovecot.org/LDA Dovecot LDA]'', which is a program called ''deliver''. By the way, the abbreviation LDA stands for Local Delivery Agent, which of course means more or less the same as MDA. To make Postfix use Dovecot LDA, we add the following line to ''/etc/postfix/master.cf'': dovecot unix - n n - - pipe flags=DRhu user=vmail:vmail argv=/usr/lib/dovecot/deliver -d ${recipient} This declares the service "dovecot" to mean using the program ''/usr/lib/dovecot/deliver'' with the right parameters. If we now let Postfix reload its files, it'll learn about this new service. Subsequently we can instruct Postfix to start using it, by declaring service "dovecot" to be the virtual transport of choice, and specifying one Dovecot-specific variable: postfix reload postconf -e virtual_transport=dovecot postconf -e dovecot_destination_recipient_limit=1 Now to configure Dovecot itself: open ''/etc/dovecot/dovecot.conf'' with your favourite editor [[vim]]; first make sure the ''protocols ='' line reads protocols = imap imaps pop3 pop3s (which it should by default). The second setting is quite crucial. By default, the location of the mail directories is found automatically by Dovecot, but here that won't work. Find the line that reads ''#maildir_location ='', and change it to mail_location = maildir:/data/vmail/%d/%n/Maildir This will look for mail in directory ''/data/vmail/'''DOMAIN'''/'''USER'''/Maildir'', and expect this directory to be in "maildir" format. Next look for a section called "auth default". First define the allowed authentication mechanisms: mechanisms = plain login Then inside that same section you need to uncomment: passdb sql { args = /etc/dovecot/dovecot-sql.conf } which tells Dovecot that the passwords are stored in an SQL database and: userdb static { args = uid=120 gid=120 home=/data/vmail/%d/%n allow_all_users=yes } to tell Dovecot where the mailboxes are located. This is similar to the ''mail_location'' setting. 4812703deab81817c5d3e52fd7471f5d8d3eb71c 1976 1975 2008-11-01T16:38:54Z Saruman! 2 /* Configuring mail delivery through Dovecot LDA */ finised wikitext text/x-wiki ==E-mail server setup== What we want to accomplish here is the setup of a mail server with the following properties: * can serve multiple mail domains * can relay mail for other domains to other mail servers * can have one or more mailboxes per domain * users of these mailboxes can be virtual (do not need to have a Linux user account) * can have multiple aliases per mailbox * can forward mail for certain aliases to multiple mailboxes For this type of mail server setup, we owe a great thankyou to [http://workaround.org/articles/ispmail-etch/ Christoph Haas], whose advise has helped us create flexible and reliable mail servers since 2003. ==Preparation== We'll assume that the server currently has no mailserver installed, at least no other than the default ''exim'' mailserver. Furthermore, the server is already fitted with MySQL, and this database is running without problems. The hostname of the server must be set correctly, so that ''hostname -f'' returns a valid DNS name, like ''lighthouse.saruman.biz.''. It might also be an internal name like ''lighthouse.saruman.lan.'' but that will require us to give extra attention to the name under which Postfix will contact its collegues on the Internet. Also, the server can correctly [Networking_section#DNS_resolution_under_Debian | resolve DNS names] like [http://www.debian.org www.debian.org], preferably by running it's own caching DNS server. The server is kept on the correct date and time using NTP, TCP port 25 is open on the server, the ISP will allow connections from Internet to this port, and if there's a firewall running on this server, then it has port 25 open so as to not block incoming e-mail. ==Software installation== As a first step, we use [[APT and aptitude|apt or aptitude]] to make sure that our server is up-to-date. Then we can install the necessary software packages. Under Debian 5.0 "Lenny", the (single) packages is: * ''postfix'', the mail server itself - this includes the "virtual package" postfix-tls, that we want to use to secure connections to Postfix with the TLS protocol At the same time we can - and must - purge the following packages: * exim4 * exim4-base * exim4-daemon-light * exim4-config In ''aptitude'', only press "go" when you've marked all four of these packages "purge", or you cannot install postfix. When installing the postfix package, the Debian installer script will ask you several questions, which you can answer like this: * General type of mail configuration: Internet site * System mail name: the FQDN of the mail server that you've verified in the previous section. Note that the script will try to guess the DNS name, but that might yield a DNS name with a trailing dot. That is technically correct, but the installation script will barf. Remove the trailing dot before hitting &lt;enter>! * Postmaster mail address: the address that all mail should go to that is addressed to "root" and "postmaster". * Domain list: give the list of all domains that the machine can consider itself the FINAL destination for. This should at a minimum include an empty value, "localhost" and the FQDN of the machine itself (no trailing dots!); however, if you're running your own mail domain, you can also add that (e.g. "saruman.biz"). Thus, the list could look like this: saruman.biz, lighthouse.saruman.lan, localhost.saruman.lan, , localhost * Force synchronous updates? We think that's not necessary, but please read the question and decide for yourself * Local networks: something like ''127.0.0.0/8 [::ffff:127.0.0.0]/104 [::1]/128 192.168.67.0/24'' (the default, augmented with your local IP range) * Mailbox size limits: you can give postfix a limit in bytes, but we're going to use one single big mailbox for all users, so we cannot let Postfix guard it. Leave it at 0 (zero) so we don't have a size limit. * Character for local address extension: we leave it at ''+'' * Internet protocols to use: currently we don't have IPv6 support, so there's no sense in letting Postfix try to serve IPv6. We choose ''ipv4'' only. With the above data, the Debian install script for Postfix can do its job and configure Postfix with some basic settings. Now that Postfix is installed, we can install some dependent packages (we could install them in the same run, but if anything goes amiss with the postfix installation, then these packages are going to remain unconfigured as well): * ''postfix-doc'', the accompanying documentation; * ''postfix-mysql'', necessary to have Postfix talk to our MySQL server; * ''postfix-pcre'' to be able to parse regular expressions, which which we can combat spam; * ''dovecot-imapd'' is a daemon that will provide your users with IMAP access to their mail; * ''dovecot-pop3d'' is another daemon, but for the POP3 protocol. ==Virtual Mailman creation== When we're done, we'll need a "system user", a sort of virtual mailman that is the owner of all mailboxes that we're serving. We suggest the name "vmail" for this user. Note: this user does not get his own mailbox (i.e. there's no mailbox at vmail@saruman.biz). To create this user, and his home directory, we can run the following commands: groupadd -g 120 vmail useradd -g vmail -u 120 vmail -d /data/vmail -m -s /bin/false As you see, we've chosen a group ID and user ID of 120 (after confirming that this ID was not taken by another group or user, by checking ''/etc/passwd'' and ''/etc/group''. Furthermore, we've decided to keep the ''vmail'' user's home directory not under ''/home/vmail'', but in a special place where we're going to expect server data to reside - in our server, the ''/data'' directory (which is a RAID-5 array mounted under root). By adding ''-m'', we've actually created the home directory, and adding ''-s /bin/false'' makes totally sure that the user ''vmail'' can never ever log in - even if we've not created a password for this user, so ''vmail'' shouldn't be able to log in anyway. Better safe than sorry. To tell Postfix that this ''vmail'' user is someone special, we run postconf -e virtual_uid_maps=static:120 postconf -e virtual_gid_maps=static:120 That makes postfix understand that all mail for the virtual mail domains must be written to disk with these specified user and group ID's. ==MySQL configuration== ===Database preparation=== We will use the MySQL database to record data on our mail system, and then give our Postfix access to this database so that it can read its configuration from there. For starters, we'll create a MySQL database named "vmail", and a MySQL user named "vmail_admin" that can read all necessary data from that "vmail" database. Then, we create the necessary tables, and a view that links these tables. We do this with the MySQL client ''mysql''. However, we're quite lazy, so we don't create this database by hand (that's error-prone), but by use of a script [[create.vmail.sql]]. To this end, feed the [[create.vmail.sql]] script into the ''mysql'' client like this: mysql -u root -p < create.vmail.sql (This of course assumes you have ''create.vmail.sql'' in your current working directory; if not you can include the path to the file.) Simply give the MySQL root user password, and the script creates the database, the user, the necessary tables, and the view.<br> A note of caution: it is never a good idea to just run scripts without a proper understanding of what it does. Especially with MySQL, it will be advantageous if you understand the SQL commands. Open the script in a text editor, open the [http://dev.mysql.com/doc/refman/5.0/en/ MySQL command reference], and trace back what the script does exactly. ===Inserting data=== Next up, we fill the database with the first sets of values (either test data or the first of our production data). We'll start off with the virtual domains that we're hosting, by running the mysql client and feeding it information like this: mysql -u root -p vmail mysql> INSERT INTO virtual_domains (id, vdomain) VALUES (1, 'saruman.biz'); mysql> INSERT INTO virtual_domains (vdomain) VALUES ('wiki.saruman.biz'); mysql> INSERT INTO virtual_domains (vdomain) VALUES ('shop.saruman.biz'); This has the effect of creating three entries. You can check that everything worked as planned by executing mysql> select * from virtual_domains; Note: only the first entry needs an ''id'' value, because in MySQL we've defined that field as AUTO_INCREMENT. After creating your first virtual domain in the table, you never have to use a statement like the first INSERT again, only statements like the other two. Now the MySQL database has the information needed by Postfix to recognise that you have three virtual mail domains (namely the three domains in the VALUES section) for which it hosts virtual mailboxes. Postfix cannot read this information yet, but that'll be taken care of in the next section. Whle still within the mysql client, we can now create users: mysql> INSERT INTO virtual_users (id, domain_id, user, passwd) VALUES (1, 1, 'jan', MD5('JanSecret')); mysql> INSERT INTO virtual_users (domain_id, user, passwd) VALUES (1, 'mike', MD5('MikeSecret')); mysql> INSERT INTO virtual_users (domain_id, user, passwd) VALUES (3, 'shopkeeper', MD5('ShopSecret')); This has the effect of creating three users "jan" (in domain saruman.biz), "mike" (in domain saruman.biz) and "shopkeeper" (in domain shop.saruman.biz). Again, the ''id'' value is only ever needed in the first statement, because from now on every user addition will auto-increment ''id''. The passwords shown are encrypted with MD5, and put in the ''passwd'' field. Later on, the users will be able to access their mailboxes using this password; we won't tell Postfix anything about them, because it doesn't need the passwords. You can check the content of the ''virtual_users'' table with the right "select" statement, and you can now also see that the view ''view-users'' works: mysql> select * from virtual_users; mysql> select * from view_users; Next up, we're going to add some aliases, which are alternative e-mail addresses for the users; their primary e-mail address can already be seen in the ''view_users'' view, but perhaps you also want mail to "webmaster@shop.saruman.biz" to arrive at one or more mailboxes, e.g. in the mailbox for user "shopkeeper" (within domain "shop.saruman.biz") and this guy's home address ("j.doe@example.com"). Furthermore, we'll define catchall-addresses for all domains, that'll send all mail for which no mailbox can be found to the mailbox of user Mike (for the first two domains) and Webmaster (for shop.saruman.biz; Webmaster himself is an alias yet again, that points to shopkeeper@shop.saruman.biz). To create the catchall, leave out a value for the source address. This creates the empty value for source that will be expanded (using source@domain) to "@domain". mysql> INSERT INTO virtual_aliases (id, domain_id, source, destination) VALUES (1, 2, 'webmaster', 'shopkeeper@shop.saruman.biz'); mysql> INSERT INTO virtual_aliases (domain_id, source, destination) VALUES (2, 'webmaster', 'j.doe@example.com'); mysql> INSERT INTO virtual_aliases (domain_id, destination) VALUES (1, 'mike@saruman.biz'); mysql> INSERT INTO virtual_aliases (domain_id, destination) VALUES (2, 'mike@saruman.biz'); mysql> INSERT INTO virtual_aliases (domain_id, destination) VALUES (3, 'webmaster@saruman.biz'); Again, we don't need to add the ''id'' value any more after the first ever insertion into this table. We can check the result by running a select statement against the ''virtual_aliases'' table and ''view_aliases'' view: mysql> select * from virtual_aliases; mysql> select * from view_aliases; == Postfix configuration for MySQL lookups== Next, we're going to tell Postfix to use the ''vmail'' database, and also how to read the database (Postfix never writes the MySQL database). To this end, we're going to create three configuration files in directory ''/etc/postfix''. We'll start off with one configuration file, with which Postfix can determine if a domain name is among the domain(s) that it's actually hosting mailboxes for. Then we'll create the config file that checks the table that contains all the users that have a virtual mailbox, and finally we create the lookup for the table with all the aliases. ===Virtual mail domains lookup=== Create file ''/etc/postfix/mysql-virtual-domains.cf'' with the following content: user = vmail_admin password = SuperSecret hosts = 127.0.0.1 dbname = vmail query = SELECT 1 FROM virtual_domains WHERE vdomain='%s' Next, we tell postfix to check this configuration file when it needs to check "virtual_mailbox_domains": postconf -e virtual_mailbox_domains=mysql:/etc/postfix/mysql-virtual-domains.cf Use of this configuration file in postfix has the effect of returning "yes" when checking our database for the domain part of an email address. Naturally, this configuration file has to be fitted with the actual ''vmail_admin'' password rather than our example "SuperSecret". === Virtual mail user lookup=== Create the file ''/etc/postfix/mysql-virtual-mailbox-maps.cf'' with the following content: user = vmail_admin password = SuperSecret hosts = 127.0.0.1 dbname = vmail query = SELECT 1 FROM view_users WHERE email='%s' Next, we tell Postfix that this mapping file is supposed to be used for the ''virtual_mailbox_maps'' mapping: postconf -e virtual_mailbox_maps=mysql:/etc/postfix/mysql-virtual-mailbox-maps.cf The lookup of virtual mailboxes should work with the data we've put into the database previously. i.e. postmap -q jan@saruman.biz mysql:/etc/postfix/mysql-virtual-mailbox-maps.cf should return a '''1''' to acknowledge that "jan@saruman.biz" is indeed a virtual mailbox in our Postfix configuration. === Virtual alias lookup=== Create another cf file at ''/etc/postfix/mysql-virtual-alias-maps.cf'': user = vmail_admin password = SuperSecret hosts = 127.0.0.1 dbname = vmail query = SELECT destination FROM view_aliases WHERE email='%s' And create yet another cf file at ''/etc/postfix/mysql-email2email.cf'': user = vmail_admin password = SuperSecret hosts = 127.0.0.1 dbname = vmail query = SELECT email FROM view_users WHERE email='%s' Again, we tell Postfix that this mapping file is supposed to be used for the ''virtual_alias_maps'' mapping: postconf -e virtual_alias_maps=mysql:/etc/postfix/mysql-virtual-alias-maps.cf,mysql:/etc/postfix/mysql-email2email.cf The lookup of virtual aliases should now work as designed: postmap -q shopkeeper@shop.saruman.biz mysql:/etc/postfix/mysql-virtual-alias-maps.cf postmap -q webmaster@shop.saruman.biz mysql:/etc/postfix/mysql-virtual-alias-maps.cf If you've put in the data from the previous section, then both commands should return the same result: ''shopkeeper@saruman.biz''. This shows that Postfix will deliver mail to shopkeeper or to webmaster to the mailbox of shopkeeper. ===Finishing up configuration files=== When everything works as planned, then we secure the configuration files against prying eyes. Remember, the configuration files contain the user/password combination which which to access the ''vmail'' SQL database. The ''vmail_admin'' user has only read rights, and passwords in there are encrypted, but nevertheless, this is information we need to protect. Thus: chown root:postfix /etc/postfix/mysql-*.cf chmod u=rw,g=r,o= /etc/postfix/mysql-*.cf This protects all four configuration files since only root can write them, members of group ''postfix'' can read them, and the rest of the world cannot access them at all. ==Configuring mail delivery through Dovecot LDA== E-mails get delivered to the virtual mailboxes by means of a Mail Delivery Agent (MDA). With Postfix, the standard MDA for delivery to virtual mailboxes is called ''virtual'', but we're not going to use that; we're going to use ''[http://wiki.dovecot.org/LDA Dovecot LDA]'', which is a program called ''deliver''. By the way, the abbreviation LDA stands for Local Delivery Agent, which of course means more or less the same as MDA. To make Postfix use Dovecot LDA, we add the following line to ''/etc/postfix/master.cf'': dovecot unix - n n - - pipe flags=DRhu user=vmail:vmail argv=/usr/lib/dovecot/deliver -d ${recipient} This declares the service "dovecot" to mean using the program ''/usr/lib/dovecot/deliver'' with the right parameters. If we now let Postfix reload its files, it'll learn about this new service. Subsequently we can instruct Postfix to start using it, by declaring service "dovecot" to be the virtual transport of choice, and specifying one Dovecot-specific variable: postfix reload postconf -e virtual_transport=dovecot postconf -e dovecot_destination_recipient_limit=1 Now to configure Dovecot itself: open ''/etc/dovecot/dovecot.conf'' with your favourite editor [[vim]]; first make sure the ''protocols ='' line reads protocols = imap imaps pop3 pop3s (which it should by default). The second setting is quite crucial. By default, the location of the mail directories is found automatically by Dovecot, but here that won't work. Find the line that reads ''#maildir_location ='', and change it to mail_location = maildir:/data/vmail/%d/%n/Maildir This will look for mail in directory ''/data/vmail/'''DOMAIN'''/'''USER'''/Maildir'', and expect this directory to be in "maildir" format. Next look for a section called "auth default". First define the allowed authentication mechanisms: mechanisms = plain login Then inside that same section you need to uncomment: passdb sql { args = /etc/dovecot/dovecot-sql.conf } which tells Dovecot that the passwords are stored in an SQL database (it's obvious that we'll now have to create this conf-file) and: userdb static { args = uid=120 gid=120 home=/data/vmail/%d/%n allow_all_users=yes } to tell Dovecot where the mailboxes are located. This is similar to the ''mail_location'' setting. Next task: comment out the section ''passdb pam'', so that Dovecot doesn't accidentally try to service local users as well. Next up: tell Dovecot to handle IMAP the same as previous versions of this virtual mailserver have: namespace private { separator = . prefix = INBOX. inbox = yes } (this section is not necessary if you're building this server from scratch). You'll also want to comment out the ''passdb pam'' sections, since we're not hosting mail for local users. Next up, we'll edit the section ''socket listen'' so that Dovecot can access the user database (master section), and our Postfix mailserver can access Dovecot (client section): socket listen { master { path = /var/run/dovecot/auth-master mode = 0600 user = vmail } client { path = /var/spool/postfix/private/auth mode = 0660 user = postfix group = postfix } } Finally, the protocol section, where we specify log files, an address to put in mails when we send out nondelivery reports, and a place to store scripts: protocol lda { log_path = /var/log/appslog/mail/dovecot-deliver.log auth_socket_path = /var/run/dovecot/auth-master postmaster_address = postmaster@saruman.biz mail_plugins = cmusieve global_script_path = /data/vmail/globalsieverc } Now that we've finished the Dovecot configuration file, we need to create a fitting MySQL configuration file for Dovecot. The file is ''/etc/dovecot/dovecot-sql.conf'', and its contents are driver = mysql connect = host=127.0.0.1 dbname=vmail user=vmail_admin password=SuperSecret default_pass_scheme = PLAIN-MD5 password_query = SELECT email as user, password FROM view_users WHERE email='%u'; When you've created this file (as root), change the attributes for safety, and then restart Dovecot to start using the new configuration: chmod u=rw,g=,o= /etc/dovecot/dovecot-sql.conf /etc/init.d/dovecot restart c80c2b4ab641b53caf859f3d58e767199aaccd6f 1977 1976 2008-11-01T18:41:31Z Saruman! 2 /* Configuring mail delivery through Dovecot LDA */ took out last errors wikitext text/x-wiki ==E-mail server setup== What we want to accomplish here is the setup of a mail server with the following properties: * can serve multiple mail domains * can relay mail for other domains to other mail servers * can have one or more mailboxes per domain * users of these mailboxes can be virtual (do not need to have a Linux user account) * can have multiple aliases per mailbox * can forward mail for certain aliases to multiple mailboxes For this type of mail server setup, we owe a great thankyou to [http://workaround.org/articles/ispmail-etch/ Christoph Haas], whose advise has helped us create flexible and reliable mail servers since 2003. ==Preparation== We'll assume that the server currently has no mailserver installed, at least no other than the default ''exim'' mailserver. Furthermore, the server is already fitted with MySQL, and this database is running without problems. The hostname of the server must be set correctly, so that ''hostname -f'' returns a valid DNS name, like ''lighthouse.saruman.biz.''. It might also be an internal name like ''lighthouse.saruman.lan.'' but that will require us to give extra attention to the name under which Postfix will contact its collegues on the Internet. Also, the server can correctly [Networking_section#DNS_resolution_under_Debian | resolve DNS names] like [http://www.debian.org www.debian.org], preferably by running it's own caching DNS server. The server is kept on the correct date and time using NTP, TCP port 25 is open on the server, the ISP will allow connections from Internet to this port, and if there's a firewall running on this server, then it has port 25 open so as to not block incoming e-mail. ==Software installation== As a first step, we use [[APT and aptitude|apt or aptitude]] to make sure that our server is up-to-date. Then we can install the necessary software packages. Under Debian 5.0 "Lenny", the (single) packages is: * ''postfix'', the mail server itself - this includes the "virtual package" postfix-tls, that we want to use to secure connections to Postfix with the TLS protocol At the same time we can - and must - purge the following packages: * exim4 * exim4-base * exim4-daemon-light * exim4-config In ''aptitude'', only press "go" when you've marked all four of these packages "purge", or you cannot install postfix. When installing the postfix package, the Debian installer script will ask you several questions, which you can answer like this: * General type of mail configuration: Internet site * System mail name: the FQDN of the mail server that you've verified in the previous section. Note that the script will try to guess the DNS name, but that might yield a DNS name with a trailing dot. That is technically correct, but the installation script will barf. Remove the trailing dot before hitting &lt;enter>! * Postmaster mail address: the address that all mail should go to that is addressed to "root" and "postmaster". * Domain list: give the list of all domains that the machine can consider itself the FINAL destination for. This should at a minimum include an empty value, "localhost" and the FQDN of the machine itself (no trailing dots!); however, if you're running your own mail domain, you can also add that (e.g. "saruman.biz"). Thus, the list could look like this: saruman.biz, lighthouse.saruman.lan, localhost.saruman.lan, , localhost * Force synchronous updates? We think that's not necessary, but please read the question and decide for yourself * Local networks: something like ''127.0.0.0/8 [::ffff:127.0.0.0]/104 [::1]/128 192.168.67.0/24'' (the default, augmented with your local IP range) * Mailbox size limits: you can give postfix a limit in bytes, but we're going to use one single big mailbox for all users, so we cannot let Postfix guard it. Leave it at 0 (zero) so we don't have a size limit. * Character for local address extension: we leave it at ''+'' * Internet protocols to use: currently we don't have IPv6 support, so there's no sense in letting Postfix try to serve IPv6. We choose ''ipv4'' only. With the above data, the Debian install script for Postfix can do its job and configure Postfix with some basic settings. Now that Postfix is installed, we can install some dependent packages (we could install them in the same run, but if anything goes amiss with the postfix installation, then these packages are going to remain unconfigured as well): * ''postfix-doc'', the accompanying documentation; * ''postfix-mysql'', necessary to have Postfix talk to our MySQL server; * ''postfix-pcre'' to be able to parse regular expressions, which which we can combat spam; * ''dovecot-imapd'' is a daemon that will provide your users with IMAP access to their mail; * ''dovecot-pop3d'' is another daemon, but for the POP3 protocol. ==Virtual Mailman creation== When we're done, we'll need a "system user", a sort of virtual mailman that is the owner of all mailboxes that we're serving. We suggest the name "vmail" for this user. Note: this user does not get his own mailbox (i.e. there's no mailbox at vmail@saruman.biz). To create this user, and his home directory, we can run the following commands: groupadd -g 120 vmail useradd -g vmail -u 120 vmail -d /data/vmail -m -s /bin/false As you see, we've chosen a group ID and user ID of 120 (after confirming that this ID was not taken by another group or user, by checking ''/etc/passwd'' and ''/etc/group''. Furthermore, we've decided to keep the ''vmail'' user's home directory not under ''/home/vmail'', but in a special place where we're going to expect server data to reside - in our server, the ''/data'' directory (which is a RAID-5 array mounted under root). By adding ''-m'', we've actually created the home directory, and adding ''-s /bin/false'' makes totally sure that the user ''vmail'' can never ever log in - even if we've not created a password for this user, so ''vmail'' shouldn't be able to log in anyway. Better safe than sorry. To tell Postfix that this ''vmail'' user is someone special, we run postconf -e virtual_uid_maps=static:120 postconf -e virtual_gid_maps=static:120 That makes postfix understand that all mail for the virtual mail domains must be written to disk with these specified user and group ID's. ==MySQL configuration== ===Database preparation=== We will use the MySQL database to record data on our mail system, and then give our Postfix access to this database so that it can read its configuration from there. For starters, we'll create a MySQL database named "vmail", and a MySQL user named "vmail_admin" that can read all necessary data from that "vmail" database. Then, we create the necessary tables, and a view that links these tables. We do this with the MySQL client ''mysql''. However, we're quite lazy, so we don't create this database by hand (that's error-prone), but by use of a script [[create.vmail.sql]]. To this end, feed the [[create.vmail.sql]] script into the ''mysql'' client like this: mysql -u root -p < create.vmail.sql (This of course assumes you have ''create.vmail.sql'' in your current working directory; if not you can include the path to the file.) Simply give the MySQL root user password, and the script creates the database, the user, the necessary tables, and the view.<br> A note of caution: it is never a good idea to just run scripts without a proper understanding of what it does. Especially with MySQL, it will be advantageous if you understand the SQL commands. Open the script in a text editor, open the [http://dev.mysql.com/doc/refman/5.0/en/ MySQL command reference], and trace back what the script does exactly. ===Inserting data=== Next up, we fill the database with the first sets of values (either test data or the first of our production data). We'll start off with the virtual domains that we're hosting, by running the mysql client and feeding it information like this: mysql -u root -p vmail mysql> INSERT INTO virtual_domains (id, vdomain) VALUES (1, 'saruman.biz'); mysql> INSERT INTO virtual_domains (vdomain) VALUES ('wiki.saruman.biz'); mysql> INSERT INTO virtual_domains (vdomain) VALUES ('shop.saruman.biz'); This has the effect of creating three entries. You can check that everything worked as planned by executing mysql> select * from virtual_domains; Note: only the first entry needs an ''id'' value, because in MySQL we've defined that field as AUTO_INCREMENT. After creating your first virtual domain in the table, you never have to use a statement like the first INSERT again, only statements like the other two. Now the MySQL database has the information needed by Postfix to recognise that you have three virtual mail domains (namely the three domains in the VALUES section) for which it hosts virtual mailboxes. Postfix cannot read this information yet, but that'll be taken care of in the next section. Whle still within the mysql client, we can now create users: mysql> INSERT INTO virtual_users (id, domain_id, user, passwd) VALUES (1, 1, 'jan', MD5('JanSecret')); mysql> INSERT INTO virtual_users (domain_id, user, passwd) VALUES (1, 'mike', MD5('MikeSecret')); mysql> INSERT INTO virtual_users (domain_id, user, passwd) VALUES (3, 'shopkeeper', MD5('ShopSecret')); This has the effect of creating three users "jan" (in domain saruman.biz), "mike" (in domain saruman.biz) and "shopkeeper" (in domain shop.saruman.biz). Again, the ''id'' value is only ever needed in the first statement, because from now on every user addition will auto-increment ''id''. The passwords shown are encrypted with MD5, and put in the ''passwd'' field. Later on, the users will be able to access their mailboxes using this password; we won't tell Postfix anything about them, because it doesn't need the passwords. You can check the content of the ''virtual_users'' table with the right "select" statement, and you can now also see that the view ''view-users'' works: mysql> select * from virtual_users; mysql> select * from view_users; Next up, we're going to add some aliases, which are alternative e-mail addresses for the users; their primary e-mail address can already be seen in the ''view_users'' view, but perhaps you also want mail to "webmaster@shop.saruman.biz" to arrive at one or more mailboxes, e.g. in the mailbox for user "shopkeeper" (within domain "shop.saruman.biz") and this guy's home address ("j.doe@example.com"). Furthermore, we'll define catchall-addresses for all domains, that'll send all mail for which no mailbox can be found to the mailbox of user Mike (for the first two domains) and Webmaster (for shop.saruman.biz; Webmaster himself is an alias yet again, that points to shopkeeper@shop.saruman.biz). To create the catchall, leave out a value for the source address. This creates the empty value for source that will be expanded (using source@domain) to "@domain". mysql> INSERT INTO virtual_aliases (id, domain_id, source, destination) VALUES (1, 2, 'webmaster', 'shopkeeper@shop.saruman.biz'); mysql> INSERT INTO virtual_aliases (domain_id, source, destination) VALUES (2, 'webmaster', 'j.doe@example.com'); mysql> INSERT INTO virtual_aliases (domain_id, destination) VALUES (1, 'mike@saruman.biz'); mysql> INSERT INTO virtual_aliases (domain_id, destination) VALUES (2, 'mike@saruman.biz'); mysql> INSERT INTO virtual_aliases (domain_id, destination) VALUES (3, 'webmaster@saruman.biz'); Again, we don't need to add the ''id'' value any more after the first ever insertion into this table. We can check the result by running a select statement against the ''virtual_aliases'' table and ''view_aliases'' view: mysql> select * from virtual_aliases; mysql> select * from view_aliases; == Postfix configuration for MySQL lookups== Next, we're going to tell Postfix to use the ''vmail'' database, and also how to read the database (Postfix never writes the MySQL database). To this end, we're going to create three configuration files in directory ''/etc/postfix''. We'll start off with one configuration file, with which Postfix can determine if a domain name is among the domain(s) that it's actually hosting mailboxes for. Then we'll create the config file that checks the table that contains all the users that have a virtual mailbox, and finally we create the lookup for the table with all the aliases. ===Virtual mail domains lookup=== Create file ''/etc/postfix/mysql-virtual-domains.cf'' with the following content: user = vmail_admin password = SuperSecret hosts = 127.0.0.1 dbname = vmail query = SELECT 1 FROM virtual_domains WHERE vdomain='%s' Next, we tell postfix to check this configuration file when it needs to check "virtual_mailbox_domains": postconf -e virtual_mailbox_domains=mysql:/etc/postfix/mysql-virtual-domains.cf Use of this configuration file in postfix has the effect of returning "yes" when checking our database for the domain part of an email address. Naturally, this configuration file has to be fitted with the actual ''vmail_admin'' password rather than our example "SuperSecret". === Virtual mail user lookup=== Create the file ''/etc/postfix/mysql-virtual-mailbox-maps.cf'' with the following content: user = vmail_admin password = SuperSecret hosts = 127.0.0.1 dbname = vmail query = SELECT 1 FROM view_users WHERE email='%s' Next, we tell Postfix that this mapping file is supposed to be used for the ''virtual_mailbox_maps'' mapping: postconf -e virtual_mailbox_maps=mysql:/etc/postfix/mysql-virtual-mailbox-maps.cf The lookup of virtual mailboxes should work with the data we've put into the database previously. i.e. postmap -q jan@saruman.biz mysql:/etc/postfix/mysql-virtual-mailbox-maps.cf should return a '''1''' to acknowledge that "jan@saruman.biz" is indeed a virtual mailbox in our Postfix configuration. === Virtual alias lookup=== Create another cf file at ''/etc/postfix/mysql-virtual-alias-maps.cf'': user = vmail_admin password = SuperSecret hosts = 127.0.0.1 dbname = vmail query = SELECT destination FROM view_aliases WHERE email='%s' And create yet another cf file at ''/etc/postfix/mysql-email2email.cf'': user = vmail_admin password = SuperSecret hosts = 127.0.0.1 dbname = vmail query = SELECT email FROM view_users WHERE email='%s' Again, we tell Postfix that this mapping file is supposed to be used for the ''virtual_alias_maps'' mapping: postconf -e virtual_alias_maps=mysql:/etc/postfix/mysql-virtual-alias-maps.cf,mysql:/etc/postfix/mysql-email2email.cf The lookup of virtual aliases should now work as designed: postmap -q shopkeeper@shop.saruman.biz mysql:/etc/postfix/mysql-virtual-alias-maps.cf postmap -q webmaster@shop.saruman.biz mysql:/etc/postfix/mysql-virtual-alias-maps.cf If you've put in the data from the previous section, then both commands should return the same result: ''shopkeeper@saruman.biz''. This shows that Postfix will deliver mail to shopkeeper or to webmaster to the mailbox of shopkeeper. ===Finishing up configuration files=== When everything works as planned, then we secure the configuration files against prying eyes. Remember, the configuration files contain the user/password combination which which to access the ''vmail'' SQL database. The ''vmail_admin'' user has only read rights, and passwords in there are encrypted, but nevertheless, this is information we need to protect. Thus: chown root:postfix /etc/postfix/mysql-*.cf chmod u=rw,g=r,o= /etc/postfix/mysql-*.cf This protects all four configuration files since only root can write them, members of group ''postfix'' can read them, and the rest of the world cannot access them at all. ==Configuring mail delivery through Dovecot LDA== E-mails get delivered to the virtual mailboxes by means of a Mail Delivery Agent (MDA). With Postfix, the standard MDA for delivery to virtual mailboxes is called ''virtual'', but we're not going to use that; we're going to use ''[http://wiki.dovecot.org/LDA Dovecot LDA]'', which is a program called ''deliver''. By the way, the abbreviation LDA stands for Local Delivery Agent, which of course means more or less the same as MDA. To make Postfix use Dovecot LDA, we add the following line to ''/etc/postfix/master.cf'': dovecot unix - n n - - pipe flags=DRhu user=vmail:vmail argv=/usr/lib/dovecot/deliver -d ${recipient} This declares the service "dovecot" to mean using the program ''/usr/lib/dovecot/deliver'' with the right parameters. If we now let Postfix reload its files, it'll learn about this new service. Subsequently we can instruct Postfix to start using it, by declaring service "dovecot" to be the virtual transport of choice, and specifying one Dovecot-specific variable: postfix reload postconf -e virtual_transport=dovecot postconf -e dovecot_destination_recipient_limit=1 Now to configure Dovecot itself: open ''/etc/dovecot/dovecot.conf'' with your favourite editor [[vim]]; first make sure the ''protocols ='' line reads protocols = imap imaps pop3 pop3s (which it should by default). The second setting is quite crucial. By default, the location of the mail directories is found automatically by Dovecot, but here that won't work. Find the line that reads ''#maildir_location ='', and change it to mail_location = maildir:/data/vmail/%d/%n/Maildir This will look for mail in directory ''/data/vmail/'''DOMAIN'''/'''USER'''/Maildir'', and expect this directory to be in "maildir" format. Next look for a section called "auth default". First define the allowed authentication mechanisms: mechanisms = plain login Then inside that same section you need to uncomment: passdb sql { args = /etc/dovecot/dovecot-sql.conf } which tells Dovecot that the passwords are stored in an SQL database (it's obvious that we'll now have to create this conf-file) and: userdb static { args = uid=120 gid=120 home=/data/vmail/%d/%n allow_all_users=yes } to tell Dovecot where the mailboxes are located. This is similar to the ''mail_location'' setting. Next task: comment out the section ''passdb pam'', so that Dovecot doesn't accidentally try to service local users as well. Next up: tell Dovecot to handle IMAP the same as previous versions of this virtual mailserver have: namespace private { separator = . prefix = INBOX. inbox = yes } (this section is not necessary if you're building this server from scratch). You'll also want to comment out the ''passdb pam'' sections, since we're not hosting mail for local users. Next up, we'll edit the section ''socket listen'' so that Dovecot can access the user database (master section), and our Postfix mailserver can access Dovecot (client section): socket listen { master { path = /var/run/dovecot/auth-master mode = 0600 user = vmail } client { path = /var/spool/postfix/private/auth mode = 0660 user = postfix group = postfix } } Finally, the protocol section, where we specify log files, an address to put in mails when we send out nondelivery reports, and a place to store scripts: protocol lda { log_path = /var/log/appslog/mail/dovecot-deliver.log auth_socket_path = /var/run/dovecot/auth-master postmaster_address = postmaster@saruman.biz mail_plugins = cmusieve global_script_path = /data/vmail/globalsieverc } Now that we've finished the Dovecot configuration file, we need to create a fitting MySQL configuration file for Dovecot. The file is ''/etc/dovecot/dovecot-sql.conf'', and its contents are driver = mysql connect = host=127.0.0.1 dbname=vmail user=vmail_admin password=SuperSecret default_pass_scheme = PLAIN-MD5 password_query = SELECT email as user, passwd as password FROM view_users WHERE email='%u'; When you've created this file (as root), change the attributes of ''dovecot-sql.conf'' and ''dovecot.conf'', and then restart Dovecot to start using the new configuration. Note: ''dovecot.conf'' needs to be read by Postfix, hence the group ownership for the file. chmod u=rw,g=,o= /etc/dovecot/dovecot-sql.conf chgrp vmail /etc/dovecot/dovecot.conf chmod u=rw,g=r,o= /etc/dovecot/dovecot.conf /etc/init.d/dovecot restart 6ebdc188b6b87b29ff43d7e5f69649948fcdd131 1965 1977 2008-11-01T23:52:35Z Saruman! 2 Added creation of virtual user wikitext text/x-wiki ==E-mail server setup== What we want to accomplish here is the setup of a mail server with the following properties: * can serve multiple mail domains * can relay mail for other domains to other mail servers * can have one or more mailboxes per domain * users of these mailboxes can be virtual (do not need to have a Linux user account) * can have multiple aliases per mailbox * can forward mail for certain aliases to multiple mailboxes For this type of mail server setup, we owe a great thankyou to [http://workaround.org/articles/ispmail-etch/ Christoph Haas], whose advise has helped us create flexible and reliable mail servers since 2003. ==Preparation== We'll assume that the server currently has no mailserver installed, at least no other than the default ''exim'' mailserver. Furthermore, the server is already fitted with MySQL, and this database is running without problems. The hostname of the server must be set correctly, so that ''hostname -f'' returns a valid DNS name, like ''lighthouse.saruman.biz.''. It might also be an internal name like ''lighthouse.saruman.lan.'' but that will require us to give extra attention to the name under which Postfix will contact its collegues on the Internet. Also, the server can correctly [Networking_section#DNS_resolution_under_Debian | resolve DNS names] like [http://www.debian.org www.debian.org], preferably by running it's own caching DNS server. The server is kept on the correct date and time using NTP, TCP port 25 is open on the server, the ISP will allow connections from Internet to this port, and if there's a firewall running on this server, then it has port 25 open so as to not block incoming e-mail. ==Software installation== As a first step, we use [[APT and aptitude|apt or aptitude]] to make sure that our server is up-to-date. Then we can install the necessary software packages. Under Debian 5.0 "Lenny", the (single) packages is: * ''postfix'', the mail server itself - this includes the "virtual package" postfix-tls, that we want to use to secure connections to Postfix with the TLS protocol At the same time we can - and must - purge the following packages: * exim4 * exim4-base * exim4-daemon-light * exim4-config In ''aptitude'', only press "go" when you've marked all four of these packages "purge", or you cannot install postfix. When installing the postfix package, the Debian installer script will ask you several questions, which you can answer like this: * General type of mail configuration: Internet site * System mail name: the FQDN of the mail server that you've verified in the previous section. Note that the script will try to guess the DNS name, but that might yield a DNS name with a trailing dot. That is technically correct, but the installation script will barf. Remove the trailing dot before hitting &lt;enter>! * Postmaster mail address: the address that all mail should go to that is addressed to "root" and "postmaster". * Domain list: give the list of all domains that the machine can consider itself the FINAL destination for. This should at a minimum include an empty value, "localhost" and the FQDN of the machine itself (no trailing dots!); however, if you're running your own mail domain, you can also add that (e.g. "saruman.biz"). Thus, the list could look like this: saruman.biz, lighthouse.saruman.lan, localhost.saruman.lan, , localhost * Force synchronous updates? We think that's not necessary, but please read the question and decide for yourself * Local networks: something like ''127.0.0.0/8 [::ffff:127.0.0.0]/104 [::1]/128 192.168.67.0/24'' (the default, augmented with your local IP range) * Mailbox size limits: you can give postfix a limit in bytes, but we're going to use one single big mailbox for all users, so we cannot let Postfix guard it. Leave it at 0 (zero) so we don't have a size limit. * Character for local address extension: we leave it at ''+'' * Internet protocols to use: currently we don't have IPv6 support, so there's no sense in letting Postfix try to serve IPv6. We choose ''ipv4'' only. With the above data, the Debian install script for Postfix can do its job and configure Postfix with some basic settings. Now that Postfix is installed, we can install some dependent packages (we could install them in the same run, but if anything goes amiss with the postfix installation, then these packages are going to remain unconfigured as well): * ''postfix-doc'', the accompanying documentation; * ''postfix-mysql'', necessary to have Postfix talk to our MySQL server; * ''postfix-pcre'' to be able to parse regular expressions, which which we can combat spam; * ''dovecot-imapd'' is a daemon that will provide your users with IMAP access to their mail; * ''dovecot-pop3d'' is another daemon, but for the POP3 protocol. ==Virtual User creation== When we're done, we'll need a "system user" that is the owner of all mailboxes that we're serving. We suggest the name "vmail" for this user. To create this user, and his home directory, we can run the following commands: groupadd -g 120 vmail useradd -g vmail -u 120 vmail -d /data/vmail -m -s /bin/false As you see, we've chosen a group ID and user ID of 120 (after confirming that this ID was not taken by another group or user, by checking ''/etc/passwd'' and ''/etc/group''. Furthermore, we've decided to keep the ''vmail'' user's home directory not under ''/home/vmail'', but in a special place where we're going to expect server data to reside - in our server, the ''/data'' directory (which is a RAID-5 array mounted under root). By adding ''-m'', we've actually created the home directory, and adding ''-s /bin/false'' makes totally sure that the user ''vmail'' can never ever log in - even if we've not created a password for this user, so ''vmail'' shouldn't be able to log in anyway. Better safe than sorry. ==MySQL configuration== We will use the MySQL database to record data on our mail system, and then give our Postfix access to this database so that it can read its configuration from there. For starters, we'll create a MySQL database named "vmail", and a MySQL user named "vmail_admin" that can read all necessary data from that "vmail" database. Then, we create the necessary tables. We do this with the MySQL client ''mysql''. However, we're quite lazy, so we don't create this database by hand, but by use of a script [[create.vmail.sql]]. To this end, feed the [[create.vmail.sql]] script into the ''mysql'' client like this: mysql -u root -p < create.vmail.sql (This of course assumes you have ''create.vmail.sql'' in your current working directory; if not you can include the path to the file.) Simply give the MySQL root user password, and the script creates the database, the user, and the necessary tables. We're not going to fill the database tables just yet, but we ''are'' going to tell Postfix to use the ''vmail'' database, and also ''how'' to read the database. To this end, we're going to create three configuration files in directory ''/etc/postfix''. We'll start off with one configuration file, with which Postfix can determine if a domain name is among the domain(s) that it's actually hosting mailboxes for. Create file ''/etc/postfix/mysql-virtual-domains.cf'' with the following content: user = vmail_admin password = SuperSecret hosts = 127.0.0.1 dbname = vmail query = SELECT 1 FROM virtual_domains WHERE vdomain='%s' Next, we change the attributes on this configuration file so that it is secure. Also, we tell postfix to check this configuration file when it needs to check "virtual_mailbox_domains": chown root:postfix /etc/postfix/mysql-virtual-domains.cf chmod o=/etc/postfix/mysql-virtual-domains.cf postconf -e virtual_mailbox_domains=mysql:/etc/postfix/mysql-virtual-domains.cf Use of this configuration file in postfix has the effect of returning "yes" when checking our database for the domain part of an email address. Naturally, this configuration file has to be fitted with the actual ''vmail_admin'' password rather than our example "SuperSecret". Furthermore, we'll have to fill our database with all virtual domains that we're hosting, by running the mysql client and feeding it information like this: mysql -u root -p vmail mysql> INSERT INTO virtual_domains (id, vdomain) VALUES (1, 'saruman.biz'); mysql> INSERT INTO virtual_domains (vdomain) VALUES ('wiki.saruman.biz'); mysql> INSERT INTO virtual_domains (vdomain) VALUES ('shop.saruman.biz'); mysql> exit This has the effect of creating three entries. Only the first entry needs an ''id'' value, because in MySQL we've defined that field as AUTO_INCREMENT. After creating your first virtual domain in the table, you never have to use a statement like the first INSERT again, only statements like the other two. After creating data like this, postfix will be able to recognise that you have three virtual mail domains (namely the three domains in the VALUES section) for which it hosts virtual mailboxes. However, 2577da27bd3447613e159d2ee6513bad62bd5ee1 1966 1965 2008-11-01T23:57:15Z Saruman! 2 /* Virtual User creation */ added postconf wikitext text/x-wiki ==E-mail server setup== What we want to accomplish here is the setup of a mail server with the following properties: * can serve multiple mail domains * can relay mail for other domains to other mail servers * can have one or more mailboxes per domain * users of these mailboxes can be virtual (do not need to have a Linux user account) * can have multiple aliases per mailbox * can forward mail for certain aliases to multiple mailboxes For this type of mail server setup, we owe a great thankyou to [http://workaround.org/articles/ispmail-etch/ Christoph Haas], whose advise has helped us create flexible and reliable mail servers since 2003. ==Preparation== We'll assume that the server currently has no mailserver installed, at least no other than the default ''exim'' mailserver. Furthermore, the server is already fitted with MySQL, and this database is running without problems. The hostname of the server must be set correctly, so that ''hostname -f'' returns a valid DNS name, like ''lighthouse.saruman.biz.''. It might also be an internal name like ''lighthouse.saruman.lan.'' but that will require us to give extra attention to the name under which Postfix will contact its collegues on the Internet. Also, the server can correctly [Networking_section#DNS_resolution_under_Debian | resolve DNS names] like [http://www.debian.org www.debian.org], preferably by running it's own caching DNS server. The server is kept on the correct date and time using NTP, TCP port 25 is open on the server, the ISP will allow connections from Internet to this port, and if there's a firewall running on this server, then it has port 25 open so as to not block incoming e-mail. ==Software installation== As a first step, we use [[APT and aptitude|apt or aptitude]] to make sure that our server is up-to-date. Then we can install the necessary software packages. Under Debian 5.0 "Lenny", the (single) packages is: * ''postfix'', the mail server itself - this includes the "virtual package" postfix-tls, that we want to use to secure connections to Postfix with the TLS protocol At the same time we can - and must - purge the following packages: * exim4 * exim4-base * exim4-daemon-light * exim4-config In ''aptitude'', only press "go" when you've marked all four of these packages "purge", or you cannot install postfix. When installing the postfix package, the Debian installer script will ask you several questions, which you can answer like this: * General type of mail configuration: Internet site * System mail name: the FQDN of the mail server that you've verified in the previous section. Note that the script will try to guess the DNS name, but that might yield a DNS name with a trailing dot. That is technically correct, but the installation script will barf. Remove the trailing dot before hitting &lt;enter>! * Postmaster mail address: the address that all mail should go to that is addressed to "root" and "postmaster". * Domain list: give the list of all domains that the machine can consider itself the FINAL destination for. This should at a minimum include an empty value, "localhost" and the FQDN of the machine itself (no trailing dots!); however, if you're running your own mail domain, you can also add that (e.g. "saruman.biz"). Thus, the list could look like this: saruman.biz, lighthouse.saruman.lan, localhost.saruman.lan, , localhost * Force synchronous updates? We think that's not necessary, but please read the question and decide for yourself * Local networks: something like ''127.0.0.0/8 [::ffff:127.0.0.0]/104 [::1]/128 192.168.67.0/24'' (the default, augmented with your local IP range) * Mailbox size limits: you can give postfix a limit in bytes, but we're going to use one single big mailbox for all users, so we cannot let Postfix guard it. Leave it at 0 (zero) so we don't have a size limit. * Character for local address extension: we leave it at ''+'' * Internet protocols to use: currently we don't have IPv6 support, so there's no sense in letting Postfix try to serve IPv6. We choose ''ipv4'' only. With the above data, the Debian install script for Postfix can do its job and configure Postfix with some basic settings. Now that Postfix is installed, we can install some dependent packages (we could install them in the same run, but if anything goes amiss with the postfix installation, then these packages are going to remain unconfigured as well): * ''postfix-doc'', the accompanying documentation; * ''postfix-mysql'', necessary to have Postfix talk to our MySQL server; * ''postfix-pcre'' to be able to parse regular expressions, which which we can combat spam; * ''dovecot-imapd'' is a daemon that will provide your users with IMAP access to their mail; * ''dovecot-pop3d'' is another daemon, but for the POP3 protocol. ==Virtual User creation== When we're done, we'll need a "system user" that is the owner of all mailboxes that we're serving. We suggest the name "vmail" for this user. To create this user, and his home directory, we can run the following commands: groupadd -g 120 vmail useradd -g vmail -u 120 vmail -d /data/vmail -m -s /bin/false As you see, we've chosen a group ID and user ID of 120 (after confirming that this ID was not taken by another group or user, by checking ''/etc/passwd'' and ''/etc/group''. Furthermore, we've decided to keep the ''vmail'' user's home directory not under ''/home/vmail'', but in a special place where we're going to expect server data to reside - in our server, the ''/data'' directory (which is a RAID-5 array mounted under root). By adding ''-m'', we've actually created the home directory, and adding ''-s /bin/false'' makes totally sure that the user ''vmail'' can never ever log in - even if we've not created a password for this user, so ''vmail'' shouldn't be able to log in anyway. Better safe than sorry. To tell Postfix that this ''vmail'' user is someone special, we run postconf -e virtual_uid_maps=static:120 postconf -e virtual_gid_maps=static:120 That makes postfix understand that all mail for the virtual mail domains must be written to disk with these specified user and group ID's. ==MySQL configuration== We will use the MySQL database to record data on our mail system, and then give our Postfix access to this database so that it can read its configuration from there. For starters, we'll create a MySQL database named "vmail", and a MySQL user named "vmail_admin" that can read all necessary data from that "vmail" database. Then, we create the necessary tables. We do this with the MySQL client ''mysql''. However, we're quite lazy, so we don't create this database by hand, but by use of a script [[create.vmail.sql]]. To this end, feed the [[create.vmail.sql]] script into the ''mysql'' client like this: mysql -u root -p < create.vmail.sql (This of course assumes you have ''create.vmail.sql'' in your current working directory; if not you can include the path to the file.) Simply give the MySQL root user password, and the script creates the database, the user, and the necessary tables. We're not going to fill the database tables just yet, but we ''are'' going to tell Postfix to use the ''vmail'' database, and also ''how'' to read the database. To this end, we're going to create three configuration files in directory ''/etc/postfix''. We'll start off with one configuration file, with which Postfix can determine if a domain name is among the domain(s) that it's actually hosting mailboxes for. Create file ''/etc/postfix/mysql-virtual-domains.cf'' with the following content: user = vmail_admin password = SuperSecret hosts = 127.0.0.1 dbname = vmail query = SELECT 1 FROM virtual_domains WHERE vdomain='%s' Next, we change the attributes on this configuration file so that it is secure. Also, we tell postfix to check this configuration file when it needs to check "virtual_mailbox_domains": chown root:postfix /etc/postfix/mysql-virtual-domains.cf chmod o=/etc/postfix/mysql-virtual-domains.cf postconf -e virtual_mailbox_domains=mysql:/etc/postfix/mysql-virtual-domains.cf Use of this configuration file in postfix has the effect of returning "yes" when checking our database for the domain part of an email address. Naturally, this configuration file has to be fitted with the actual ''vmail_admin'' password rather than our example "SuperSecret". Furthermore, we'll have to fill our database with all virtual domains that we're hosting, by running the mysql client and feeding it information like this: mysql -u root -p vmail mysql> INSERT INTO virtual_domains (id, vdomain) VALUES (1, 'saruman.biz'); mysql> INSERT INTO virtual_domains (vdomain) VALUES ('wiki.saruman.biz'); mysql> INSERT INTO virtual_domains (vdomain) VALUES ('shop.saruman.biz'); mysql> exit This has the effect of creating three entries. Only the first entry needs an ''id'' value, because in MySQL we've defined that field as AUTO_INCREMENT. After creating your first virtual domain in the table, you never have to use a statement like the first INSERT again, only statements like the other two. After creating data like this, postfix will be able to recognise that you have three virtual mail domains (namely the three domains in the VALUES section) for which it hosts virtual mailboxes. However, b2e6de26ce1dbc6b668459202ea38f8801150e76 1967 1966 2008-11-02T10:45:54Z Saruman! 2 /* Virtual User creation */ renamed to Virtual Mailman creation, for clarity wikitext text/x-wiki ==E-mail server setup== What we want to accomplish here is the setup of a mail server with the following properties: * can serve multiple mail domains * can relay mail for other domains to other mail servers * can have one or more mailboxes per domain * users of these mailboxes can be virtual (do not need to have a Linux user account) * can have multiple aliases per mailbox * can forward mail for certain aliases to multiple mailboxes For this type of mail server setup, we owe a great thankyou to [http://workaround.org/articles/ispmail-etch/ Christoph Haas], whose advise has helped us create flexible and reliable mail servers since 2003. ==Preparation== We'll assume that the server currently has no mailserver installed, at least no other than the default ''exim'' mailserver. Furthermore, the server is already fitted with MySQL, and this database is running without problems. The hostname of the server must be set correctly, so that ''hostname -f'' returns a valid DNS name, like ''lighthouse.saruman.biz.''. It might also be an internal name like ''lighthouse.saruman.lan.'' but that will require us to give extra attention to the name under which Postfix will contact its collegues on the Internet. Also, the server can correctly [Networking_section#DNS_resolution_under_Debian | resolve DNS names] like [http://www.debian.org www.debian.org], preferably by running it's own caching DNS server. The server is kept on the correct date and time using NTP, TCP port 25 is open on the server, the ISP will allow connections from Internet to this port, and if there's a firewall running on this server, then it has port 25 open so as to not block incoming e-mail. ==Software installation== As a first step, we use [[APT and aptitude|apt or aptitude]] to make sure that our server is up-to-date. Then we can install the necessary software packages. Under Debian 5.0 "Lenny", the (single) packages is: * ''postfix'', the mail server itself - this includes the "virtual package" postfix-tls, that we want to use to secure connections to Postfix with the TLS protocol At the same time we can - and must - purge the following packages: * exim4 * exim4-base * exim4-daemon-light * exim4-config In ''aptitude'', only press "go" when you've marked all four of these packages "purge", or you cannot install postfix. When installing the postfix package, the Debian installer script will ask you several questions, which you can answer like this: * General type of mail configuration: Internet site * System mail name: the FQDN of the mail server that you've verified in the previous section. Note that the script will try to guess the DNS name, but that might yield a DNS name with a trailing dot. That is technically correct, but the installation script will barf. Remove the trailing dot before hitting &lt;enter>! * Postmaster mail address: the address that all mail should go to that is addressed to "root" and "postmaster". * Domain list: give the list of all domains that the machine can consider itself the FINAL destination for. This should at a minimum include an empty value, "localhost" and the FQDN of the machine itself (no trailing dots!); however, if you're running your own mail domain, you can also add that (e.g. "saruman.biz"). Thus, the list could look like this: saruman.biz, lighthouse.saruman.lan, localhost.saruman.lan, , localhost * Force synchronous updates? We think that's not necessary, but please read the question and decide for yourself * Local networks: something like ''127.0.0.0/8 [::ffff:127.0.0.0]/104 [::1]/128 192.168.67.0/24'' (the default, augmented with your local IP range) * Mailbox size limits: you can give postfix a limit in bytes, but we're going to use one single big mailbox for all users, so we cannot let Postfix guard it. Leave it at 0 (zero) so we don't have a size limit. * Character for local address extension: we leave it at ''+'' * Internet protocols to use: currently we don't have IPv6 support, so there's no sense in letting Postfix try to serve IPv6. We choose ''ipv4'' only. With the above data, the Debian install script for Postfix can do its job and configure Postfix with some basic settings. Now that Postfix is installed, we can install some dependent packages (we could install them in the same run, but if anything goes amiss with the postfix installation, then these packages are going to remain unconfigured as well): * ''postfix-doc'', the accompanying documentation; * ''postfix-mysql'', necessary to have Postfix talk to our MySQL server; * ''postfix-pcre'' to be able to parse regular expressions, which which we can combat spam; * ''dovecot-imapd'' is a daemon that will provide your users with IMAP access to their mail; * ''dovecot-pop3d'' is another daemon, but for the POP3 protocol. ==Virtual Mailman creation== When we're done, we'll need a "system user", a sort of virtual mailman that is the owner of all mailboxes that we're serving. We suggest the name "vmail" for this user. Note: this user does not get his own mailbox (i.e. there's no mailbox at vmail@saruman.biz). To create this user, and his home directory, we can run the following commands: groupadd -g 120 vmail useradd -g vmail -u 120 vmail -d /data/vmail -m -s /bin/false As you see, we've chosen a group ID and user ID of 120 (after confirming that this ID was not taken by another group or user, by checking ''/etc/passwd'' and ''/etc/group''. Furthermore, we've decided to keep the ''vmail'' user's home directory not under ''/home/vmail'', but in a special place where we're going to expect server data to reside - in our server, the ''/data'' directory (which is a RAID-5 array mounted under root). By adding ''-m'', we've actually created the home directory, and adding ''-s /bin/false'' makes totally sure that the user ''vmail'' can never ever log in - even if we've not created a password for this user, so ''vmail'' shouldn't be able to log in anyway. Better safe than sorry. To tell Postfix that this ''vmail'' user is someone special, we run postconf -e virtual_uid_maps=static:120 postconf -e virtual_gid_maps=static:120 That makes postfix understand that all mail for the virtual mail domains must be written to disk with these specified user and group ID's. ==MySQL configuration== We will use the MySQL database to record data on our mail system, and then give our Postfix access to this database so that it can read its configuration from there. For starters, we'll create a MySQL database named "vmail", and a MySQL user named "vmail_admin" that can read all necessary data from that "vmail" database. Then, we create the necessary tables. We do this with the MySQL client ''mysql''. However, we're quite lazy, so we don't create this database by hand, but by use of a script [[create.vmail.sql]]. To this end, feed the [[create.vmail.sql]] script into the ''mysql'' client like this: mysql -u root -p < create.vmail.sql (This of course assumes you have ''create.vmail.sql'' in your current working directory; if not you can include the path to the file.) Simply give the MySQL root user password, and the script creates the database, the user, and the necessary tables. We're not going to fill the database tables just yet, but we ''are'' going to tell Postfix to use the ''vmail'' database, and also ''how'' to read the database. To this end, we're going to create three configuration files in directory ''/etc/postfix''. We'll start off with one configuration file, with which Postfix can determine if a domain name is among the domain(s) that it's actually hosting mailboxes for. Create file ''/etc/postfix/mysql-virtual-domains.cf'' with the following content: user = vmail_admin password = SuperSecret hosts = 127.0.0.1 dbname = vmail query = SELECT 1 FROM virtual_domains WHERE vdomain='%s' Next, we change the attributes on this configuration file so that it is secure. Also, we tell postfix to check this configuration file when it needs to check "virtual_mailbox_domains": chown root:postfix /etc/postfix/mysql-virtual-domains.cf chmod o=/etc/postfix/mysql-virtual-domains.cf postconf -e virtual_mailbox_domains=mysql:/etc/postfix/mysql-virtual-domains.cf Use of this configuration file in postfix has the effect of returning "yes" when checking our database for the domain part of an email address. Naturally, this configuration file has to be fitted with the actual ''vmail_admin'' password rather than our example "SuperSecret". Furthermore, we'll have to fill our database with all virtual domains that we're hosting, by running the mysql client and feeding it information like this: mysql -u root -p vmail mysql> INSERT INTO virtual_domains (id, vdomain) VALUES (1, 'saruman.biz'); mysql> INSERT INTO virtual_domains (vdomain) VALUES ('wiki.saruman.biz'); mysql> INSERT INTO virtual_domains (vdomain) VALUES ('shop.saruman.biz'); mysql> exit This has the effect of creating three entries. Only the first entry needs an ''id'' value, because in MySQL we've defined that field as AUTO_INCREMENT. After creating your first virtual domain in the table, you never have to use a statement like the first INSERT again, only statements like the other two. After creating data like this, postfix will be able to recognise that you have three virtual mail domains (namely the three domains in the VALUES section) for which it hosts virtual mailboxes. However, 3295b136e4594e80347cfefceb62ad0c23eda33a 1968 1967 2008-11-02T11:01:26Z Saruman! 2 /* MySQL configuration */ added mailboxmaps wikitext text/x-wiki ==E-mail server setup== What we want to accomplish here is the setup of a mail server with the following properties: * can serve multiple mail domains * can relay mail for other domains to other mail servers * can have one or more mailboxes per domain * users of these mailboxes can be virtual (do not need to have a Linux user account) * can have multiple aliases per mailbox * can forward mail for certain aliases to multiple mailboxes For this type of mail server setup, we owe a great thankyou to [http://workaround.org/articles/ispmail-etch/ Christoph Haas], whose advise has helped us create flexible and reliable mail servers since 2003. ==Preparation== We'll assume that the server currently has no mailserver installed, at least no other than the default ''exim'' mailserver. Furthermore, the server is already fitted with MySQL, and this database is running without problems. The hostname of the server must be set correctly, so that ''hostname -f'' returns a valid DNS name, like ''lighthouse.saruman.biz.''. It might also be an internal name like ''lighthouse.saruman.lan.'' but that will require us to give extra attention to the name under which Postfix will contact its collegues on the Internet. Also, the server can correctly [Networking_section#DNS_resolution_under_Debian | resolve DNS names] like [http://www.debian.org www.debian.org], preferably by running it's own caching DNS server. The server is kept on the correct date and time using NTP, TCP port 25 is open on the server, the ISP will allow connections from Internet to this port, and if there's a firewall running on this server, then it has port 25 open so as to not block incoming e-mail. ==Software installation== As a first step, we use [[APT and aptitude|apt or aptitude]] to make sure that our server is up-to-date. Then we can install the necessary software packages. Under Debian 5.0 "Lenny", the (single) packages is: * ''postfix'', the mail server itself - this includes the "virtual package" postfix-tls, that we want to use to secure connections to Postfix with the TLS protocol At the same time we can - and must - purge the following packages: * exim4 * exim4-base * exim4-daemon-light * exim4-config In ''aptitude'', only press "go" when you've marked all four of these packages "purge", or you cannot install postfix. When installing the postfix package, the Debian installer script will ask you several questions, which you can answer like this: * General type of mail configuration: Internet site * System mail name: the FQDN of the mail server that you've verified in the previous section. Note that the script will try to guess the DNS name, but that might yield a DNS name with a trailing dot. That is technically correct, but the installation script will barf. Remove the trailing dot before hitting &lt;enter>! * Postmaster mail address: the address that all mail should go to that is addressed to "root" and "postmaster". * Domain list: give the list of all domains that the machine can consider itself the FINAL destination for. This should at a minimum include an empty value, "localhost" and the FQDN of the machine itself (no trailing dots!); however, if you're running your own mail domain, you can also add that (e.g. "saruman.biz"). Thus, the list could look like this: saruman.biz, lighthouse.saruman.lan, localhost.saruman.lan, , localhost * Force synchronous updates? We think that's not necessary, but please read the question and decide for yourself * Local networks: something like ''127.0.0.0/8 [::ffff:127.0.0.0]/104 [::1]/128 192.168.67.0/24'' (the default, augmented with your local IP range) * Mailbox size limits: you can give postfix a limit in bytes, but we're going to use one single big mailbox for all users, so we cannot let Postfix guard it. Leave it at 0 (zero) so we don't have a size limit. * Character for local address extension: we leave it at ''+'' * Internet protocols to use: currently we don't have IPv6 support, so there's no sense in letting Postfix try to serve IPv6. We choose ''ipv4'' only. With the above data, the Debian install script for Postfix can do its job and configure Postfix with some basic settings. Now that Postfix is installed, we can install some dependent packages (we could install them in the same run, but if anything goes amiss with the postfix installation, then these packages are going to remain unconfigured as well): * ''postfix-doc'', the accompanying documentation; * ''postfix-mysql'', necessary to have Postfix talk to our MySQL server; * ''postfix-pcre'' to be able to parse regular expressions, which which we can combat spam; * ''dovecot-imapd'' is a daemon that will provide your users with IMAP access to their mail; * ''dovecot-pop3d'' is another daemon, but for the POP3 protocol. ==Virtual Mailman creation== When we're done, we'll need a "system user", a sort of virtual mailman that is the owner of all mailboxes that we're serving. We suggest the name "vmail" for this user. Note: this user does not get his own mailbox (i.e. there's no mailbox at vmail@saruman.biz). To create this user, and his home directory, we can run the following commands: groupadd -g 120 vmail useradd -g vmail -u 120 vmail -d /data/vmail -m -s /bin/false As you see, we've chosen a group ID and user ID of 120 (after confirming that this ID was not taken by another group or user, by checking ''/etc/passwd'' and ''/etc/group''. Furthermore, we've decided to keep the ''vmail'' user's home directory not under ''/home/vmail'', but in a special place where we're going to expect server data to reside - in our server, the ''/data'' directory (which is a RAID-5 array mounted under root). By adding ''-m'', we've actually created the home directory, and adding ''-s /bin/false'' makes totally sure that the user ''vmail'' can never ever log in - even if we've not created a password for this user, so ''vmail'' shouldn't be able to log in anyway. Better safe than sorry. To tell Postfix that this ''vmail'' user is someone special, we run postconf -e virtual_uid_maps=static:120 postconf -e virtual_gid_maps=static:120 That makes postfix understand that all mail for the virtual mail domains must be written to disk with these specified user and group ID's. ==MySQL configuration== We will use the MySQL database to record data on our mail system, and then give our Postfix access to this database so that it can read its configuration from there. For starters, we'll create a MySQL database named "vmail", and a MySQL user named "vmail_admin" that can read all necessary data from that "vmail" database. Then, we create the necessary tables. We do this with the MySQL client ''mysql''. However, we're quite lazy, so we don't create this database by hand, but by use of a script [[create.vmail.sql]]. To this end, feed the [[create.vmail.sql]] script into the ''mysql'' client like this: mysql -u root -p < create.vmail.sql (This of course assumes you have ''create.vmail.sql'' in your current working directory; if not you can include the path to the file.) Simply give the MySQL root user password, and the script creates the database, the user, and the necessary tables. Next, we're going to tell Postfix to use the ''vmail'' database, and also how to read the database (Postfix never writes the MySQL database). To this end, we're going to create three configuration files in directory ''/etc/postfix''. We'll start off with one configuration file, with which Postfix can determine if a domain name is among the domain(s) that it's actually hosting mailboxes for. Then we'll create the config file that checks the table that contains all the users that have a virtual mailbox, and finally we create the lookup for the table with all the aliases. ===Virtual mail domains lookup=== Create file ''/etc/postfix/mysql-virtual-domains.cf'' with the following content: user = vmail_admin password = SuperSecret hosts = 127.0.0.1 dbname = vmail query = SELECT 1 FROM virtual_domains WHERE vdomain='%s' Next, we change the attributes on this configuration file so that it is secure. Also, we tell postfix to check this configuration file when it needs to check "virtual_mailbox_domains": chown root:postfix /etc/postfix/mysql-virtual-domains.cf chmod o=/etc/postfix/mysql-virtual-domains.cf postconf -e virtual_mailbox_domains=mysql:/etc/postfix/mysql-virtual-domains.cf Use of this configuration file in postfix has the effect of returning "yes" when checking our database for the domain part of an email address. Naturally, this configuration file has to be fitted with the actual ''vmail_admin'' password rather than our example "SuperSecret". Furthermore, we'll have to fill our database with all virtual domains that we're hosting, by running the mysql client and feeding it information like this: mysql -u root -p vmail mysql> INSERT INTO virtual_domains (id, vdomain) VALUES (1, 'saruman.biz'); mysql> INSERT INTO virtual_domains (vdomain) VALUES ('wiki.saruman.biz'); mysql> INSERT INTO virtual_domains (vdomain) VALUES ('shop.saruman.biz'); mysql> exit This has the effect of creating three entries. Only the first entry needs an ''id'' value, because in MySQL we've defined that field as AUTO_INCREMENT. After creating your first virtual domain in the table, you never have to use a statement like the first INSERT again, only statements like the other two. After creating data like this, postfix will be able to recognise that you have three virtual mail domains (namely the three domains in the VALUES section) for which it hosts virtual mailboxes. === Virtual mail user lookup=== Create the file ''/etc/postfix/mysql-virtual-mailbox-maps.cf'' with the following content: user = vmail_admin password = SuperSecret hosts = 127.0.0.1 dbname = vmail query = SELECT 1 FROM view_users WHERE email='%s' Next, we change the attributes on this configuration file so that it is secure. Also, we tell Postfix that this mapping file is supposed to be used for the ''virtual_mailbox_maps'' mapping: chown root:postfix /etc/postfix/mysql-virtual-mailbox-maps.cf chmod o=/etc/postfix/mysql-virtual-mailbox-maps.cf postconf -e virtual_mailbox_maps=mysql:/etc/postfix/mysql-virtual-mailbox-maps.cf However, the lookup of virtual mailboxes at present will not work (yet), because we need data in the ''users'' table. 9a1e21a29736ca5f00b1d5043f3dcad5c4d467b6 1979 1968 2008-11-02T15:14:14Z Saruman! 2 /* Configuring mail delivery through Dovecot LDA */ added "finishing up" section wikitext text/x-wiki ==E-mail server setup== What we want to accomplish here is the setup of a mail server with the following properties: * can serve multiple mail domains * can relay mail for other domains to other mail servers * can have one or more mailboxes per domain * users of these mailboxes can be virtual (do not need to have a Linux user account) * can have multiple aliases per mailbox * can forward mail for certain aliases to multiple mailboxes For this type of mail server setup, we owe a great thankyou to [http://workaround.org/articles/ispmail-etch/ Christoph Haas], whose advise has helped us create flexible and reliable mail servers since 2003. ==Preparation== We'll assume that the server currently has no mailserver installed, at least no other than the default ''exim'' mailserver. Furthermore, the server is already fitted with MySQL, and this database is running without problems. The hostname of the server must be set correctly, so that ''hostname -f'' returns a valid DNS name, like ''lighthouse.saruman.biz.''. It might also be an internal name like ''lighthouse.saruman.lan.'' but that will require us to give extra attention to the name under which Postfix will contact its collegues on the Internet. Also, the server can correctly [Networking_section#DNS_resolution_under_Debian | resolve DNS names] like [http://www.debian.org www.debian.org], preferably by running it's own caching DNS server. The server is kept on the correct date and time using NTP, TCP port 25 is open on the server, the ISP will allow connections from Internet to this port, and if there's a firewall running on this server, then it has port 25 open so as to not block incoming e-mail. ==Software installation== As a first step, we use [[APT and aptitude|apt or aptitude]] to make sure that our server is up-to-date. Then we can install the necessary software packages. Under Debian 5.0 "Lenny", the (single) packages is: * ''postfix'', the mail server itself - this includes the "virtual package" postfix-tls, that we want to use to secure connections to Postfix with the TLS protocol At the same time we can - and must - purge the following packages: * exim4 * exim4-base * exim4-daemon-light * exim4-config In ''aptitude'', only press "go" when you've marked all four of these packages "purge", or you cannot install postfix. When installing the postfix package, the Debian installer script will ask you several questions, which you can answer like this: * General type of mail configuration: Internet site * System mail name: the FQDN of the mail server that you've verified in the previous section. Note that the script will try to guess the DNS name, but that might yield a DNS name with a trailing dot. That is technically correct, but the installation script will barf. Remove the trailing dot before hitting &lt;enter>! * Postmaster mail address: the address that all mail should go to that is addressed to "root" and "postmaster". * Domain list: give the list of all domains that the machine can consider itself the FINAL destination for. This should at a minimum include an empty value, "localhost" and the FQDN of the machine itself (no trailing dots!); however, if you're running your own mail domain, you can also add that (e.g. "saruman.biz"). Thus, the list could look like this: saruman.biz, lighthouse.saruman.lan, localhost.saruman.lan, , localhost * Force synchronous updates? We think that's not necessary, but please read the question and decide for yourself * Local networks: something like ''127.0.0.0/8 [::ffff:127.0.0.0]/104 [::1]/128 192.168.67.0/24'' (the default, augmented with your local IP range) * Mailbox size limits: you can give postfix a limit in bytes, but we're going to use one single big mailbox for all users, so we cannot let Postfix guard it. Leave it at 0 (zero) so we don't have a size limit. * Character for local address extension: we leave it at ''+'' * Internet protocols to use: currently we don't have IPv6 support, so there's no sense in letting Postfix try to serve IPv6. We choose ''ipv4'' only. With the above data, the Debian install script for Postfix can do its job and configure Postfix with some basic settings. Now that Postfix is installed, we can install some dependent packages (we could install them in the same run, but if anything goes amiss with the postfix installation, then these packages are going to remain unconfigured as well): * ''postfix-doc'', the accompanying documentation; * ''postfix-mysql'', necessary to have Postfix talk to our MySQL server; * ''postfix-pcre'' to be able to parse regular expressions, which which we can combat spam; * ''dovecot-imapd'' is a daemon that will provide your users with IMAP access to their mail; * ''dovecot-pop3d'' is another daemon, but for the POP3 protocol. ==Virtual Mailman creation== When we're done, we'll need a "system user", a sort of virtual mailman that is the owner of all mailboxes that we're serving. We suggest the name "vmail" for this user. Note: this user does not get his own mailbox (i.e. there's no mailbox at vmail@saruman.biz). To create this user, and his home directory, we can run the following commands: groupadd -g 120 vmail useradd -g vmail -u 120 vmail -d /data/vmail -m -s /bin/false As you see, we've chosen a group ID and user ID of 120 (after confirming that this ID was not taken by another group or user, by checking ''/etc/passwd'' and ''/etc/group''. Furthermore, we've decided to keep the ''vmail'' user's home directory not under ''/home/vmail'', but in a special place where we're going to expect server data to reside - in our server, the ''/data'' directory (which is a RAID-5 array mounted under root). By adding ''-m'', we've actually created the home directory, and adding ''-s /bin/false'' makes totally sure that the user ''vmail'' can never ever log in - even if we've not created a password for this user, so ''vmail'' shouldn't be able to log in anyway. Better safe than sorry. To tell Postfix that this ''vmail'' user is someone special, we run postconf -e virtual_uid_maps=static:120 postconf -e virtual_gid_maps=static:120 That makes postfix understand that all mail for the virtual mail domains must be written to disk with these specified user and group ID's. ==MySQL configuration== ===Database preparation=== We will use the MySQL database to record data on our mail system, and then give our Postfix access to this database so that it can read its configuration from there. For starters, we'll create a MySQL database named "vmail", and a MySQL user named "vmail_admin" that can read all necessary data from that "vmail" database. Then, we create the necessary tables, and a view that links these tables. We do this with the MySQL client ''mysql''. However, we're quite lazy, so we don't create this database by hand (that's error-prone), but by use of a script [[create.vmail.sql]]. To this end, feed the [[create.vmail.sql]] script into the ''mysql'' client like this: mysql -u root -p < create.vmail.sql (This of course assumes you have ''create.vmail.sql'' in your current working directory; if not you can include the path to the file.) Simply give the MySQL root user password, and the script creates the database, the user, the necessary tables, and the view.<br> A note of caution: it is never a good idea to just run scripts without a proper understanding of what it does. Especially with MySQL, it will be advantageous if you understand the SQL commands. Open the script in a text editor, open the [http://dev.mysql.com/doc/refman/5.0/en/ MySQL command reference], and trace back what the script does exactly. ===Inserting data=== Next up, we fill the database with the first sets of values (either test data or the first of our production data). We'll start off with the virtual domains that we're hosting, by running the mysql client and feeding it information like this: mysql -u root -p vmail mysql> INSERT INTO virtual_domains (id, vdomain) VALUES (1, 'saruman.biz'); mysql> INSERT INTO virtual_domains (vdomain) VALUES ('wiki.saruman.biz'); mysql> INSERT INTO virtual_domains (vdomain) VALUES ('shop.saruman.biz'); This has the effect of creating three entries. You can check that everything worked as planned by executing mysql> select * from virtual_domains; Note: only the first entry needs an ''id'' value, because in MySQL we've defined that field as AUTO_INCREMENT. After creating your first virtual domain in the table, you never have to use a statement like the first INSERT again, only statements like the other two. Now the MySQL database has the information needed by Postfix to recognise that you have three virtual mail domains (namely the three domains in the VALUES section) for which it hosts virtual mailboxes. Postfix cannot read this information yet, but that'll be taken care of in the next section. Whle still within the mysql client, we can now create users: mysql> INSERT INTO virtual_users (id, domain_id, user, passwd) VALUES (1, 1, 'jan', MD5('JanSecret')); mysql> INSERT INTO virtual_users (domain_id, user, passwd) VALUES (1, 'mike', MD5('MikeSecret')); mysql> INSERT INTO virtual_users (domain_id, user, passwd) VALUES (3, 'shopkeeper', MD5('ShopSecret')); This has the effect of creating three users "jan" (in domain saruman.biz), "mike" (in domain saruman.biz) and "shopkeeper" (in domain shop.saruman.biz). Again, the ''id'' value is only ever needed in the first statement, because from now on every user addition will auto-increment ''id''. The passwords shown are encrypted with MD5, and put in the ''passwd'' field. Later on, the users will be able to access their mailboxes using this password; we won't tell Postfix anything about them, because it doesn't need the passwords. You can check the content of the ''virtual_users'' table with the right "select" statement, and you can now also see that the view ''view-users'' works: mysql> select * from virtual_users; mysql> select * from view_users; Next up, we're going to add some aliases, which are alternative e-mail addresses for the users; their primary e-mail address can already be seen in the ''view_users'' view, but perhaps you also want mail to "webmaster@shop.saruman.biz" to arrive at one or more mailboxes, e.g. in the mailbox for user "shopkeeper" (within domain "shop.saruman.biz") and this guy's home address ("j.doe@example.com"). Furthermore, we'll define catchall-addresses for all domains, that'll send all mail for which no mailbox can be found to the mailbox of user Mike (for the first two domains) and Webmaster (for shop.saruman.biz; Webmaster himself is an alias yet again, that points to shopkeeper@shop.saruman.biz). To create the catchall, leave out a value for the source address. This creates the empty value for source that will be expanded (using source@domain) to "@domain". mysql> INSERT INTO virtual_aliases (id, domain_id, source, destination) VALUES (1, 2, 'webmaster', 'shopkeeper@shop.saruman.biz'); mysql> INSERT INTO virtual_aliases (domain_id, source, destination) VALUES (2, 'webmaster', 'j.doe@example.com'); mysql> INSERT INTO virtual_aliases (domain_id, destination) VALUES (1, 'mike@saruman.biz'); mysql> INSERT INTO virtual_aliases (domain_id, destination) VALUES (2, 'mike@saruman.biz'); mysql> INSERT INTO virtual_aliases (domain_id, destination) VALUES (3, 'webmaster@saruman.biz'); Again, we don't need to add the ''id'' value any more after the first ever insertion into this table. We can check the result by running a select statement against the ''virtual_aliases'' table and ''view_aliases'' view: mysql> select * from virtual_aliases; mysql> select * from view_aliases; == Postfix configuration for MySQL lookups== Next, we're going to tell Postfix to use the ''vmail'' database, and also how to read the database (Postfix never writes the MySQL database). To this end, we're going to create three configuration files in directory ''/etc/postfix''. We'll start off with one configuration file, with which Postfix can determine if a domain name is among the domain(s) that it's actually hosting mailboxes for. Then we'll create the config file that checks the table that contains all the users that have a virtual mailbox, and finally we create the lookup for the table with all the aliases. ===Virtual mail domains lookup=== Create file ''/etc/postfix/mysql-virtual-domains.cf'' with the following content: user = vmail_admin password = SuperSecret hosts = 127.0.0.1 dbname = vmail query = SELECT 1 FROM virtual_domains WHERE vdomain='%s' Next, we tell postfix to check this configuration file when it needs to check "virtual_mailbox_domains": postconf -e virtual_mailbox_domains=mysql:/etc/postfix/mysql-virtual-domains.cf Use of this configuration file in postfix has the effect of returning "yes" when checking our database for the domain part of an email address. Naturally, this configuration file has to be fitted with the actual ''vmail_admin'' password rather than our example "SuperSecret". === Virtual mail user lookup=== Create the file ''/etc/postfix/mysql-virtual-mailbox-maps.cf'' with the following content: user = vmail_admin password = SuperSecret hosts = 127.0.0.1 dbname = vmail query = SELECT 1 FROM view_users WHERE email='%s' Next, we tell Postfix that this mapping file is supposed to be used for the ''virtual_mailbox_maps'' mapping: postconf -e virtual_mailbox_maps=mysql:/etc/postfix/mysql-virtual-mailbox-maps.cf The lookup of virtual mailboxes should work with the data we've put into the database previously. i.e. postmap -q jan@saruman.biz mysql:/etc/postfix/mysql-virtual-mailbox-maps.cf should return a '''1''' to acknowledge that "jan@saruman.biz" is indeed a virtual mailbox in our Postfix configuration. === Virtual alias lookup=== Create another cf file at ''/etc/postfix/mysql-virtual-alias-maps.cf'': user = vmail_admin password = SuperSecret hosts = 127.0.0.1 dbname = vmail query = SELECT destination FROM view_aliases WHERE email='%s' And create yet another cf file at ''/etc/postfix/mysql-email2email.cf'': user = vmail_admin password = SuperSecret hosts = 127.0.0.1 dbname = vmail query = SELECT email FROM view_users WHERE email='%s' Again, we tell Postfix that this mapping file is supposed to be used for the ''virtual_alias_maps'' mapping: postconf -e virtual_alias_maps=mysql:/etc/postfix/mysql-virtual-alias-maps.cf,mysql:/etc/postfix/mysql-email2email.cf The lookup of virtual aliases should now work as designed: postmap -q shopkeeper@shop.saruman.biz mysql:/etc/postfix/mysql-virtual-alias-maps.cf postmap -q webmaster@shop.saruman.biz mysql:/etc/postfix/mysql-virtual-alias-maps.cf If you've put in the data from the previous section, then both commands should return the same result: ''shopkeeper@saruman.biz''. This shows that Postfix will deliver mail to shopkeeper or to webmaster to the mailbox of shopkeeper. ===Finishing up configuration files=== When everything works as planned, then we secure the configuration files against prying eyes. Remember, the configuration files contain the user/password combination which which to access the ''vmail'' SQL database. The ''vmail_admin'' user has only read rights, and passwords in there are encrypted, but nevertheless, this is information we need to protect. Thus: chown root:postfix /etc/postfix/mysql-*.cf chmod u=rw,g=r,o= /etc/postfix/mysql-*.cf This protects all four configuration files since only root can write them, members of group ''postfix'' can read them, and the rest of the world cannot access them at all. ==Configuring mail delivery through Dovecot LDA== E-mails get delivered to the virtual mailboxes by means of a Mail Delivery Agent (MDA). With Postfix, the standard MDA for delivery to virtual mailboxes is called ''virtual'', but we're not going to use that; we're going to use ''[http://wiki.dovecot.org/LDA Dovecot LDA]'', which is a program called ''deliver''. By the way, the abbreviation LDA stands for Local Delivery Agent, which of course means more or less the same as MDA. To make Postfix use Dovecot LDA, we add the following line to ''/etc/postfix/master.cf'': dovecot unix - n n - - pipe flags=DRhu user=vmail:vmail argv=/usr/lib/dovecot/deliver -d ${recipient} This declares the service "dovecot" to mean using the program ''/usr/lib/dovecot/deliver'' with the right parameters. If we now let Postfix reload its files, it'll learn about this new service. Subsequently we can instruct Postfix to start using it, by declaring service "dovecot" to be the virtual transport of choice, and specifying one Dovecot-specific variable: postfix reload postconf -e virtual_transport=dovecot postconf -e dovecot_destination_recipient_limit=1 Now to configure Dovecot itself: open ''/etc/dovecot/dovecot.conf'' with your favourite editor [[vim]]; first make sure the ''protocols ='' line reads protocols = imap imaps pop3 pop3s (which it should by default). The second setting is quite crucial. By default, the location of the mail directories is found automatically by Dovecot, but here that won't work. Find the line that reads ''#maildir_location ='', and change it to mail_location = maildir:/data/vmail/%d/%n/Maildir This will look for mail in directory ''/data/vmail/'''DOMAIN'''/'''USER'''/Maildir'', and expect this directory to be in "maildir" format. Next look for a section called "auth default". First define the allowed authentication mechanisms: mechanisms = plain login Then inside that same section you need to uncomment: passdb sql { args = /etc/dovecot/dovecot-sql.conf } which tells Dovecot that the passwords are stored in an SQL database (it's obvious that we'll now have to create this conf-file) and: userdb static { args = uid=120 gid=120 home=/data/vmail/%d/%n allow_all_users=yes } to tell Dovecot where the mailboxes are located. This is similar to the ''mail_location'' setting. Next task: comment out the section ''passdb pam'', so that Dovecot doesn't accidentally try to service local users as well. Next up: tell Dovecot to handle IMAP the same as previous versions of this virtual mailserver have - this can prove to be quite tricky if you already have mailboxes full of mail, put there by e.g. Courier-IMAP. What works for us, is namespace private { separator = . prefix = inbox = yes } However, your mileage may vary. You'll also want to comment out the ''passdb pam'' sections, since we're not hosting mail for local users. Next up, we'll edit the section ''socket listen'' so that Dovecot can access the user database (master section), and our Postfix mailserver can access Dovecot (client section): socket listen { master { path = /var/run/dovecot/auth-master mode = 0600 user = vmail } client { path = /var/spool/postfix/private/auth mode = 0660 user = postfix group = postfix } } Finally, the protocol section, where we specify log files, an address to put in mails when we send out nondelivery reports, and a place to store scripts: protocol lda { log_path = /var/log/appslog/mail/dovecot-deliver.log auth_socket_path = /var/run/dovecot/auth-master postmaster_address = postmaster@saruman.biz mail_plugins = cmusieve global_script_path = /data/vmail/globalsieverc } Now that we've finished the Dovecot configuration file, we need to create a fitting MySQL configuration file for Dovecot. The file is ''/etc/dovecot/dovecot-sql.conf'', and its contents are driver = mysql connect = host=127.0.0.1 dbname=vmail user=vmail_admin password=SuperSecret default_pass_scheme = PLAIN-MD5 password_query = SELECT email as user, passwd as password FROM view_users WHERE email='%u'; When you've created this file (as root), change the attributes of ''dovecot-sql.conf'' and ''dovecot.conf'', and then restart Dovecot to start using the new configuration. Note: ''dovecot.conf'' needs to be read by Postfix, hence the group ownership for the file. chmod u=rw,g=,o= /etc/dovecot/dovecot-sql.conf chgrp vmail /etc/dovecot/dovecot.conf chmod u=rw,g=r,o= /etc/dovecot/dovecot.conf /etc/init.d/dovecot restart ==Finishing up== This is a good moment to test your configuration, if you haven't been able to test your work inbetween. If everything works as expected, you can add bells and whistles to your configuration. The first one we'd like to present covers the way Postfix handles incoming connections. Since authentication works, we can have Postfix distrust every (unauthenticated) connection: postconf -e mynetworks= Furthermore, since a default SSL certificate is installed by the Debian Postfix installation routine, we can encrypt all our connections using TLS; we enforce this using postconf -e smtpd_use_tls=yes postconf -e smtpd_tls_auth_only=yes Of course, you need to adjust the settings of your IMAP client so that it properly uses TLS and properly authenticates itself. If everything ''still'' works after these changes, then congratulations, you now have a powerful, flexible and pretty secure mail setup. Of course, there are always points for improvements. We'll cover these in separate pages. Two pages that we want to direct you to now, are * [[Creating_digital_certificates_with_our_root_certificate | Creating a custom SSL certificate]] for our mail server * [[Antispam measures]] for our Postfix mailserver 1f1a42aa94c8710b19dd6d3981c7df9c03d2915d 0 1490 1957 2008-10-30T20:58:36Z Saruman! 2 DB creation script wikitext text/x-wiki USE mysql; REPLACE INTO user (host, user, password) VALUES ( 'localhost', 'vmail_admin', PASSWORD('SuperSecret') ); REPLACE INTO db (host, db, user, select_priv, insert_priv, update_priv, delete_priv, create_priv, drop_priv, index_priv) VALUES ( 'localhost', 'vmail', 'vmail_admin', 'Y', 'Y', 'Y', 'Y', 'Y', 'Y', 'Y' ); -- Make sure that priviliges are reloaded. FLUSH PRIVILEGES; -- we're assuming the database does not exist yet CREATE DATABASE vmail; USE vmail; CREATE TABLE domains ( domain VARCHAR(50) NOT NULL, PRIMARY KEY (domain) ) TYPE=MyISAM; CREATE TABLE forwardings ( source VARCHAR(80) NOT NULL, destination TEXT NOT NULL, PRIMARY KEY (source) ) TYPE=MyISAM; CREATE TABLE users ( emailaddr VARCHAR(80) NOT NULL, passwd VARCHAR(30) NOT NULL, PRIMARY KEY (emailaddr) ) TYPE=MyISAM; CREATE TABLE relaydomains ( rdomain VARCHAR(80) NOT NULL, transport VARCHAR(80) NOT NULL, PRIMARY KEY (rdomain) ) TYPE=MyISAM; FLUSH PRIVILEGES; 2edbe6cfb715f1f518c35b65d624ea2b9ac64665 1958 1957 2008-10-30T21:04:36Z Saruman! 2 limited vmal_admin rights wikitext text/x-wiki USE mysql; REPLACE INTO user (host, user, password) VALUES ( 'localhost', 'vmail_admin', PASSWORD('SuperSecret') ); REPLACE INTO db (host, db, user, select_priv) VALUES ( 'localhost', 'vmail', 'vmail_admin', 'Y' ); -- Make sure that priviliges are reloaded. FLUSH PRIVILEGES; -- we're assuming the database does not exist yet CREATE DATABASE vmail; USE vmail; CREATE TABLE domains ( domain VARCHAR(50) NOT NULL, PRIMARY KEY (domain) ) TYPE=MyISAM; CREATE TABLE forwardings ( source VARCHAR(80) NOT NULL, destination TEXT NOT NULL, PRIMARY KEY (source) ) TYPE=MyISAM; CREATE TABLE users ( emailaddr VARCHAR(80) NOT NULL, passwd VARCHAR(30) NOT NULL, PRIMARY KEY (emailaddr) ) TYPE=MyISAM; CREATE TABLE relaydomains ( rdomain VARCHAR(80) NOT NULL, transport VARCHAR(80) NOT NULL, PRIMARY KEY (rdomain) ) TYPE=MyISAM; FLUSH PRIVILEGES; adf01b425f6cd0f83817e682ec5dd737a63603b8 1959 1958 2008-10-31T00:01:53Z Saruman! 2 Updated to MySQL5.0, InnoDB and relational tables wikitext text/x-wiki USE mysql; REPLACE INTO user (host, user, password) VALUES ( 'localhost', 'vmail_admin', PASSWORD('SuperSecret') ); REPLACE INTO db (host, db, user, select_priv) VALUES ( 'localhost', 'vmail', 'vmail_admin', 'Y' ); -- Make sure that priviliges are reloaded. FLUSH PRIVILEGES; -- You should drop a pre-existing "vmail" -- database manually to avoid CREATE errors. CREATE DATABASE vmail; USE vmail; CREATE TABLE virtual_domains ( id INT NOT NULL AUTO_INCREMENT PRIMARY KEY, vdomain VARCHAR(50) NOT NULL ) ENGINE = InnoDB; CREATE TABLE relaydomains ( id INT NOT NULL AUTO_INCREMENT PRIMARY KEY, relaydomain VARCHAR(80) NOT NULL, transport VARCHAR(80) NOT NULL ) ENGINE = InnoDB; CREATE TABLE virtual_users ( id INT(11) NOT NULL AUTO_INCREMENT PRIMARY KEY, domain_id INT(11) NOT NULL, user VARCHAR(40) NOT NULL, passwd VARCHAR(32) NOT NULL ) ENGINE = InnoDB; CREATE TABLE virtual_aliases ( id INT(11) NOT NULL AUTO_INCREMENT PRIMARY KEY, domain_id INT(11) NOT NULL, source VARCHAR(80) NOT NULL, destination VARCHAR(80) NOT NULL, FOREIGN KEY (domain_id) REFERENCES virtual_domains(id) ON DELETE CASCADE ) ENGINE = InnoDB; FLUSH PRIVILEGES; 94ec318c6271e4286c260548415cfc53b17c0596 1960 1959 2008-10-31T00:08:34Z Saruman! 2 Added output description wikitext text/x-wiki USE mysql; REPLACE INTO user (host, user, password) VALUES ( 'localhost', 'vmail_admin', PASSWORD('SuperSecret') ); REPLACE INTO db (host, db, user, select_priv) VALUES ( 'localhost', 'vmail', 'vmail_admin', 'Y' ); -- Make sure that priviliges are reloaded. FLUSH PRIVILEGES; -- You should drop a pre-existing "vmail" -- database manually to avoid CREATE errors. CREATE DATABASE vmail; USE vmail; CREATE TABLE virtual_domains ( id INT NOT NULL AUTO_INCREMENT PRIMARY KEY, vdomain VARCHAR(50) NOT NULL ) ENGINE = InnoDB; CREATE TABLE relaydomains ( id INT NOT NULL AUTO_INCREMENT PRIMARY KEY, relaydomain VARCHAR(80) NOT NULL, transport VARCHAR(80) NOT NULL ) ENGINE = InnoDB; CREATE TABLE virtual_users ( id INT(11) NOT NULL AUTO_INCREMENT PRIMARY KEY, domain_id INT(11) NOT NULL, user VARCHAR(40) NOT NULL, passwd VARCHAR(32) NOT NULL ) ENGINE = InnoDB; CREATE TABLE virtual_aliases ( id INT(11) NOT NULL AUTO_INCREMENT PRIMARY KEY, domain_id INT(11) NOT NULL, source VARCHAR(80) NOT NULL, destination VARCHAR(80) NOT NULL, FOREIGN KEY (domain_id) REFERENCES virtual_domains(id) ON DELETE CASCADE ) ENGINE = InnoDB; FLUSH PRIVILEGES; Using this script to create the ''vmail'' database should result in the following database (log into ''mysql'' as a root user, and type the commands shown after ''mysql>'' to check): mysql> show databases; +--------------------+ | Database | +--------------------+ | information_schema | | mysql | | vmail | +--------------------+ 3 rows in set mysql> use vmail; Database changed mysql> show tables; +-----------------+ | Tables_in_vmail | +-----------------+ | relaydomains | | virtual_aliases | | virtual_domains | | virtual_users | +-----------------+ 4 rows in set mysql> describe relaydomains; +-------------+-------------+------+-----+---------+----------------+ | Field | Type | Null | Key | Default | Extra | +-------------+-------------+------+-----+---------+----------------+ | id | int(11) | NO | PRI | NULL | auto_increment | | relaydomain | varchar(80) | NO | | NULL | | | transport | varchar(80) | NO | | NULL | | +-------------+-------------+------+-----+---------+----------------+ 3 rows in set mysql> describe virtual_aliases; +-------------+-------------+------+-----+---------+----------------+ | Field | Type | Null | Key | Default | Extra | +-------------+-------------+------+-----+---------+----------------+ | id | int(11) | NO | PRI | NULL | auto_increment | | domain_id | int(11) | NO | MUL | NULL | | | source | varchar(80) | NO | | NULL | | | destination | varchar(80) | NO | | NULL | | +-------------+-------------+------+-----+---------+----------------+ 4 rows in set mysql> describe virtual_domains; +---------+-------------+------+-----+---------+----------------+ | Field | Type | Null | Key | Default | Extra | +---------+-------------+------+-----+---------+----------------+ | id | int(11) | NO | PRI | NULL | auto_increment | | vdomain | varchar(50) | NO | | NULL | | +---------+-------------+------+-----+---------+----------------+ 2 rows in set mysql> describe virtual_users; +-----------+-------------+------+-----+---------+----------------+ | Field | Type | Null | Key | Default | Extra | +-----------+-------------+------+-----+---------+----------------+ | id | int(11) | NO | PRI | NULL | auto_increment | | domain_id | int(11) | NO | | NULL | | | user | varchar(40) | NO | | NULL | | | passwd | varchar(32) | NO | | NULL | | +-----------+-------------+------+-----+---------+----------------+ 4 rows in set 5cd3a9e2b1c72aa42bb4aef9265528a38af04e94 1970 1960 2008-11-01T09:46:05Z Saruman! 2 added view_users wikitext text/x-wiki USE mysql; REPLACE INTO user (host, user, password) VALUES ( 'localhost', 'vmail_admin', PASSWORD('SuperSecret') ); REPLACE INTO db (host, db, user, select_priv) VALUES ( 'localhost', 'vmail', 'vmail_admin', 'Y' ); -- Make sure that priviliges are reloaded. FLUSH PRIVILEGES; -- You should drop a pre-existing "vmail" -- database manually to avoid CREATE errors. CREATE DATABASE vmail; USE vmail; CREATE TABLE virtual_domains ( id INT NOT NULL AUTO_INCREMENT PRIMARY KEY, vdomain VARCHAR(50) NOT NULL ) ENGINE = InnoDB; CREATE TABLE relaydomains ( id INT NOT NULL AUTO_INCREMENT PRIMARY KEY, relaydomain VARCHAR(80) NOT NULL, transport VARCHAR(80) NOT NULL ) ENGINE = InnoDB; CREATE TABLE virtual_users ( id INT(11) NOT NULL AUTO_INCREMENT PRIMARY KEY, domain_id INT(11) NOT NULL, user VARCHAR(40) NOT NULL, passwd VARCHAR(32) NOT NULL ) ENGINE = InnoDB; CREATE TABLE virtual_aliases ( id INT(11) NOT NULL AUTO_INCREMENT PRIMARY KEY, domain_id INT(11) NOT NULL, source VARCHAR(80) NOT NULL, destination VARCHAR(80) NOT NULL, FOREIGN KEY (domain_id) REFERENCES virtual_domains(id) ON DELETE CASCADE ) ENGINE = InnoDB; FLUSH PRIVILEGES; CREATE VIEW view_users AS SELECT CONCAT(virtual_users.user, '@', virtual_domains.vdomain) AS email, virtual_users.passwd FROM virtual_users LEFT JOIN virtual_domains ON virtual_users.domain_id=virtual_domains.id; Using this script to create the ''vmail'' database should result in the following database (log into ''mysql'' as a root user, and type the commands shown after ''mysql>'' to check): mysql> show databases; +--------------------+ | Database | +--------------------+ | information_schema | | mysql | | vmail | +--------------------+ 3 rows in set mysql> use vmail; Database changed mysql> show tables; +-----------------+ | Tables_in_vmail | +-----------------+ | relaydomains | | view_users | | virtual_aliases | | virtual_domains | | virtual_users | +-----------------+ 5 rows in set mysql> describe relaydomains; +-------------+-------------+------+-----+---------+----------------+ | Field | Type | Null | Key | Default | Extra | +-------------+-------------+------+-----+---------+----------------+ | id | int(11) | NO | PRI | NULL | auto_increment | | relaydomain | varchar(80) | NO | | NULL | | | transport | varchar(80) | NO | | NULL | | +-------------+-------------+------+-----+---------+----------------+ 3 rows in set describe view_users; +--------+-------------+------+-----+---------+-------+ | Field | Type | Null | Key | Default | Extra | +--------+-------------+------+-----+---------+-------+ | email | varchar(91) | YES | | NULL | | | passwd | varchar(32) | NO | | NULL | | +--------+-------------+------+-----+---------+-------+ 2 rows in set mysql> describe virtual_aliases; +-------------+-------------+------+-----+---------+----------------+ | Field | Type | Null | Key | Default | Extra | +-------------+-------------+------+-----+---------+----------------+ | id | int(11) | NO | PRI | NULL | auto_increment | | domain_id | int(11) | NO | MUL | NULL | | | source | varchar(80) | NO | | NULL | | | destination | varchar(80) | NO | | NULL | | +-------------+-------------+------+-----+---------+----------------+ 4 rows in set mysql> describe virtual_domains; +---------+-------------+------+-----+---------+----------------+ | Field | Type | Null | Key | Default | Extra | +---------+-------------+------+-----+---------+----------------+ | id | int(11) | NO | PRI | NULL | auto_increment | | vdomain | varchar(50) | NO | | NULL | | +---------+-------------+------+-----+---------+----------------+ 2 rows in set mysql> describe virtual_users; +-----------+-------------+------+-----+---------+----------------+ | Field | Type | Null | Key | Default | Extra | +-----------+-------------+------+-----+---------+----------------+ | id | int(11) | NO | PRI | NULL | auto_increment | | domain_id | int(11) | NO | | NULL | | | user | varchar(40) | NO | | NULL | | | passwd | varchar(32) | NO | | NULL | | +-----------+-------------+------+-----+---------+----------------+ 4 rows in set 8dd19fe2fb73b21756a9dcacac3a6bfc40bb8320 1972 1970 2008-11-01T11:58:56Z Saruman! 2 added view_aliases wikitext text/x-wiki USE mysql; REPLACE INTO user (host, user, password) VALUES ( 'localhost', 'vmail_admin', PASSWORD('SuperSecret') ); REPLACE INTO db (host, db, user, select_priv) VALUES ( 'localhost', 'vmail', 'vmail_admin', 'Y' ); -- Make sure that priviliges are reloaded. FLUSH PRIVILEGES; -- You should drop a pre-existing "vmail" -- database manually to avoid CREATE errors. CREATE DATABASE vmail; USE vmail; CREATE TABLE virtual_domains ( id INT NOT NULL AUTO_INCREMENT PRIMARY KEY, vdomain VARCHAR(50) NOT NULL ) ENGINE = InnoDB; CREATE TABLE relaydomains ( id INT NOT NULL AUTO_INCREMENT PRIMARY KEY, relaydomain VARCHAR(80) NOT NULL, transport VARCHAR(80) NOT NULL ) ENGINE = InnoDB; CREATE TABLE virtual_users ( id INT(11) NOT NULL AUTO_INCREMENT PRIMARY KEY, domain_id INT(11) NOT NULL, user VARCHAR(40) NOT NULL, passwd VARCHAR(32) NOT NULL ) ENGINE = InnoDB; CREATE TABLE virtual_aliases ( id INT(11) NOT NULL AUTO_INCREMENT PRIMARY KEY, domain_id INT(11) NOT NULL, source VARCHAR(80) NOT NULL, destination VARCHAR(80) NOT NULL, FOREIGN KEY (domain_id) REFERENCES virtual_domains(id) ON DELETE CASCADE ) ENGINE = InnoDB; FLUSH PRIVILEGES; CREATE VIEW view_users AS SELECT CONCAT(virtual_users.user, '@', virtual_domains.vdomain) AS email, virtual_users.passwd FROM virtual_users LEFT JOIN virtual_domains ON virtual_users.domain_id=virtual_domains.id; CREATE VIEW view_aliases AS SELECT CONCAT(virtual_aliases.source, '@', virtual_domains.vdomain) AS email, destination FROM virtual_aliases LEFT JOIN virtual_domains ON virtual_aliases.domain_id=virtual_domains.id; Using this script to create the ''vmail'' database should result in the following database (log into ''mysql'' as a root user, and type the commands shown after ''mysql>'' to check): mysql> show databases; +--------------------+ | Database | +--------------------+ | information_schema | | mysql | | vmail | +--------------------+ 3 rows in set mysql> use vmail; Database changed mysql> show tables; +-----------------+ | Tables_in_vmail | +-----------------+ | relaydomains | | view_users | | virtual_aliases | | virtual_domains | | virtual_users | +-----------------+ 5 rows in set mysql> describe relaydomains; +-------------+-------------+------+-----+---------+----------------+ | Field | Type | Null | Key | Default | Extra | +-------------+-------------+------+-----+---------+----------------+ | id | int(11) | NO | PRI | NULL | auto_increment | | relaydomain | varchar(80) | NO | | NULL | | | transport | varchar(80) | NO | | NULL | | +-------------+-------------+------+-----+---------+----------------+ 3 rows in set describe view_users; +--------+-------------+------+-----+---------+-------+ | Field | Type | Null | Key | Default | Extra | +--------+-------------+------+-----+---------+-------+ | email | varchar(91) | YES | | NULL | | | passwd | varchar(32) | NO | | NULL | | +--------+-------------+------+-----+---------+-------+ 2 rows in set mysql> describe virtual_aliases; +-------------+-------------+------+-----+---------+----------------+ | Field | Type | Null | Key | Default | Extra | +-------------+-------------+------+-----+---------+----------------+ | id | int(11) | NO | PRI | NULL | auto_increment | | domain_id | int(11) | NO | MUL | NULL | | | source | varchar(80) | NO | | NULL | | | destination | varchar(80) | NO | | NULL | | +-------------+-------------+------+-----+---------+----------------+ 4 rows in set mysql> describe virtual_domains; +---------+-------------+------+-----+---------+----------------+ | Field | Type | Null | Key | Default | Extra | +---------+-------------+------+-----+---------+----------------+ | id | int(11) | NO | PRI | NULL | auto_increment | | vdomain | varchar(50) | NO | | NULL | | +---------+-------------+------+-----+---------+----------------+ 2 rows in set mysql> describe virtual_users; +-----------+-------------+------+-----+---------+----------------+ | Field | Type | Null | Key | Default | Extra | +-----------+-------------+------+-----+---------+----------------+ | id | int(11) | NO | PRI | NULL | auto_increment | | domain_id | int(11) | NO | | NULL | | | user | varchar(40) | NO | | NULL | | | passwd | varchar(32) | NO | | NULL | | +-----------+-------------+------+-----+---------+----------------+ 4 rows in set e6ae599cf1f1dbefbf2972fe200a1f7cffc881e5 1973 1972 2008-11-01T12:03:49Z Saruman! 2 added describe view_aliases wikitext text/x-wiki USE mysql; REPLACE INTO user (host, user, password) VALUES ( 'localhost', 'vmail_admin', PASSWORD('SuperSecret') ); REPLACE INTO db (host, db, user, select_priv) VALUES ( 'localhost', 'vmail', 'vmail_admin', 'Y' ); -- Make sure that priviliges are reloaded. FLUSH PRIVILEGES; -- You should drop a pre-existing "vmail" -- database manually to avoid CREATE errors. CREATE DATABASE vmail; USE vmail; CREATE TABLE virtual_domains ( id INT NOT NULL AUTO_INCREMENT PRIMARY KEY, vdomain VARCHAR(50) NOT NULL ) ENGINE = InnoDB; CREATE TABLE relaydomains ( id INT NOT NULL AUTO_INCREMENT PRIMARY KEY, relaydomain VARCHAR(80) NOT NULL, transport VARCHAR(80) NOT NULL ) ENGINE = InnoDB; CREATE TABLE virtual_users ( id INT(11) NOT NULL AUTO_INCREMENT PRIMARY KEY, domain_id INT(11) NOT NULL, user VARCHAR(40) NOT NULL, passwd VARCHAR(32) NOT NULL ) ENGINE = InnoDB; CREATE TABLE virtual_aliases ( id INT(11) NOT NULL AUTO_INCREMENT PRIMARY KEY, domain_id INT(11) NOT NULL, source VARCHAR(80) NOT NULL, destination VARCHAR(80) NOT NULL, FOREIGN KEY (domain_id) REFERENCES virtual_domains(id) ON DELETE CASCADE ) ENGINE = InnoDB; FLUSH PRIVILEGES; CREATE VIEW view_users AS SELECT CONCAT(virtual_users.user, '@', virtual_domains.vdomain) AS email, virtual_users.passwd FROM virtual_users LEFT JOIN virtual_domains ON virtual_users.domain_id=virtual_domains.id; CREATE VIEW view_aliases AS SELECT CONCAT(virtual_aliases.source, '@', virtual_domains.vdomain) AS email, destination FROM virtual_aliases LEFT JOIN virtual_domains ON virtual_aliases.domain_id=virtual_domains.id; Using this script to create the ''vmail'' database should result in the following database (log into ''mysql'' as a root user, and type the commands shown after ''mysql>'' to check): mysql> show databases; +--------------------+ | Database | +--------------------+ | information_schema | | mysql | | vmail | +--------------------+ 3 rows in set mysql> use vmail; Database changed mysql> show tables; +-----------------+ | Tables_in_vmail | +-----------------+ | relaydomains | | view_aliases | | view_users | | virtual_aliases | | virtual_domains | | virtual_users | +-----------------+ 6 rows in set mysql> describe relaydomains; +-------------+-------------+------+-----+---------+----------------+ | Field | Type | Null | Key | Default | Extra | +-------------+-------------+------+-----+---------+----------------+ | id | int(11) | NO | PRI | NULL | auto_increment | | relaydomain | varchar(80) | NO | | NULL | | | transport | varchar(80) | NO | | NULL | | +-------------+-------------+------+-----+---------+----------------+ 3 rows in set mysql> describe view_aliases; +-------------+--------------+------+-----+---------+-------+ | Field | Type | Null | Key | Default | Extra | +-------------+--------------+------+-----+---------+-------+ | email | varchar(131) | YES | | NULL | | | destination | varchar(80) | NO | | NULL | | +-------------+--------------+------+-----+---------+-------+ 2 rows in set mysql> describe view_users; +--------+-------------+------+-----+---------+-------+ | Field | Type | Null | Key | Default | Extra | +--------+-------------+------+-----+---------+-------+ | email | varchar(91) | YES | | NULL | | | passwd | varchar(32) | NO | | NULL | | +--------+-------------+------+-----+---------+-------+ 2 rows in set mysql> describe virtual_aliases; +-------------+-------------+------+-----+---------+----------------+ | Field | Type | Null | Key | Default | Extra | +-------------+-------------+------+-----+---------+----------------+ | id | int(11) | NO | PRI | NULL | auto_increment | | domain_id | int(11) | NO | MUL | NULL | | | source | varchar(80) | NO | | NULL | | | destination | varchar(80) | NO | | NULL | | +-------------+-------------+------+-----+---------+----------------+ 4 rows in set mysql> describe virtual_domains; +---------+-------------+------+-----+---------+----------------+ | Field | Type | Null | Key | Default | Extra | +---------+-------------+------+-----+---------+----------------+ | id | int(11) | NO | PRI | NULL | auto_increment | | vdomain | varchar(50) | NO | | NULL | | +---------+-------------+------+-----+---------+----------------+ 2 rows in set mysql> describe virtual_users; +-----------+-------------+------+-----+---------+----------------+ | Field | Type | Null | Key | Default | Extra | +-----------+-------------+------+-----+---------+----------------+ | id | int(11) | NO | PRI | NULL | auto_increment | | domain_id | int(11) | NO | | NULL | | | user | varchar(40) | NO | | NULL | | | passwd | varchar(32) | NO | | NULL | | +-----------+-------------+------+-----+---------+----------------+ 4 rows in set 8c89fff4ca448514660c65e635088160eebbe9a2 0 1491 1984 2008-11-04T20:59:21Z Insomnia 3 Make a initrd ramdrive wikitext text/x-wiki Most kernels use a ramdrive to load the modules the need to boot. This is called a initrd image. To make such a ramdrive mkinitramfs -k -o /boot/initrd.img-2.6.27.4 2.6.27.4 And to update grub and use the ramdrive update-grub 747b16ef756baff6861f819c4c258d4715c60626 0 1492 1986 2008-11-05T10:28:25Z Saruman! 2 Created article structure wikitext text/x-wiki '''Pluggable Authentication Modules for Linux''' (Linux-PAM) is a great way to fit your Linux server with authentication-related services. However, we found their use pretty difficult, due to some aspects of PAM not being as obvious as the tutorial and howto-writers apparently expect. Thus, we here try to explain [[SaruWiki:About | ourselves]] (and you, dear reader) how PAM works. =PAM introduction= ==What is PAM== First the well-known basics. Free from the PAM admin guide: Linux-PAM is a suite of shared libraries. Using these libraries, the local system administrator can specify how (PAM-aware) applications authenticate users. In other words, if an application or service is PAM-aware, then it is possible to switch between the authentication mechanism(s) it uses without (rewriting and) recompiling it. Indeed, one may entirely upgrade or reconfigure the local authentication system without touching the applications themselves. Historically, an application that required a given user to be authenticated had to be compiled to use a specific authentication mechanism. For example, in the case of traditional UN*X systems, the identity of the user is verified by the user entering a correct password. This password, after being prefixed by a two character "salt", is encrypted (with crypt(3)). The user is then authenticated if this encrypted password is identical to the second field of the user's entry in the system password database (the /etc/passwd file). On such systems, most if not all forms of privileges are granted based on this single authentication scheme. Privilege comes in the form of a personal user-identifier (UID) and membership of various groups. Services and applications are available based on the personal and group identity of the user. Traditionally, group membership has been assigned based on entries in the /etc/group file. It is the purpose of the Linux-PAM project to separate the development of privilege granting software from the development of secure and appropriate authentication schemes. This is accomplished by providing a library of functions that an application may use to request that a user be authenticated. This PAM library is configured locally with a system file, /etc/pam.conf (or a series of configuration files located in /etc/pam.d/) to authenticate a user request via the locally available authentication modules. The modules themselves will usually be located in the directory /lib/security or /lib64/security and take the form of dynamically loadable object files == Why use PAM == = PAM Principles = == Invoking PAM == == PAM modules - in general == == A line of PAM configuration code == == PAM module types == === module type ''auth'' === === module type ''account'' === === module type ''password'' === === module type ''session'' === == PAM control flags == == A line of PAM configuration code - revisited == = PAM on Debian= == PAM modules in Debian 5.0 'Lenny'== == PAM configuration files == = Configuration example= == Configuring PAM for LDAP == e93ec78173340e5cd263408626a0762e4068c77f 1987 1986 2008-11-05T18:36:45Z 194.151.67.13 0 /* What is PAM */ small addition wikitext text/x-wiki '''Pluggable Authentication Modules for Linux''' (Linux-PAM) is a great way to fit your Linux server with authentication-related services. However, we found their use pretty difficult, due to some aspects of PAM not being as obvious as the tutorial and howto-writers apparently expect. Thus, we here try to explain [[SaruWiki:About | ourselves]] (and you, dear reader) how PAM works. =PAM introduction= ==What is PAM== Most Linux applications require authentication of some type or another. For authentication, multiple mechanisms are available, ranging from the standard Linux password through certificates all the way to smartcard readers, fingerprint readers and what have you not. To make use of one (or more) of these mechanisms, there are two main choices: either program the code required to interface with your authentication mechanism of choice, or make use of some framework that can take care of the interfacing with the authentication mechanism for you. It will be clear that programming authentication mechanism support is not usually a smart move; for any new authentication mechanism, as well as for any change in existing ones, you need to reprogram, recompile et cetera. Connecting to a framework on the other hand is a one-time effort, requiring only extra effort if and when the framework itself changes. And here we encounter PAM, because PAM is just such a framework. Free after the PAM admin guide: Linux-PAM is a suite of shared libraries. Using these libraries, the local system administrator can specify how PAM-aware applications authenticate users. In other words, if an application or service is PAM-aware, then it is possible to switch between the authentication mechanism(s) it uses without (rewriting and) recompiling it. Indeed, one may entirely upgrade or reconfigure the local authentication system without touching the applications themselves. Furthermore, the administrative effort associated with authentication managemnet is reduced, since all configuration using the framework is the same for any application using it. In other words: admins have to learn only once to operate the framework, and can then deploy and configure any application using it. Historically, an application that required a given user to be authenticated had to be compiled to use a specific authentication mechanism. For example, in the case of traditional UN*X systems, the identity of the user is verified by the user entering a correct password. This password, after being prefixed by a two character "salt", is encrypted (with crypt(3)). The user is then authenticated if this encrypted password is identical to the second field of the user's entry in the system password database (the /etc/passwd file). On such systems, most if not all forms of privileges are granted based on this single authentication scheme. Privilege comes in the form of a personal user-identifier (UID) and membership of various groups. Services and applications are available based on the personal and group identity of the user. Traditionally, group membership has been assigned based on entries in the /etc/group file. It is the purpose of the Linux-PAM project to separate the development of privilege granting software from the development of secure and appropriate authentication schemes. This is accomplished by providing a library of functions that an application may use to request that a user be authenticated. This PAM library is configured locally with a system file, /etc/pam.conf (or a series of configuration files located in /etc/pam.d/) to authenticate a user request via the locally available authentication modules. The modules themselves will usually be located in the directory /lib/security or /lib64/security and take the form of dynamically loadable object files == Why use PAM == = PAM Principles = == Invoking PAM == == PAM modules - in general == == A line of PAM configuration code == == PAM module types == === module type ''auth'' === === module type ''account'' === === module type ''password'' === === module type ''session'' === == PAM control flags == == A line of PAM configuration code - revisited == = PAM on Debian= == PAM modules in Debian 5.0 'Lenny'== == PAM configuration files == = Configuration example= == Configuring PAM for LDAP == c81f769e271f5af451096d116493636ee142643d 1989 1987 2008-11-05T20:17:59Z Saruman! 2 /* PAM Principles */ - introduction wikitext text/x-wiki '''Pluggable Authentication Modules for Linux''' (Linux-PAM) is a great way to fit your Linux server with authentication-related services. However, we found their use pretty difficult, due to some aspects of PAM not being as obvious as the tutorial and howto-writers apparently expect. Thus, we here try to explain [[SaruWiki:About | ourselves]] (and you, dear reader) how PAM works. =PAM introduction= ==What is PAM== Most Linux applications require authentication of some type or another. For authentication, multiple mechanisms are available, ranging from the standard Linux password through certificates all the way to smartcard readers, fingerprint readers and what have you not. To make use of one (or more) of these mechanisms, there are two main choices: either program the code required to interface with your authentication mechanism of choice, or make use of some framework that can take care of the interfacing with the authentication mechanism for you. It will be clear that programming authentication mechanism support is not usually a smart move; for any new authentication mechanism, as well as for any change in existing ones, you need to reprogram, recompile et cetera. Connecting to a framework on the other hand is a one-time effort, requiring only extra effort if and when the framework itself changes. And here we encounter PAM, because PAM is just such a framework. Free after the PAM admin guide: Linux-PAM is a suite of shared libraries. Using these libraries, the local system administrator can specify how PAM-aware applications authenticate users. In other words, if an application or service is PAM-aware, then it is possible to switch between the authentication mechanism(s) it uses without (rewriting and) recompiling it. Indeed, one may entirely upgrade or reconfigure the local authentication system without touching the applications themselves. Furthermore, the administrative effort associated with authentication managemnet is reduced, since all configuration using the framework is the same for any application using it. In other words: admins have to learn only once to operate the framework, and can then deploy and configure any application using it. Historically, an application that required a given user to be authenticated had to be compiled to use a specific authentication mechanism. For example, in the case of traditional UN*X systems, the identity of the user is verified by the user entering a correct password. This password, after being prefixed by a two character "salt", is encrypted (with crypt(3)). The user is then authenticated if this encrypted password is identical to the second field of the user's entry in the system password database (the /etc/passwd file). On such systems, most if not all forms of privileges are granted based on this single authentication scheme. Privilege comes in the form of a personal user-identifier (UID) and membership of various groups. Services and applications are available based on the personal and group identity of the user. Traditionally, group membership has been assigned based on entries in the /etc/group file. It is the purpose of the Linux-PAM project to separate the development of privilege granting software from the development of secure and appropriate authentication schemes. This is accomplished by providing a library of functions that an application may use to request that a user be authenticated. This PAM library is configured locally with a system file, /etc/pam.conf (or a series of configuration files located in /etc/pam.d/) to authenticate a user request via the locally available authentication modules. The modules themselves will usually be located in the directory /lib/security or /lib64/security and take the form of dynamically loadable object files == Why use PAM == = PAM Principles = == Invoking PAM == As you might expect from the previous texts, you can only use PAM if your application, service, daemon or program is "PAM-aware". This means, that it is coded and compiled to use PAM. Fortunately, in this day and age most applications, daemons et cetera are. However, this presents us with a true problem: that of ''choice''. When your application is PAM-aware, it means that your application can deletate just about any imaginable authentication-task to PAM - which YOU, the system administrator, must achieve by invoking PAM in just the right way. To this end, you must create a PAM configuration file, and fill it with just the right information as to have PAM perform all tasks that you want - and none other. == PAM modules - in general == == A line of PAM configuration code == == PAM module types == === module type ''auth'' === === module type ''account'' === === module type ''password'' === === module type ''session'' === == PAM control flags == == A line of PAM configuration code - revisited == = PAM on Debian= == PAM modules in Debian 5.0 'Lenny'== == PAM configuration files == = Configuration example= == Configuring PAM for LDAP == dc0c99424ac312527674a2dfcdd6941372c7c63e 1992 1989 2008-11-05T20:51:42Z Saruman! 2 added PAM example wikitext text/x-wiki '''Pluggable Authentication Modules for Linux''' (Linux-PAM) is a great way to fit your Linux server with authentication-related services. However, we found their use pretty difficult, due to some aspects of PAM not being as obvious as the tutorial and howto-writers apparently expect. Thus, we here try to explain [[SaruWiki:About | ourselves]] (and you, dear reader) how PAM works. =PAM introduction= ==What is PAM== Most Linux applications require authentication of some type or another. For authentication, multiple mechanisms are available, ranging from the standard Linux password through certificates all the way to smartcard readers, fingerprint readers and what have you not. To make use of one (or more) of these mechanisms, there are two main choices: either program the code required to interface with your authentication mechanism of choice, or make use of some framework that can take care of the interfacing with the authentication mechanism for you. It will be clear that programming authentication mechanism support is not usually a smart move; for any new authentication mechanism, as well as for any change in existing ones, you need to reprogram, recompile et cetera. Connecting to a framework on the other hand is a one-time effort, requiring only extra effort if and when the framework itself changes. And here we encounter PAM, because PAM is just such a framework. Free after the PAM admin guide: Linux-PAM is a suite of shared libraries. Using these libraries, the local system administrator can specify how PAM-aware applications authenticate users. In other words, if an application or service is PAM-aware, then it is possible to switch between the authentication mechanism(s) it uses without (rewriting and) recompiling it. Indeed, one may entirely upgrade or reconfigure the local authentication system without touching the applications themselves. Furthermore, the administrative effort associated with authentication managemnet is reduced, since all configuration using the framework is the same for any application using it. In other words: admins have to learn only once to operate the framework, and can then deploy and configure any application using it. Historically, an application that required a given user to be authenticated had to be compiled to use a specific authentication mechanism. For example, in the case of traditional UN*X systems, the identity of the user is verified by the user entering a correct password. This password, after being prefixed by a two character "salt", is encrypted (with crypt(3)). The user is then authenticated if this encrypted password is identical to the second field of the user's entry in the system password database (the /etc/passwd file). On such systems, most if not all forms of privileges are granted based on this single authentication scheme. Privilege comes in the form of a personal user-identifier (UID) and membership of various groups. Services and applications are available based on the personal and group identity of the user. Traditionally, group membership has been assigned based on entries in the /etc/group file. It is the purpose of the Linux-PAM project to separate the development of privilege granting software from the development of secure and appropriate authentication schemes. This is accomplished by providing a library of functions that an application may use to request that a user be authenticated. This PAM library is configured locally with a system file, /etc/pam.conf (or a series of configuration files located in /etc/pam.d/) to authenticate a user request via the locally available authentication modules. The modules themselves will usually be located in the directory /lib/security or /lib64/security and take the form of dynamically loadable object files == Why use PAM == = PAM Principles = == Invoking PAM == As you might expect from the previous texts, you can only use PAM if your application, service, daemon or program is "PAM-aware". This means, that it is coded and compiled to use PAM. Fortunately, in this day and age most applications, daemons et cetera are. However, this presents us with a true problem: that of ''choice''. When your application is PAM-aware, it means that your application can deletate just about any imaginable authentication-task to PAM - which YOU, the system administrator, must achieve by invoking PAM in just the right way. To this end, you must create a PAM configuration file, and fill it with just the right information as to have PAM perform all tasks that you want - and none other. This is because when a privilege granting application is started that is PAM aware, it activates its attachment to the PAM-API. This activation performs a number of tasks, the most important being the reading of the configuration file (more on that further on). This file list the PAMs (the "PAM modules") that will do the authentication tasks required by this application, and the appropriate behavior of the PAM-API in the event that individual PAMs fail. Now there are several ways to invoke PAM, and which ones are available to us under Debian will be more fully explored in a later section, but for now let's look at one particular method, that is also available under Debian. If we create a file in ''/etc/pam.d/'' with the name of the service that we want to have PAM perform authentication for, then that can contain the necessary PAM configuration lines, and that will be the PAM configuration for that particular service. Does that make sense? No? Then let me give you an example. Suppose we have some service with a name of ''sshd'', and we want that service to use PAM to check if a user that attempts to use the service is actuall allowed to do so. We then create ''/etc/pam.d/sshd'' and fill it with these two lines: auth required pam_unix.so session optional pam_motd.so This means we've now configured the ''sshd'' [[OpenSSH server | SSH daemon]] to use PAM for authentication/authorization. The exact instructions we've provided PAM are: check if the name and password provided to ''sshd'' by a user attempting to log in represent a valid name/password as they occur in our local Linux user account database (''/etc/passwd''). If so, we'll allow access. The second line furthermore shows a user logging in the [[MOTD_file | Message-of-the-day]], if that message exists. Think that that's easy? Almost looks like it, right? But for a real SSH daemon, the file in effect looks more like this: auth required pam_env.so auth required pam_env.so envfile=/etc/default/locale auth sufficient pam_unix.so nullok_secure auth requisite pam_succeed_if.so uid >= 1000 quiet auth sufficient pam_ldap.so use_first_pass auth required pam_deny.so account required pam_access.so account sufficient pam_unix.so account sufficient pam_succeed_if.so uid < 1000 quiet account [default=bad success=ok user_unknown=ignore] pam_ldap.so account required pam_permit.so session required pam_limits.so session required pam_unix.so session required pam_mkhomedir.so skel=/etc/skel/ umask=0022 session optional pam_ldap.so session optional pam_motd.so session optional pam_mail.so standard noenv session required pam_limits.so password sufficient pam_unix.so md5 obscure min=4 nullok try_first_pass password sufficient pam_ldap.so password required pam_deny.so Well that looks a bit more intimidating, doesn't it? Do not worry, we'll explain everything in great detail, so we are quite sure that, once you get to the end of this document, you'll understand what files like this mean. And hopefully, you'll even be able to create or edit your own! == PAM modules - in general == == A line of PAM configuration code == == PAM module types == === module type ''auth'' === === module type ''account'' === === module type ''password'' === === module type ''session'' === == PAM control flags == == A line of PAM configuration code - revisited == = PAM on Debian= == PAM modules in Debian 5.0 'Lenny'== == PAM configuration files == = Configuration example= == Configuring PAM for LDAP == 92c95fd8144a27a6be657606e77329a26ae06c80 1996 1992 2008-11-08T09:02:36Z Saruman! 2 expounded "what is PAM" wikitext text/x-wiki '''Pluggable Authentication Modules for Linux''' (Linux-PAM) is a great way to fit your Linux server with [[Authentication, authorization and privileges | authentication-related]] services. However, we found their use pretty difficult, due to some aspects of PAM not being as obvious as the tutorial and howto-writers apparently expect. Thus, we here try to explain [[SaruWiki:About | ourselves]] (and you, dear reader) how PAM works. =PAM introduction= ==What is PAM== Most Linux applications require [[Authentication, authorization and privileges | authentication]] of some type or another. For [[Authentication, authorization and privileges | authentication]], multiple mechanisms are available, ranging from the standard Linux password through certificates all the way to smartcard readers, fingerprint readers and what have you not. To make use of one (or more) of these mechanisms, there are two main choices: either program the code required to interface with your authentication mechanism of choice, or make use of some framework that can take care of the interfacing with the authentication mechanism for you. Historically, an application that required a given user to be [[Authentication, authorization and privileges | authenticated]] had to be compiled to use a specific authentication mechanism. For example, in the case of traditional UN*X systems, the identity of the user is verified by the user entering a correct password. This password, after being prefixed by a two character "salt", is encrypted (with ''crypt''). The user is then authenticated if this encrypted password is identical to the second field of the user's entry in the system password database (the ''/etc/passwd'' file). On such systems, most if not all forms of [[Authentication, authorization and privileges | privileges]] are granted based on this single authentication scheme. [[Authentication, authorization and privileges | Privilege]] comes in the form of a personal user-identifier (UID) and membership of various groups. Services and applications are available based on the personal and group identity of the user. Traditionally, group membership has been assigned based on entries in the ''/etc/group'' file. This all means, that if you ever want to change something in the way users or groups are stored, then you'll have to rewrite and recompile each and every application that has the support for ''passwd'' and ''group'' hardcoded. And if you wanted to include support for some other authentication mechanism, you'd have to rewrite ''every'' application that's using authentication. Furthermore, the configuration of your authentication mechanism most likely takes place in the configuration file of each individual program. This means different configuration files, probably with different notations, syntax, et cetera. It will be clear that programming authentication mechanism support is not usually a smart move. Enter authentication frameworks. Suppose we create a framework that contains multiple authentication mechanisms, each conveniently shaped in the form of separate modules and libraries. Suppose we have a clearly defined interface, so that any program can easily link to this framework. Programs can then configure their interface to the framework to choose the authentication mechanisms they want themselves, and then delegate the [[Authentication, authorization and privileges | authenticity question]] to this framework; once a user is authenticated (or not), the framework passes the "yes" (or "no") back to the program. This makes connecting to a framework a one-time effort, requiring only extra effort if and when the framework itself changes. And here we encounter PAM, because PAM is just such a framework. Free after the PAM admin guide: Linux-PAM is a suite of shared libraries. Using these libraries, the local system administrator can specify how PAM-aware applications authenticate users. "PAM-aware" in this context means that the application is written to interface with the PAM framework. In other words, if an application or service is PAM-aware, then it is possible to select/combine/switch between the PAM authentication mechanism(s) you want it to use, without (rewriting and) recompiling program code. Indeed, one may entirely upgrade or reconfigure the local authentication system without touching the applications themselves. Furthermore, the administrative effort associated with authentication management is reduced, since all configuration is the same for any application using using the framework. In other words: admins have to learn only once to operate the framework, and can then deploy and configure any application using it. It is the purpose of the Linux-PAM project to separate the development of [[Authentication, authorization and privileges | privilege granting]] software from the development of secure and appropriate authentication schemes. This is accomplished by providing a library of functions that an application may use to request that a user be authenticated. This PAM library is configured locally with a series of configuration files located in ''/etc/pam.d/'' (or a system file, ''/etc/pam.conf'') to authenticate a user request via the locally available authentication modules. The modules themselves will usually be located in the directory ''/lib/security'' or ''/lib64/security'' and take the form of dynamically loadable object files. == Why use PAM == = PAM Principles = == Invoking PAM == As you might expect from the previous texts, you can only use PAM if your application, service, daemon or program is "PAM-aware". This means, that it is coded and compiled to use PAM. Fortunately, in this day and age most applications, daemons et cetera are. However, this presents us with a true problem: that of ''choice''. When your application is PAM-aware, it means that your application can deletate just about any imaginable authentication-task to PAM - which YOU, the system administrator, must achieve by invoking PAM in just the right way. To this end, you must create a PAM configuration file, and fill it with just the right information as to have PAM perform all tasks that you want - and none other. This is because when a privilege granting application is started that is PAM aware, it activates its attachment to the PAM-API. This activation performs a number of tasks, the most important being the reading of the configuration file (more on that further on). This file list the PAMs (the "PAM modules") that will do the authentication tasks required by this application, and the appropriate behavior of the PAM-API in the event that individual PAMs fail. Now there are several ways to invoke PAM, and which ones are available to us under Debian will be more fully explored in a later section, but for now let's look at one particular method, that is also available under Debian. If we create a file in ''/etc/pam.d/'' with the name of the service that we want to have PAM perform authentication for, then that can contain the necessary PAM configuration lines, and that will be the PAM configuration for that particular service. Does that make sense? No? Then let me give you an example. Suppose we have some service with a name of ''sshd'', and we want that service to use PAM to check if a user that attempts to use the service is actuall allowed to do so. We then create ''/etc/pam.d/sshd'' and fill it with these two lines: auth required pam_unix.so session optional pam_motd.so This means we've now configured the ''sshd'' [[OpenSSH server | SSH daemon]] to use PAM for authentication/authorization. The exact instructions we've provided PAM are: check if the name and password provided to ''sshd'' by a user attempting to log in represent a valid name/password as they occur in our local Linux user account database (''/etc/passwd''). If so, we'll allow access. The second line furthermore shows a user logging in the [[MOTD_file | Message-of-the-day]], if that message exists. Think that that's easy? Almost looks like it, right? But for a real SSH daemon, the file in effect looks more like this: auth required pam_env.so auth required pam_env.so envfile=/etc/default/locale auth sufficient pam_unix.so nullok_secure auth requisite pam_succeed_if.so uid >= 1000 quiet auth sufficient pam_ldap.so use_first_pass auth required pam_deny.so account required pam_access.so account sufficient pam_unix.so account sufficient pam_succeed_if.so uid < 1000 quiet account [default=bad success=ok user_unknown=ignore] pam_ldap.so account required pam_permit.so session required pam_limits.so session required pam_unix.so session required pam_mkhomedir.so skel=/etc/skel/ umask=0022 session optional pam_ldap.so session optional pam_motd.so session optional pam_mail.so standard noenv session required pam_limits.so password sufficient pam_unix.so md5 obscure min=4 nullok try_first_pass password sufficient pam_ldap.so password required pam_deny.so Well that looks a bit more intimidating, doesn't it? Do not worry, we'll explain everything in great detail, so we are quite sure that, once you get to the end of this document, you'll understand what files like this mean. And hopefully, you'll even be able to create or edit your own! == PAM modules - in general == == A line of PAM configuration code == == PAM module types == === module type ''auth'' === === module type ''account'' === === module type ''password'' === === module type ''session'' === == PAM control flags == == A line of PAM configuration code - revisited == = PAM on Debian= == PAM modules in Debian 5.0 'Lenny'== == PAM configuration files == = Configuration example= == Configuring PAM for LDAP == dac22e9ac273a1920d64c73f880a6b7bb82d0381 2000 1996 2008-11-08T16:34:48Z Saruman! 2 module types added wikitext text/x-wiki '''Pluggable Authentication Modules for Linux''' (Linux-PAM) is a great way to fit your Linux server with [[Authentication, authorization and privileges | authentication-related]] services. However, we found their use pretty difficult, due to some aspects of PAM not being as obvious as the tutorial and howto-writers apparently expect. Thus, we here try to explain [[SaruWiki:About | ourselves]] (and you, dear reader) how PAM works. =PAM introduction= ==What is PAM== Most Linux applications require [[Authentication, authorization and privileges | authentication]] of some type or another. For [[Authentication, authorization and privileges | authentication]], multiple mechanisms are available, ranging from the standard Linux password through certificates all the way to smartcard readers, fingerprint readers and what have you not. To make use of one (or more) of these mechanisms, there are two main choices: either program the code required to interface with your authentication mechanism of choice, or make use of some framework that can take care of the interfacing with the authentication mechanism for you. Historically, an application that required a given user to be [[Authentication, authorization and privileges | authenticated]] had to be compiled to use a specific authentication mechanism. For example, in the case of traditional UN*X systems, the identity of the user is verified by the user entering a correct password. This password, after being prefixed by a two character "salt", is encrypted (with ''crypt''). The user is then authenticated if this encrypted password is identical to the second field of the user's entry in the system password database (the ''/etc/passwd'' file). On such systems, most if not all forms of [[Authentication, authorization and privileges | privileges]] are granted based on this single authentication scheme. [[Authentication, authorization and privileges | Privilege]] comes in the form of a personal user-identifier (UID) and membership of various groups. Services and applications are available based on the personal and group identity of the user. Traditionally, group membership has been assigned based on entries in the ''/etc/group'' file. This all means, that if you ever want to change something in the way users or groups are stored, then you'll have to rewrite and recompile each and every application that has the support for ''passwd'' and ''group'' hardcoded. And if you wanted to include support for some other authentication mechanism, you'd have to rewrite ''every'' application that's using authentication. Furthermore, the configuration of your authentication mechanism most likely takes place in the configuration file of each individual program. This means different configuration files, probably with different notations, syntax, et cetera. It will be clear that programming authentication mechanism support is not usually a smart move. Enter authentication frameworks. Suppose we create a framework that contains multiple authentication mechanisms, each conveniently shaped in the form of separate modules and libraries. Suppose we have a clearly defined interface, so that any program can easily link to this framework. Programs can then configure their interface to the framework to choose the authentication mechanisms they want themselves, and then delegate the [[Authentication, authorization and privileges | authenticity question]] to this framework; once a user is authenticated (or not), the framework passes the "yes" (or "no") back to the program. This makes connecting to a framework a one-time effort, requiring only extra effort if and when the framework itself changes. And here we encounter PAM, because PAM is just such a framework. Free after the PAM admin guide: Linux-PAM is a suite of shared libraries. Using these libraries, the local system administrator can specify how PAM-aware applications authenticate users. "PAM-aware" in this context means that the application is written to interface with the PAM framework. In other words, if an application or service is PAM-aware, then it is possible to select/combine/switch between the PAM authentication mechanism(s) you want it to use, without (rewriting and) recompiling program code. Indeed, one may entirely upgrade or reconfigure the local authentication system without touching the applications themselves. Furthermore, the administrative effort associated with authentication management is reduced, since all configuration is the same for any application using using the framework. In other words: admins have to learn only once to operate the framework, and can then deploy and configure any application using it. It is the purpose of the Linux-PAM project to separate the development of [[Authentication, authorization and privileges | privilege granting]] software from the development of secure and appropriate authentication schemes. This is accomplished by providing a library of functions that an application may use to request that a user be authenticated. This PAM library is configured locally with a series of configuration files located in ''/etc/pam.d/'' (or a system file, ''/etc/pam.conf'') to authenticate a user request via the locally available authentication modules. The modules themselves will usually be located in the directory ''/lib/security'' or ''/lib64/security'' and take the form of dynamically loadable object files. == Why use PAM == = PAM Principles = == PAM modules - in general == So we have these PAMs (or "PAM modules" as they're also referred to). Each module exists as a single file, usually beginning with ''pam_'' followed by a pretty descriptive name; for example ''pam_deny.so''. Each of these modules can be invoked by an application to answer a question about an authentication attempt. Furthermore, modules can be "stacked", so that you can call several modules sequentially. This makes it possible for an application to consult two different user repositories for a single login attempt: if ''both'' answer that the user is unknown, then the login attempt should probably fail, but if ''one'' of the two answers positively on the authentication request, then the user is authenticated, and the login attempt may continue. PAM has the necessary controls for this. == PAM module types == So our modules can answer questions we have on an authentication request. But we can have several types of questions, like "may this user log in from this particular workstation" or "after logging in, what environment variables should the user get". PAM can handle these questions as well, because there are different types of modules. Or to be more precise: modules can answer questions in one or more categories. Currently, there are four module types, and they are explained below. === module type ''auth'' === ''auth'' type modules can answer [[Authentication, authorization and privileges |authentication requests]]. These are requests of the type "Is the user trying to log on REALLY user ''root''? Please verify using this password." But next to this, ''auth'' PAMs can also check for the application if system conditions are met, like "Is the user logging in from an acceptable device?" or "Is login currenly allowed (i.e. is the file ''/etc/nologin'' absent)?" === module type ''account'' === ''account'' type modules verify additional attributes of the digital identity trying to authenticate; these attributes could be described as "account data". Think of things like "is the user's account not disabled?", "Is the user entitled to accessing the specific resource?" (i.e. entitlement), et cetera. === module type ''password'' === When users can make use of a certain authentication mechanism, then they usually can also make some changes for their entry in that mechanism. For example, if a user can authenticate using a username/password, then he usually can also change his password. These changes can be made through this type of PAM; there usually is one ''password''-type PAM for every authentication method that the system is fitted with. === module type ''session'' === ''session'' type modules don't so much check the user login attempt, but they perform tasks that must be completed before running the actual program or service. ''session'' type modules can load user limits, mount directories, record login data for auditing purposes, or check system resources to see if there are enough resources to support the login attempt. == Invoking PAM == As you might expect from the previous texts, you can only use PAM if your application, service, daemon or program is "PAM-aware". This means, that it is coded and compiled to use PAM. Fortunately, in this day and age most applications, daemons et cetera are. However, this presents us with a true problem: that of ''choice''. When your application is PAM-aware, it means that your application can deletate just about any imaginable authentication-task to PAM - which YOU, the system administrator, must achieve by invoking PAM in just the right way. To this end, you must create a PAM configuration file, and fill it with just the right information as to have PAM perform all tasks that you want - and none other. This is because when a privilege granting application is started that is PAM aware, it activates its attachment to the PAM-API. This activation performs a number of tasks, the most important being the reading of the configuration file (more on that further on). This file list the PAMs (the "PAM modules") that will do the authentication tasks required by this application, and the appropriate behavior of the PAM-API in the event that individual PAMs fail. Now there are several ways to invoke PAM, and which ones are available to us under Debian will be more fully explored in a later section, but for now let's look at one particular method, that is also available under Debian. If we create a file in ''/etc/pam.d/'' with the name of the service that we want to have PAM perform authentication for, then that can contain the necessary PAM configuration lines, and that will be the PAM configuration for that particular service. Does that make sense? No? Then let me give you an example. Suppose we have some service with a name of ''sshd'', and we want that service to use PAM to check if a user that attempts to use the service is actuall allowed to do so. We then create ''/etc/pam.d/sshd'' and fill it with these two lines: auth required pam_unix.so session optional pam_motd.so This means we've now configured the ''sshd'' [[OpenSSH server | SSH daemon]] to use PAM for authentication/authorization. The exact instructions we've provided PAM are: check if the name and password provided to ''sshd'' by a user attempting to log in represent a valid name/password as they occur in our local Linux user account database (''/etc/passwd''). If so, we'll allow access. The second line furthermore shows a user logging in the [[MOTD_file | Message-of-the-day]], if that message exists. Think that that's easy? Almost looks like it, right? But for a real SSH daemon, the file in effect looks more like this: auth required pam_env.so auth required pam_env.so envfile=/etc/default/locale auth sufficient pam_unix.so nullok_secure auth requisite pam_succeed_if.so uid >= 1000 quiet auth sufficient pam_ldap.so use_first_pass auth required pam_deny.so account required pam_access.so account sufficient pam_unix.so account sufficient pam_succeed_if.so uid < 1000 quiet account [default=bad success=ok user_unknown=ignore] pam_ldap.so account required pam_permit.so session required pam_limits.so session required pam_unix.so session required pam_mkhomedir.so skel=/etc/skel/ umask=0022 session optional pam_ldap.so session optional pam_motd.so session optional pam_mail.so standard noenv session required pam_limits.so password sufficient pam_unix.so md5 obscure min=4 nullok try_first_pass password sufficient pam_ldap.so password required pam_deny.so Well that looks a bit more intimidating, doesn't it? Do not worry, we'll explain everything in great detail, so we are quite sure that, once you get to the end of this document, you'll understand what files like this mean. And hopefully, you'll even be able to create or edit your own! == A line of PAM configuration code == == PAM control flags == == A line of PAM configuration code - revisited == = PAM on Debian= == PAM modules in Debian 5.0 'Lenny'== == PAM configuration files == = Configuration example= == Configuring PAM for LDAP == 17a5f0a4c91d2b16d586127a64ef03ff166335d6 2001 2000 2008-11-08T16:57:30Z Saruman! 2 /* PAM modules - in general */ added control flags ref wikitext text/x-wiki '''Pluggable Authentication Modules for Linux''' (Linux-PAM) is a great way to fit your Linux server with [[Authentication, authorization and privileges | authentication-related]] services. However, we found their use pretty difficult, due to some aspects of PAM not being as obvious as the tutorial and howto-writers apparently expect. Thus, we here try to explain [[SaruWiki:About | ourselves]] (and you, dear reader) how PAM works. =PAM introduction= ==What is PAM== Most Linux applications require [[Authentication, authorization and privileges | authentication]] of some type or another. For [[Authentication, authorization and privileges | authentication]], multiple mechanisms are available, ranging from the standard Linux password through certificates all the way to smartcard readers, fingerprint readers and what have you not. To make use of one (or more) of these mechanisms, there are two main choices: either program the code required to interface with your authentication mechanism of choice, or make use of some framework that can take care of the interfacing with the authentication mechanism for you. Historically, an application that required a given user to be [[Authentication, authorization and privileges | authenticated]] had to be compiled to use a specific authentication mechanism. For example, in the case of traditional UN*X systems, the identity of the user is verified by the user entering a correct password. This password, after being prefixed by a two character "salt", is encrypted (with ''crypt''). The user is then authenticated if this encrypted password is identical to the second field of the user's entry in the system password database (the ''/etc/passwd'' file). On such systems, most if not all forms of [[Authentication, authorization and privileges | privileges]] are granted based on this single authentication scheme. [[Authentication, authorization and privileges | Privilege]] comes in the form of a personal user-identifier (UID) and membership of various groups. Services and applications are available based on the personal and group identity of the user. Traditionally, group membership has been assigned based on entries in the ''/etc/group'' file. This all means, that if you ever want to change something in the way users or groups are stored, then you'll have to rewrite and recompile each and every application that has the support for ''passwd'' and ''group'' hardcoded. And if you wanted to include support for some other authentication mechanism, you'd have to rewrite ''every'' application that's using authentication. Furthermore, the configuration of your authentication mechanism most likely takes place in the configuration file of each individual program. This means different configuration files, probably with different notations, syntax, et cetera. It will be clear that programming authentication mechanism support is not usually a smart move. Enter authentication frameworks. Suppose we create a framework that contains multiple authentication mechanisms, each conveniently shaped in the form of separate modules and libraries. Suppose we have a clearly defined interface, so that any program can easily link to this framework. Programs can then configure their interface to the framework to choose the authentication mechanisms they want themselves, and then delegate the [[Authentication, authorization and privileges | authenticity question]] to this framework; once a user is authenticated (or not), the framework passes the "yes" (or "no") back to the program. This makes connecting to a framework a one-time effort, requiring only extra effort if and when the framework itself changes. And here we encounter PAM, because PAM is just such a framework. Free after the PAM admin guide: Linux-PAM is a suite of shared libraries. Using these libraries, the local system administrator can specify how PAM-aware applications authenticate users. "PAM-aware" in this context means that the application is written to interface with the PAM framework. In other words, if an application or service is PAM-aware, then it is possible to select/combine/switch between the PAM authentication mechanism(s) you want it to use, without (rewriting and) recompiling program code. Indeed, one may entirely upgrade or reconfigure the local authentication system without touching the applications themselves. Furthermore, the administrative effort associated with authentication management is reduced, since all configuration is the same for any application using using the framework. In other words: admins have to learn only once to operate the framework, and can then deploy and configure any application using it. It is the purpose of the Linux-PAM project to separate the development of [[Authentication, authorization and privileges | privilege granting]] software from the development of secure and appropriate authentication schemes. This is accomplished by providing a library of functions that an application may use to request that a user be authenticated. This PAM library is configured locally with a series of configuration files located in ''/etc/pam.d/'' (or a system file, ''/etc/pam.conf'') to authenticate a user request via the locally available authentication modules. The modules themselves will usually be located in the directory ''/lib/security'' or ''/lib64/security'' and take the form of dynamically loadable object files. == Why use PAM == = PAM Principles = == PAM modules - in general == So we have these PAMs (or "PAM modules" as they're also referred to). Each module exists as a single file, usually beginning with ''pam_'' followed by a pretty descriptive name; for example ''pam_deny.so''. Each of these modules can be invoked by an application to answer a question about an authentication attempt. Furthermore, modules can be "stacked", so that you can call several modules sequentially. This makes it possible for an application to consult two different user repositories for a single login attempt: if ''both'' answer that the user is unknown, then the login attempt should probably fail, but if ''one'' of the two answers positively on the authentication request, then the user is authenticated, and the login attempt may continue. PAM has the necessary controls for this. These are named "control flags" and are treated further down. == PAM module types == So our modules can answer questions we have on an authentication request. But we can have several types of questions, like "may this user log in from this particular workstation" or "after logging in, what environment variables should the user get". PAM can handle these questions as well, because there are different types of modules. Or to be more precise: modules can answer questions in one or more categories. Currently, there are four module types, and they are explained below. === module type ''auth'' === ''auth'' type modules can answer [[Authentication, authorization and privileges |authentication requests]]. These are requests of the type "Is the user trying to log on REALLY user ''root''? Please verify using this password." But next to this, ''auth'' PAMs can also check for the application if system conditions are met, like "Is the user logging in from an acceptable device?" or "Is login currenly allowed (i.e. is the file ''/etc/nologin'' absent)?" === module type ''account'' === ''account'' type modules verify additional attributes of the digital identity trying to authenticate; these attributes could be described as "account data". Think of things like "is the user's account not disabled?", "Is the user entitled to accessing the specific resource?" (i.e. entitlement), et cetera. === module type ''password'' === When users can make use of a certain authentication mechanism, then they usually can also make some changes for their entry in that mechanism. For example, if a user can authenticate using a username/password, then he usually can also change his password. These changes can be made through this type of PAM; there usually is one ''password''-type PAM for every authentication method that the system is fitted with. === module type ''session'' === ''session'' type modules don't so much check the user login attempt, but they perform tasks that must be completed before running the actual program or service. ''session'' type modules can load user limits, mount directories, record login data for auditing purposes, or check system resources to see if there are enough resources to support the login attempt. == Invoking PAM == As you might expect from the previous texts, you can only use PAM if your application, service, daemon or program is "PAM-aware". This means, that it is coded and compiled to use PAM. Fortunately, in this day and age most applications, daemons et cetera are. However, this presents us with a true problem: that of ''choice''. When your application is PAM-aware, it means that your application can deletate just about any imaginable authentication-task to PAM - which YOU, the system administrator, must achieve by invoking PAM in just the right way. To this end, you must create a PAM configuration file, and fill it with just the right information as to have PAM perform all tasks that you want - and none other. This is because when a privilege granting application is started that is PAM aware, it activates its attachment to the PAM-API. This activation performs a number of tasks, the most important being the reading of the configuration file (more on that further on). This file list the PAMs (the "PAM modules") that will do the authentication tasks required by this application, and the appropriate behavior of the PAM-API in the event that individual PAMs fail. Now there are several ways to invoke PAM, and which ones are available to us under Debian will be more fully explored in a later section, but for now let's look at one particular method, that is also available under Debian. If we create a file in ''/etc/pam.d/'' with the name of the service that we want to have PAM perform authentication for, then that can contain the necessary PAM configuration lines, and that will be the PAM configuration for that particular service. Does that make sense? No? Then let me give you an example. Suppose we have some service with a name of ''sshd'', and we want that service to use PAM to check if a user that attempts to use the service is actuall allowed to do so. We then create ''/etc/pam.d/sshd'' and fill it with these two lines: auth required pam_unix.so session optional pam_motd.so This means we've now configured the ''sshd'' [[OpenSSH server | SSH daemon]] to use PAM for authentication/authorization. The exact instructions we've provided PAM are: check if the name and password provided to ''sshd'' by a user attempting to log in represent a valid name/password as they occur in our local Linux user account database (''/etc/passwd''). If so, we'll allow access. The second line furthermore shows a user logging in the [[MOTD_file | Message-of-the-day]], if that message exists. Think that that's easy? Almost looks like it, right? But for a real SSH daemon, the file in effect looks more like this: auth required pam_env.so auth required pam_env.so envfile=/etc/default/locale auth sufficient pam_unix.so nullok_secure auth requisite pam_succeed_if.so uid >= 1000 quiet auth sufficient pam_ldap.so use_first_pass auth required pam_deny.so account required pam_access.so account sufficient pam_unix.so account sufficient pam_succeed_if.so uid < 1000 quiet account [default=bad success=ok user_unknown=ignore] pam_ldap.so account required pam_permit.so session required pam_limits.so session required pam_unix.so session required pam_mkhomedir.so skel=/etc/skel/ umask=0022 session optional pam_ldap.so session optional pam_motd.so session optional pam_mail.so standard noenv session required pam_limits.so password sufficient pam_unix.so md5 obscure min=4 nullok try_first_pass password sufficient pam_ldap.so password required pam_deny.so Well that looks a bit more intimidating, doesn't it? Do not worry, we'll explain everything in great detail, so we are quite sure that, once you get to the end of this document, you'll understand what files like this mean. And hopefully, you'll even be able to create or edit your own! == A line of PAM configuration code == == PAM control flags == == A line of PAM configuration code - revisited == = PAM on Debian= == PAM modules in Debian 5.0 'Lenny'== == PAM configuration files == = Configuration example= == Configuring PAM for LDAP == f0899db198aa45622259bc613c7aa6168872e034 2002 2001 2008-11-08T17:32:56Z Saruman! 2 /* PAM module types */ explained wikitext text/x-wiki '''Pluggable Authentication Modules for Linux''' (Linux-PAM) is a great way to fit your Linux server with [[Authentication, authorization and privileges | authentication-related]] services. However, we found their use pretty difficult, due to some aspects of PAM not being as obvious as the tutorial and howto-writers apparently expect. Thus, we here try to explain [[SaruWiki:About | ourselves]] (and you, dear reader) how PAM works. =PAM introduction= ==What is PAM== Most Linux applications require [[Authentication, authorization and privileges | authentication]] of some type or another. For [[Authentication, authorization and privileges | authentication]], multiple mechanisms are available, ranging from the standard Linux password through certificates all the way to smartcard readers, fingerprint readers and what have you not. To make use of one (or more) of these mechanisms, there are two main choices: either program the code required to interface with your authentication mechanism of choice, or make use of some framework that can take care of the interfacing with the authentication mechanism for you. Historically, an application that required a given user to be [[Authentication, authorization and privileges | authenticated]] had to be compiled to use a specific authentication mechanism. For example, in the case of traditional UN*X systems, the identity of the user is verified by the user entering a correct password. This password, after being prefixed by a two character "salt", is encrypted (with ''crypt''). The user is then authenticated if this encrypted password is identical to the second field of the user's entry in the system password database (the ''/etc/passwd'' file). On such systems, most if not all forms of [[Authentication, authorization and privileges | privileges]] are granted based on this single authentication scheme. [[Authentication, authorization and privileges | Privilege]] comes in the form of a personal user-identifier (UID) and membership of various groups. Services and applications are available based on the personal and group identity of the user. Traditionally, group membership has been assigned based on entries in the ''/etc/group'' file. This all means, that if you ever want to change something in the way users or groups are stored, then you'll have to rewrite and recompile each and every application that has the support for ''passwd'' and ''group'' hardcoded. And if you wanted to include support for some other authentication mechanism, you'd have to rewrite ''every'' application that's using authentication. Furthermore, the configuration of your authentication mechanism most likely takes place in the configuration file of each individual program. This means different configuration files, probably with different notations, syntax, et cetera. It will be clear that programming authentication mechanism support is not usually a smart move. Enter authentication frameworks. Suppose we create a framework that contains multiple authentication mechanisms, each conveniently shaped in the form of separate modules and libraries. Suppose we have a clearly defined interface, so that any program can easily link to this framework. Programs can then configure their interface to the framework to choose the authentication mechanisms they want themselves, and then delegate the [[Authentication, authorization and privileges | authenticity question]] to this framework; once a user is authenticated (or not), the framework passes the "yes" (or "no") back to the program. This makes connecting to a framework a one-time effort, requiring only extra effort if and when the framework itself changes. And here we encounter PAM, because PAM is just such a framework. Free after the PAM admin guide: Linux-PAM is a suite of shared libraries. Using these libraries, the local system administrator can specify how PAM-aware applications authenticate users. "PAM-aware" in this context means that the application is written to interface with the PAM framework. In other words, if an application or service is PAM-aware, then it is possible to select/combine/switch between the PAM authentication mechanism(s) you want it to use, without (rewriting and) recompiling program code. Indeed, one may entirely upgrade or reconfigure the local authentication system without touching the applications themselves. Furthermore, the administrative effort associated with authentication management is reduced, since all configuration is the same for any application using using the framework. In other words: admins have to learn only once to operate the framework, and can then deploy and configure any application using it. It is the purpose of the Linux-PAM project to separate the development of [[Authentication, authorization and privileges | privilege granting]] software from the development of secure and appropriate authentication schemes. This is accomplished by providing a library of functions that an application may use to request that a user be authenticated. This PAM library is configured locally with a series of configuration files located in ''/etc/pam.d/'' (or a system file, ''/etc/pam.conf'') to authenticate a user request via the locally available authentication modules. The modules themselves will usually be located in the directory ''/lib/security'' or ''/lib64/security'' and take the form of dynamically loadable object files. == Why use PAM == = PAM Principles = == PAM modules - in general == So we have these PAMs (or "PAM modules" as they're also referred to). Each module exists as a single file, usually beginning with ''pam_'' followed by a pretty descriptive name; for example ''pam_deny.so''. Each of these modules can be invoked by an application to answer a question about an authentication attempt. Furthermore, modules can be "stacked", so that you can call several modules sequentially. This makes it possible for an application to consult two different user repositories for a single login attempt: if ''both'' answer that the user is unknown, then the login attempt should probably fail, but if ''one'' of the two answers positively on the authentication request, then the user is authenticated, and the login attempt may continue. PAM has the necessary controls for this. These are named "control flags" and are treated further down. == PAM module types == So our modules can answer questions we have on an authentication request. But we can have several types of questions, like "may this user log in from this particular workstation" or "after logging in, what environment variables should the user get". PAM can handle these questions as well, because there are different types of modules. Or to be more precise: an individual module can address more than one of the module types. For instance pam_unix.so has components which address four module types. Currently, there ''are'' four module types, and they are explained below. === module type ''auth'' === ''auth'' type modules can answer [[Authentication, authorization and privileges |authentication requests]]. These are requests of the type "Is the user trying to log on REALLY user ''root''? Please verify using this password." But next to this, ''auth'' PAMs can also check for the application if system conditions are met, like "Is the user logging in from an acceptable device?" or "Is login currenly allowed (i.e. is the file ''/etc/nologin'' absent)?" Furthermore, this module type can also ''set'' credentials, like Kerberos tickets. === module type ''account'' === ''account'' type modules verify additional attributes of the digital identity trying to authenticate; these attributes could be described as "account data". Think of things like "is the user's account not disabled?", "Is the user entitled to accessing the specific resource?" (i.e. entitlement), et cetera. === module type ''password'' === When users can make use of a certain authentication mechanism, then they usually can also make some changes for their entry in that mechanism. For example, if a user can authenticate using a username/password, then he usually can also change his password. These changes can be made through this type of PAM; there usually is one ''password''-type PAM for every authentication method that the system is fitted with. === module type ''session'' === ''session'' type modules don't so much check the user login attempt, but they perform tasks that must be completed after a user has been authenticated. ''session'' type modules can load user limits, mount (home) directories, record login data for auditing purposes, or check system resources to see if there are enough resources to support the login attempt. == PAM control flags == So if a PAM is called to provide an answer, how do you determine what to do with the answer? To this end, we can -and must- make use of a control flag. These are the four control flags that are available: === control flag ''required'' === This is quite a common control flag. A ''required'' module must be successfully checked in order to allow authentication. If a ''required module'' check fails, the user is not notified until all other modules of the same module type have been checked. === control flag ''requisite'' === A ''requisite'' module must be successfully checked in order for the authentication to be successful. However, if a ''requisite'' module check fails, the user is notified immediately with a message reflecting the first failed ''required'' or ''requisite'' module. === control flag ''sufficient'' === A ''sufficient'' module check is ignored if it fails. But, if a module flagged ''sufficient'' is successfully checked, and no ''required'' flagged modules above it have failed, then no other modules of this module type are checked and the user is authenticated. === control flag ''optional'' === An ''optional'' module check is always ignored if it fails. And if the module check is successful, it still doesn't play a role in the overall success or failure for that module type. The only time a module flagged as ''optional'' is necessary for successful authentication, is when no other modules of that type have succeeded or failed. ONLY in this case, an ''optional'' module determines the overall PAM authentication for that module type. == Invoking PAM == As you might expect from the previous texts, you can only use PAM if your application, service, daemon or program is "PAM-aware". This means, that it is coded and compiled to use PAM. Fortunately, in this day and age most applications, daemons et cetera are. However, this presents us with a true problem: that of ''choice''. When your application is PAM-aware, it means that your application can deletate just about any imaginable authentication-task to PAM - which YOU, the system administrator, must achieve by invoking PAM in just the right way. To this end, you must create a PAM configuration file, and fill it with just the right information as to have PAM perform all tasks that you want - and none other. This is because when a privilege granting application is started that is PAM aware, it activates its attachment to the PAM-API. This activation performs a number of tasks, the most important being the reading of the configuration file (more on that further on). This file list the PAMs (the "PAM modules") that will do the authentication tasks required by this application, and the appropriate behavior of the PAM-API in the event that individual PAMs fail. Now there are several ways to invoke PAM, and which ones are available to us under Debian will be more fully explored in a later section, but for now let's look at one particular method, that is also available under Debian. If we create a file in ''/etc/pam.d/'' with the name of the service that we want to have PAM perform authentication for, then that can contain the necessary PAM configuration lines, and that will be the PAM configuration for that particular service. Does that make sense? No? Then let me give you an example. Suppose we have some service with a name of ''sshd'', and we want that service to use PAM to check if a user that attempts to use the service is actuall allowed to do so. We then create ''/etc/pam.d/sshd'' and fill it with these two lines: auth required pam_unix.so session optional pam_motd.so This means we've now configured the ''sshd'' [[OpenSSH server | SSH daemon]] to use PAM for authentication/authorization. The exact instructions we've provided PAM are: check if the name and password provided to ''sshd'' by a user attempting to log in represent a valid name/password as they occur in our local Linux user account database (''/etc/passwd''). If so, we'll allow access. The second line furthermore shows a user logging in the [[MOTD_file | Message-of-the-day]], if that message exists. Think that that's easy? Almost looks like it, right? But for a real SSH daemon, the file in effect looks more like this: auth required pam_env.so auth required pam_env.so envfile=/etc/default/locale auth sufficient pam_unix.so nullok_secure auth requisite pam_succeed_if.so uid >= 1000 quiet auth sufficient pam_ldap.so use_first_pass auth required pam_deny.so account required pam_access.so account sufficient pam_unix.so account sufficient pam_succeed_if.so uid < 1000 quiet account [default=bad success=ok user_unknown=ignore] pam_ldap.so account required pam_permit.so session required pam_limits.so session required pam_unix.so session required pam_mkhomedir.so skel=/etc/skel/ umask=0022 session optional pam_ldap.so session optional pam_motd.so session optional pam_mail.so standard noenv session required pam_limits.so password sufficient pam_unix.so md5 obscure min=4 nullok try_first_pass password sufficient pam_ldap.so password required pam_deny.so Well that looks a bit more intimidating, doesn't it? Do not worry, we'll explain everything in great detail, so we are quite sure that, once you get to the end of this document, you'll understand what files like this mean. And hopefully, you'll even be able to create or edit your own! == A line of PAM configuration code == == PAM control flags == == A line of PAM configuration code - revisited == = PAM on Debian= == PAM modules in Debian 5.0 'Lenny'== == PAM configuration files == = Configuration example= == Configuring PAM for LDAP == 8c486e665f6092f8bbbeeecef7b9438b9bcf534e 2003 2002 2008-11-08T21:59:20Z Saruman! 2 /* PAM Principles */ example in place wikitext text/x-wiki '''Pluggable Authentication Modules for Linux''' (Linux-PAM) is a great way to fit your Linux server with [[Authentication, authorization and privileges | authentication-related]] services. However, we found their use pretty difficult, due to some aspects of PAM not being as obvious as the tutorial and howto-writers apparently expect. Thus, we here try to explain [[SaruWiki:About | ourselves]] (and you, dear reader) how PAM works. =PAM introduction= ==What is PAM== Most Linux applications require [[Authentication, authorization and privileges | authentication]] of some type or another. For [[Authentication, authorization and privileges | authentication]], multiple mechanisms are available, ranging from the standard Linux password through certificates all the way to smartcard readers, fingerprint readers and what have you not. To make use of one (or more) of these mechanisms, there are two main choices: either program the code required to interface with your authentication mechanism of choice, or make use of some framework that can take care of the interfacing with the authentication mechanism for you. Historically, an application that required a given user to be [[Authentication, authorization and privileges | authenticated]] had to be compiled to use a specific authentication mechanism. For example, in the case of traditional UN*X systems, the identity of the user is verified by the user entering a correct password. This password, after being prefixed by a two character "salt", is encrypted (with ''crypt''). The user is then authenticated if this encrypted password is identical to the second field of the user's entry in the system password database (the ''/etc/passwd'' file). On such systems, most if not all forms of [[Authentication, authorization and privileges | privileges]] are granted based on this single authentication scheme. [[Authentication, authorization and privileges | Privilege]] comes in the form of a personal user-identifier (UID) and membership of various groups. Services and applications are available based on the personal and group identity of the user. Traditionally, group membership has been assigned based on entries in the ''/etc/group'' file. This all means, that if you ever want to change something in the way users or groups are stored, then you'll have to rewrite and recompile each and every application that has the support for ''passwd'' and ''group'' hardcoded. And if you wanted to include support for some other authentication mechanism, you'd have to rewrite ''every'' application that's using authentication. Furthermore, the configuration of your authentication mechanism most likely takes place in the configuration file of each individual program. This means different configuration files, probably with different notations, syntax, et cetera. It will be clear that programming authentication mechanism support is not usually a smart move. Enter authentication frameworks. Suppose we create a framework that contains multiple authentication mechanisms, each conveniently shaped in the form of separate modules and libraries. Suppose we have a clearly defined interface, so that any program can easily link to this framework. Programs can then configure their interface to the framework to choose the authentication mechanisms they want themselves, and then delegate the [[Authentication, authorization and privileges | authenticity question]] to this framework; once a user is authenticated (or not), the framework passes the "yes" (or "no") back to the program. This makes connecting to a framework a one-time effort, requiring only extra effort if and when the framework itself changes. And here we encounter PAM, because PAM is just such a framework. Free after the PAM admin guide: Linux-PAM is a suite of shared libraries. Using these libraries, the local system administrator can specify how PAM-aware applications authenticate users. "PAM-aware" in this context means that the application is written to interface with the PAM framework. In other words, if an application or service is PAM-aware, then it is possible to select/combine/switch between the PAM authentication mechanism(s) you want it to use, without (rewriting and) recompiling program code. Indeed, one may entirely upgrade or reconfigure the local authentication system without touching the applications themselves. Furthermore, the administrative effort associated with authentication management is reduced, since all configuration is the same for any application using using the framework. In other words: admins have to learn only once to operate the framework, and can then deploy and configure any application using it. It is the purpose of the Linux-PAM project to separate the development of [[Authentication, authorization and privileges | privilege granting]] software from the development of secure and appropriate authentication schemes. This is accomplished by providing a library of functions that an application may use to request that a user be authenticated. This PAM library is configured locally with a series of configuration files located in ''/etc/pam.d/'' (or a system file, ''/etc/pam.conf'') to authenticate a user request via the locally available authentication modules. The modules themselves will usually be located in the directory ''/lib/security'' or ''/lib64/security'' and take the form of dynamically loadable object files. == Why use PAM == = PAM Principles = == PAM modules - in general == So we have these PAMs (or "PAM modules" as they're also referred to). Each module exists as a single file, usually beginning with ''pam_'' followed by a pretty descriptive name; for example ''pam_deny.so''. Each of these modules can be invoked by an application to answer a question about an authentication attempt. Furthermore, modules can be "stacked", so that you can call several modules sequentially. This makes it possible for an application to consult two different user repositories for a single login attempt: if ''both'' answer that the user is unknown, then the login attempt should probably fail, but if ''one'' of the two answers positively on the authentication request, then the user is authenticated, and the login attempt may continue. PAM has the necessary controls for this. These are named "control flags" and are treated further down. == PAM module types == So our modules can answer questions we have on an authentication request. But we can have several types of questions, like "may this user log in from this particular workstation" or "after logging in, what environment variables should the user get". PAM can handle these questions as well, because there are different types of modules. Or to be more precise: an individual module can address more than one of the module types. For instance pam_unix.so has components which address four module types. Currently, there ''are'' four module types, and they are explained below. === module type ''auth'' === ''auth'' type modules can answer [[Authentication, authorization and privileges |authentication requests]]. These are requests of the type "Is the user trying to log on REALLY user ''root''? Please verify using this password." But next to this, ''auth'' PAMs can also check for the application if system conditions are met, like "Is the user logging in from an acceptable device?" or "Is login currenly allowed (i.e. is the file ''/etc/nologin'' absent)?" Furthermore, this module type can also ''set'' credentials, like Kerberos tickets. === module type ''account'' === ''account'' type modules verify additional attributes of the digital identity trying to authenticate; these attributes could be described as "account data". Think of things like "is the user's account not disabled?", "Is the user entitled to accessing the specific resource?" (i.e. entitlement), et cetera. === module type ''password'' === When users can make use of a certain authentication mechanism, then they usually can also make some changes for their entry in that mechanism. For example, if a user can authenticate using a username/password, then he usually can also change his password. These changes can be made through this type of PAM; there usually is one ''password''-type PAM for every authentication method that the system is fitted with. === module type ''session'' === ''session'' type modules don't so much check the user login attempt, but they perform tasks that must be completed after a user has been authenticated. ''session'' type modules can load user limits, mount (home) directories, record login data for auditing purposes, or check system resources to see if there are enough resources to support the login attempt. == PAM control flags == So if a PAM is called to provide an answer, how do you determine what to do with the answer? To this end, we can -and must- make use of a control flag. These are the four control flags that are available: === control flag ''required'' === This is quite a common control flag. A ''required'' module must be successfully checked in order to allow authentication. If a ''required module'' check fails, the user is not notified until all other modules of the same module type have been checked. === control flag ''requisite'' === A ''requisite'' module must be successfully checked in order for the authentication to be successful. However, if a ''requisite'' module check fails, the user is notified immediately with a message reflecting the first failed ''required'' or ''requisite'' module. === control flag ''sufficient'' === A ''sufficient'' module check is ignored if it fails. But, if a module flagged ''sufficient'' is successfully checked, and no ''required'' flagged modules above it have failed, then no other modules of this module type are checked and the user is authenticated. === control flag ''optional'' === An ''optional'' module check is always ignored if it fails. And if the module check is successful, it still doesn't play a role in the overall success or failure for that module type. The only time a module flagged as ''optional'' is necessary for successful authentication, is when no other modules of that type have succeeded or failed. ONLY in this case, an ''optional'' module determines the overall PAM authentication for that module type. == PAM module arguments == PAM can use "arguments" to pass information to a pluggable module during authentication. These arguments allow the PAM configuration files for particular programs to use a common PAM module, but in different ways. For example, the ''pam_userdb.so'' module uses secrets stored in a Berkeley DB file to authenticate the user. Berkeley DB is an open source database system designed to be embedded in many applications to track information. The module takes a "db argument", specifying the Berkeley DB filename to use, which can be different for different services. Thus, the ''pam_userdb.so'' line in a PAM configuration file can look like this: auth required /lib/security/pam_userdb.so db=path/to/file Invalid arguments are ignored, and do not otherwise affect the success or failure of the PAM module. When an invalid argument is passed, an error is usually written to the ''/var/log/messages'' file. However, since the reporting method is controlled by the PAM module itself, you depend on the module having been written correctly to log the error to this file. Usually this is the case, but be aware that exotic PAMs might write to a different location, or not at all. == PAM configuration lines== As was already shown in the previous section, a single line of PAM configuration code consists of the four fields we've now covered, separated by whitespace. The fields are: <module type> <control flag> <PAM> <optional arguments> Multiple arguments can be written one after another, separated by spaces (PAM simply interprets the whole rest of the line after the <PAM> as arguments). You can string lines like this after one another in a PAM configuration file, and the PAM framework will process them one after another at the time of an authentication request. == Invoking PAM == As you might expect from the previous texts, you can only use PAM if your application, service, daemon or program is "PAM-aware". This means, that it is coded and compiled to use PAM. Fortunately, in this day and age most applications, daemons et cetera are. However, this presents us with a true problem: that of ''choice''. When your application is PAM-aware, it means that your application can deletate just about any imaginable authentication-task to PAM - which YOU, the system administrator, must achieve by invoking PAM in just the right way. To this end, you must create a PAM configuration file, and fill it with just the right information as to have PAM perform all tasks that you want - and none other. This is because when a privilege granting application is started that is PAM aware, it activates its attachment to the PAM-API. This activation performs a number of tasks, the most important being the reading of the configuration file (more on that further on). This file list the PAMs (the "PAM modules") that will do the authentication tasks required by this application, and the appropriate behavior of the PAM-API in the event that individual PAMs fail. Now there are several ways to invoke PAM, and which ones are available to us under Debian will be more fully explored in a later section, but for now let's look at one particular method, that is also available under Debian. If we create a file in ''/etc/pam.d/'' with the name of the service that we want to have PAM perform authentication for, then that can contain the necessary PAM configuration lines, and that will be the PAM configuration for that particular service. Does that make sense? No? Then let me give you an example. Suppose we have some service with a name of ''sshd'', and we want that service to use PAM to check if a user that attempts to use the service is actuall allowed to do so. We then create ''/etc/pam.d/sshd'' and fill it with these two lines: auth required pam_unix.so session optional pam_motd.so This means we've now configured the ''sshd'' [[OpenSSH server | SSH daemon]] to use PAM for authentication/authorization. The exact instructions we've provided PAM are: check if the name and password provided to ''sshd'' by a user attempting to log in represent a valid name/password as they occur in our local Linux user account database (''/etc/passwd''). If so, we'll allow access. The second line furthermore shows a user logging in the [[MOTD_file | Message-of-the-day]], if that message exists. Think that that's easy? Almost looks like it, right? But ==An example: sshd configuration file == For a real SSH daemon, the PAM configuration file can look something like this: auth required pam_env.so auth required pam_env.so envfile=/etc/default/locale auth sufficient pam_unix.so nullok_secure auth requisite pam_succeed_if.so uid >= 1000 quiet auth sufficient pam_ldap.so use_first_pass auth required pam_deny.so account required pam_access.so account sufficient pam_unix.so account sufficient pam_succeed_if.so uid < 1000 quiet account [default=bad success=ok user_unknown=ignore] pam_ldap.so account required pam_permit.so session required pam_limits.so session required pam_unix.so session required pam_mkhomedir.so skel=/etc/skel/ umask=0022 session optional pam_ldap.so session optional pam_motd.so session optional pam_mail.so standard noenv session required pam_limits.so password sufficient pam_unix.so md5 obscure min=4 nullok try_first_pass password sufficient pam_ldap.so password required pam_deny.so Well that looks a bit intimidating, doesn't it? Do not worry, we'll explain everything in great detail, so we are quite sure that, once you get to the end of this document, you'll understand what files like this mean. And hopefully, you'll even be able to create or edit your own! In the example, there are five lines that begin with ''auth''. This means that for any authentication request, PAM consults five modules. Let's have a look at what they do: * ''auth required pam_env.so''<br>This line calls the ''pam_env.so'' PAM, which is a module that can ''only'' be called as an ''auth'' module. It is configured using the ''/etc/security/pam_env.conf'' file, and what it does is it sets a number of environmental variables for the user that tries to log in. These variables can be declared in the ''pam_env.conf'' file, and can be used to supply default values for environmental variables that are not (yet) set for the user, and to override other environmental variables for which the administrator wishes to provide different values from what the user might have configured. It's flagged ''required'', so this module must succeed or the user will be denied access. Fortunately, this module will always succeed. * '' auth required pam_env.so envfile=/etc/default/locale''<br>Hey, haven't we seen this one before? It's the same ''pam_env.so'', but now it's reading an ''envfile'', so as to set the variables that are in the file ''locale''. * '' auth sufficient pam_unix.so nullok_secure''<br>This calls the PAM named ''pam_unix.so'' in its authentication mode. The module is flagged ''sufficient'', so if this module recognises the user, then no other ''auth'' module will be consulted - effectively skipping the next three ''auth'' modules. See that order is important?<br>The module will check if the authentication attempt is made by a valid Unix user. The parameter nullok_secure makes sure that even login attempts by users with blank passwords fail, as long as they try to authenticate from a secure terminal * ''auth requisite pam_succeed_if.so uid >= 1000 quiet''<br>This module ''[http://linux.die.net/man/8/pam_succeed_if pam_succeed_if.so]'' brings a rudimentary form of flow control to our PAM configuration files. It can perform tests, and based on that test will cause a "success" or "fail" state to the ''auth'' section - but it WON'T return "success" or "fail" to the authentication attempt itself! Because it is here used with ''requisite'', a failure of this module would immediately be effective. The first argument (or set of arguments) is ''uid >= 1000''. This is the actual test that the module will be performing: if the user that is trying to authenticate has a user ID of LESS than 1000, the module will fail, and the ''requisite'' flag will cause PAM to perform no more ''auth'' module tests. The last argument of this module is a flag ''quiet'', which makes this module skip recording failure or success messages in the message log.<br>So what is now the effect of this module? For ordinary system users (who have an uid of 1000 or more), this module will do just nothing. But if this module is called for an authentication request by a service daemon, then the uid will be less than 1000, so ''pam_succeed_if.so'' will FAIL. The ''requisite'' control flag causes PAM to immediately end the ''auth'' stage of the login; that means all following ''auth'' modules will ONLY be processed for ordinary users, not service daemons. Neat, eh? * ''auth sufficient pam_ldap.so use_first_pass''<br>This module (because of the preceding line never called when daemons try to log in) will attempt to see if the user and password that need to be authenticated are valid in your LDAP server. The ''sufficient'' control flag makes sure that if the user is NOT a valid LDAP user, nothing happens. However, if he is, AND no previous ''auth'' modules have returned an auth failure, then the PAM returns "success" and the ''auth'' phase immediately ends. * ''auth required pam_deny.so''<br>This last ''auth'' module is the catchall; if no previous ''auth'' module of type ''sufficient'' has returned a success, then this module kicks in. And guess what? Called as an ''auth'' module, it ALWAYS returns "failure". The compound effect of this authentication section of the example PAM configuration is this: # Default environmental variables are set # The ''locale'' file is read # All valid Unix users, and Unix users with blank passwords from secure terminals, are authenticated OK # All valid Unix users = PAM on Debian= == PAM modules in Debian 5.0 'Lenny'== == PAM configuration files == = Configuration example= == Configuring PAM for LDAP == 755aecfd7823840072529d0c2d54ee7f5fd5aebf 2013 2003 2008-11-16T11:28:30Z Saruman! 2 /* PAM control flags */ expressions added wikitext text/x-wiki '''Pluggable Authentication Modules for Linux''' (Linux-PAM) is a great way to fit your Linux server with [[Authentication, authorization and privileges | authentication-related]] services. However, we found their use pretty difficult, due to some aspects of PAM not being as obvious as the tutorial and howto-writers apparently expect. Thus, we here try to explain [[SaruWiki:About | ourselves]] (and you, dear reader) how PAM works. =PAM introduction= ==What is PAM== Most Linux applications require [[Authentication, authorization and privileges | authentication]] of some type or another. For [[Authentication, authorization and privileges | authentication]], multiple mechanisms are available, ranging from the standard Linux password through certificates all the way to smartcard readers, fingerprint readers and what have you not. To make use of one (or more) of these mechanisms, there are two main choices: either program the code required to interface with your authentication mechanism of choice, or make use of some framework that can take care of the interfacing with the authentication mechanism for you. Historically, an application that required a given user to be [[Authentication, authorization and privileges | authenticated]] had to be compiled to use a specific authentication mechanism. For example, in the case of traditional UN*X systems, the identity of the user is verified by the user entering a correct password. This password, after being prefixed by a two character "salt", is encrypted (with ''crypt''). The user is then authenticated if this encrypted password is identical to the second field of the user's entry in the system password database (the ''/etc/passwd'' file). On such systems, most if not all forms of [[Authentication, authorization and privileges | privileges]] are granted based on this single authentication scheme. [[Authentication, authorization and privileges | Privilege]] comes in the form of a personal user-identifier (UID) and membership of various groups. Services and applications are available based on the personal and group identity of the user. Traditionally, group membership has been assigned based on entries in the ''/etc/group'' file. This all means, that if you ever want to change something in the way users or groups are stored, then you'll have to rewrite and recompile each and every application that has the support for ''passwd'' and ''group'' hardcoded. And if you wanted to include support for some other authentication mechanism, you'd have to rewrite ''every'' application that's using authentication. Furthermore, the configuration of your authentication mechanism most likely takes place in the configuration file of each individual program. This means different configuration files, probably with different notations, syntax, et cetera. It will be clear that programming authentication mechanism support is not usually a smart move. Enter authentication frameworks. Suppose we create a framework that contains multiple authentication mechanisms, each conveniently shaped in the form of separate modules and libraries. Suppose we have a clearly defined interface, so that any program can easily link to this framework. Programs can then configure their interface to the framework to choose the authentication mechanisms they want themselves, and then delegate the [[Authentication, authorization and privileges | authenticity question]] to this framework; once a user is authenticated (or not), the framework passes the "yes" (or "no") back to the program. This makes connecting to a framework a one-time effort, requiring only extra effort if and when the framework itself changes. And here we encounter PAM, because PAM is just such a framework. Free after the PAM admin guide: Linux-PAM is a suite of shared libraries. Using these libraries, the local system administrator can specify how PAM-aware applications authenticate users. "PAM-aware" in this context means that the application is written to interface with the PAM framework. In other words, if an application or service is PAM-aware, then it is possible to select/combine/switch between the PAM authentication mechanism(s) you want it to use, without (rewriting and) recompiling program code. Indeed, one may entirely upgrade or reconfigure the local authentication system without touching the applications themselves. Furthermore, the administrative effort associated with authentication management is reduced, since all configuration is the same for any application using using the framework. In other words: admins have to learn only once to operate the framework, and can then deploy and configure any application using it. It is the purpose of the Linux-PAM project to separate the development of [[Authentication, authorization and privileges | privilege granting]] software from the development of secure and appropriate authentication schemes. This is accomplished by providing a library of functions that an application may use to request that a user be authenticated. This PAM library is configured locally with a series of configuration files located in ''/etc/pam.d/'' (or a system file, ''/etc/pam.conf'') to authenticate a user request via the locally available authentication modules. The modules themselves will usually be located in the directory ''/lib/security'' or ''/lib64/security'' and take the form of dynamically loadable object files. == Why use PAM == = PAM Principles = == PAM modules - in general == So we have these PAMs (or "PAM modules" as they're also referred to). Each module exists as a single file, usually beginning with ''pam_'' followed by a pretty descriptive name; for example ''pam_deny.so''. Each of these modules can be invoked by an application to answer a question about an authentication attempt. Furthermore, modules can be "stacked", so that you can call several modules sequentially. This makes it possible for an application to consult two different user repositories for a single login attempt: if ''both'' answer that the user is unknown, then the login attempt should probably fail, but if ''one'' of the two answers positively on the authentication request, then the user is authenticated, and the login attempt may continue. PAM has the necessary controls for this. These are named "control flags" and are treated further down. == PAM module types == So our modules can answer questions we have on an authentication request. But we can have several types of questions, like "may this user log in from this particular workstation" or "after logging in, what environment variables should the user get". PAM can handle these questions as well, because there are different types of modules. Or to be more precise: an individual module can address more than one of the module types. For instance pam_unix.so has components which address four module types. Currently, there ''are'' four module types, and they are explained below. === module type ''auth'' === ''auth'' type modules can answer [[Authentication, authorization and privileges |authentication requests]]. These are requests of the type "Is the user trying to log on REALLY user ''root''? Please verify using this password." But next to this, ''auth'' PAMs can also check for the application if system conditions are met, like "Is the user logging in from an acceptable device?" or "Is login currenly allowed (i.e. is the file ''/etc/nologin'' absent)?" Furthermore, this module type can also ''set'' credentials, like Kerberos tickets. === module type ''account'' === ''account'' type modules verify additional attributes of the digital identity trying to authenticate; these attributes could be described as "account data". Think of things like "is the user's account not disabled?", "Is the user entitled to accessing the specific resource?" (i.e. entitlement), et cetera. === module type ''password'' === When users can make use of a certain authentication mechanism, then they usually can also make some changes for their entry in that mechanism. For example, if a user can authenticate using a username/password, then he usually can also change his password. These changes can be made through this type of PAM; there usually is one ''password''-type PAM for every authentication method that the system is fitted with. === module type ''session'' === ''session'' type modules don't so much check the user login attempt, but they perform tasks that must be completed after a user has been authenticated. ''session'' type modules can load user limits, mount (home) directories, record login data for auditing purposes, or check system resources to see if there are enough resources to support the login attempt. == PAM control flags == So if a PAM is called to provide an answer, how do you determine what to do with the answer? To this end, we can -and must- make use of a control flag. These are the control flags that are available, ''plus'' a more complicated ''control value'' expression: === control flag ''required'' === This is quite a common control flag. A ''required'' module must be successfully checked in order to allow authentication. If a ''required module'' check fails, the user is not notified until all other modules of the same module type have been checked. === control flag ''requisite'' === A ''requisite'' module must be successfully checked in order for the authentication to be successful. However, if a ''requisite'' module check fails, the user is notified immediately with a message reflecting the first failed ''required'' or ''requisite'' module. === control flag ''sufficient'' === A ''sufficient'' module check is ignored if it fails. But, if a module flagged ''sufficient'' is successfully checked, and no ''required'' flagged modules above it have failed, then no other modules of this module type are checked and the user is authenticated. === control flag ''optional'' === An ''optional'' module check is always ignored if it fails. And if the module check is successful, it still doesn't play a role in the overall success or failure for that module type. The only time a module flagged as ''optional'' is necessary for successful authentication, is when no other modules of that type have succeeded or failed. ONLY in this case, an ''optional'' module determines the overall PAM authentication for that module type. === control value [expression] === Instead of one of the "classic" control flags, it is also possible to create a more complicated expression, as summarily mentioned in the [http://www.kernel.org/pub/linux/libs/pam/Linux-PAM-html/sag-configuration-file.html Linux-PAM SysAdmin guide]. The whole expression is enclosed in square brackets, with inbetween one or more expressions ''value=action''. Each ''value'' corresponds with must be one of this list: success, open_err, symbol_err, service_err, system_err, buf_err, perm_denied, auth_err, cred_insufficient, authinfo_unavail, user_unknown, maxtries, new_authtok_reqd, acct_expired, session_err, cred_unavail, cred_expired, cred_err, no_module_data, conv_err, authtok_err, authtok_recover_err, authtok_lock_busy, authtok_disable_aging, try_again, ignore, abort, authtok_expired, module_unknown, bad_item, conv_again, incomplete, and default.<br> Each ''action'' corresponds with one of these: * '''<number>''': if you list a number (an integer that's 1 or greater), then the effect will be that if your call to the module returns <value>, then your PAM process will skip the next <number> lines; this is a rudimentary form of flow control * '''ignore''': when used with a stack of modules, the module's return status will not contribute to the return code the application obtains. * '''bad''': this action indicates that the return code should be thought of as indicative of the module failing. If this module is the first in the stack to fail, its status value will be used for that of the whole stack. * '''die''': equivalent to bad with the side effect of terminating the module stack and PAM immediately returning to the application. * '''ok''': this tells PAM that the administrator thinks this return code should contribute directly to the return code of the full stack of modules. In other words, if the former state of the stack would lead to a return of PAM_SUCCESS, the module's return code will override this value. Note, if the former state of the stack holds some value that is indicative of a modules failure, this 'ok' value will not be used to override that value. * '''done''': equivalent to ok with the side effect of terminating the module stack and PAM immediately returning to the application. * '''reset''': clear all memory of the state of the module stack and start again with the next stacked module. If you've grasped the effects of the classic control flags, then you'll see that each of these makes use of these actions. == PAM module arguments == PAM can use "arguments" to pass information to a pluggable module during authentication. These arguments allow the PAM configuration files for particular programs to use a common PAM module, but in different ways. For example, the ''pam_userdb.so'' module uses secrets stored in a Berkeley DB file to authenticate the user. Berkeley DB is an open source database system designed to be embedded in many applications to track information. The module takes a "db argument", specifying the Berkeley DB filename to use, which can be different for different services. Thus, the ''pam_userdb.so'' line in a PAM configuration file can look like this: auth required /lib/security/pam_userdb.so db=path/to/file Invalid arguments are ignored, and do not otherwise affect the success or failure of the PAM module. When an invalid argument is passed, an error is usually written to the ''/var/log/messages'' file. However, since the reporting method is controlled by the PAM module itself, you depend on the module having been written correctly to log the error to this file. Usually this is the case, but be aware that exotic PAMs might write to a different location, or not at all. == PAM configuration lines== As was already shown in the previous section, a single line of PAM configuration code consists of the four fields we've now covered, separated by whitespace. The fields are: <module type> <control flag> <PAM> <optional arguments> Multiple arguments can be written one after another, separated by spaces (PAM simply interprets the whole rest of the line after the <PAM> as arguments). You can string lines like this after one another in a PAM configuration file, and the PAM framework will process them one after another at the time of an authentication request. == Invoking PAM == As you might expect from the previous texts, you can only use PAM if your application, service, daemon or program is "PAM-aware". This means, that it is coded and compiled to use PAM. Fortunately, in this day and age most applications, daemons et cetera are. However, this presents us with a true problem: that of ''choice''. When your application is PAM-aware, it means that your application can deletate just about any imaginable authentication-task to PAM - which YOU, the system administrator, must achieve by invoking PAM in just the right way. To this end, you must create a PAM configuration file, and fill it with just the right information as to have PAM perform all tasks that you want - and none other. This is because when a privilege granting application is started that is PAM aware, it activates its attachment to the PAM-API. This activation performs a number of tasks, the most important being the reading of the configuration file (more on that further on). This file list the PAMs (the "PAM modules") that will do the authentication tasks required by this application, and the appropriate behavior of the PAM-API in the event that individual PAMs fail. Now there are several ways to invoke PAM, and which ones are available to us under Debian will be more fully explored in a later section, but for now let's look at one particular method, that is also available under Debian. If we create a file in ''/etc/pam.d/'' with the name of the service that we want to have PAM perform authentication for, then that can contain the necessary PAM configuration lines, and that will be the PAM configuration for that particular service. Does that make sense? No? Then let me give you an example. Suppose we have some service with a name of ''sshd'', and we want that service to use PAM to check if a user that attempts to use the service is actuall allowed to do so. We then create ''/etc/pam.d/sshd'' and fill it with these two lines: auth required pam_unix.so session optional pam_motd.so This means we've now configured the ''sshd'' [[OpenSSH server | SSH daemon]] to use PAM for authentication/authorization. The exact instructions we've provided PAM are: check if the name and password provided to ''sshd'' by a user attempting to log in represent a valid name/password as they occur in our local Linux user account database (''/etc/passwd''). If so, we'll allow access. The second line furthermore shows a user logging in the [[MOTD_file | Message-of-the-day]], if that message exists. Think that that's easy? Almost looks like it, right? But ==An example: sshd configuration file == For a real SSH daemon, the PAM configuration file can look something like this: auth required pam_env.so auth required pam_env.so envfile=/etc/default/locale auth sufficient pam_unix.so nullok_secure auth requisite pam_succeed_if.so uid >= 1000 quiet auth sufficient pam_ldap.so use_first_pass auth required pam_deny.so account required pam_access.so account sufficient pam_unix.so account sufficient pam_succeed_if.so uid < 1000 quiet account [default=bad success=ok user_unknown=ignore] pam_ldap.so account required pam_permit.so session required pam_limits.so session required pam_unix.so session required pam_mkhomedir.so skel=/etc/skel/ umask=0022 session optional pam_ldap.so session optional pam_motd.so session optional pam_mail.so standard noenv session required pam_limits.so password sufficient pam_unix.so md5 obscure min=4 nullok try_first_pass password sufficient pam_ldap.so password required pam_deny.so Well that looks a bit intimidating, doesn't it? Do not worry, we'll explain everything in great detail, so we are quite sure that, once you get to the end of this document, you'll understand what files like this mean. And hopefully, you'll even be able to create or edit your own! In the example, there are five lines that begin with ''auth''. This means that for any authentication request, PAM consults five modules. Let's have a look at what they do: * ''auth required pam_env.so''<br>This line calls the ''pam_env.so'' PAM, which is a module that can ''only'' be called as an ''auth'' module. It is configured using the ''/etc/security/pam_env.conf'' file, and what it does is it sets a number of environmental variables for the user that tries to log in. These variables can be declared in the ''pam_env.conf'' file, and can be used to supply default values for environmental variables that are not (yet) set for the user, and to override other environmental variables for which the administrator wishes to provide different values from what the user might have configured. It's flagged ''required'', so this module must succeed or the user will be denied access. Fortunately, this module will always succeed. * '' auth required pam_env.so envfile=/etc/default/locale''<br>Hey, haven't we seen this one before? It's the same ''pam_env.so'', but now it's reading an ''envfile'', so as to set the variables that are in the file ''locale''. * '' auth sufficient pam_unix.so nullok_secure''<br>This calls the PAM named ''pam_unix.so'' in its authentication mode. The module is flagged ''sufficient'', so if this module recognises the user, then no other ''auth'' module will be consulted - effectively skipping the next three ''auth'' modules. See that order is important?<br>The module will check if the authentication attempt is made by a valid Unix user. The parameter nullok_secure makes sure that even login attempts by users with blank passwords fail, as long as they try to authenticate from a secure terminal * ''auth requisite pam_succeed_if.so uid >= 1000 quiet''<br>This module ''[http://linux.die.net/man/8/pam_succeed_if pam_succeed_if.so]'' brings a rudimentary form of flow control to our PAM configuration files. It can perform tests, and based on that test will cause a "success" or "fail" state to the ''auth'' section - but it WON'T return "success" or "fail" to the authentication attempt itself! Because it is here used with ''requisite'', a failure of this module would immediately be effective. The first argument (or set of arguments) is ''uid >= 1000''. This is the actual test that the module will be performing: if the user that is trying to authenticate has a user ID of LESS than 1000, the module will fail, and the ''requisite'' flag will cause PAM to perform no more ''auth'' module tests. The last argument of this module is a flag ''quiet'', which makes this module skip recording failure or success messages in the message log.<br>So what is now the effect of this module? For ordinary system users (who have an uid of 1000 or more), this module will do just nothing. But if this module is called for an authentication request by a service daemon, then the uid will be less than 1000, so ''pam_succeed_if.so'' will FAIL. The ''requisite'' control flag causes PAM to immediately end the ''auth'' stage of the login; that means all following ''auth'' modules will ONLY be processed for ordinary users, not service daemons. Neat, eh? * ''auth sufficient pam_ldap.so use_first_pass''<br>This module (because of the preceding line never called when daemons try to log in) will attempt to see if the user and password that need to be authenticated are valid in your LDAP server. The ''sufficient'' control flag makes sure that if the user is NOT a valid LDAP user, nothing happens. However, if he is, AND no previous ''auth'' modules have returned an auth failure, then the PAM returns "success" and the ''auth'' phase immediately ends. * ''auth required pam_deny.so''<br>This last ''auth'' module is the catchall; if no previous ''auth'' module of type ''sufficient'' has returned a success, then this module kicks in. And guess what? Called as an ''auth'' module, it ALWAYS returns "failure". The compound effect of this authentication section of the example PAM configuration is this: # Default environmental variables are set # The ''locale'' file is read # All valid Unix users, and Unix users with blank passwords from secure terminals, are authenticated OK # All valid Unix users = PAM on Debian= == PAM modules in Debian 5.0 'Lenny'== == PAM configuration files == = Configuration example= == Configuring PAM for LDAP == 112b6765b0fa6fd89a076cddf8b8e67c460d3238 2014 2013 2008-11-16T11:48:57Z Saruman! 2 /* PAM configuration lines */ added @include and substack wikitext text/x-wiki '''Pluggable Authentication Modules for Linux''' (Linux-PAM) is a great way to fit your Linux server with [[Authentication, authorization and privileges | authentication-related]] services. However, we found their use pretty difficult, due to some aspects of PAM not being as obvious as the tutorial and howto-writers apparently expect. Thus, we here try to explain [[SaruWiki:About | ourselves]] (and you, dear reader) how PAM works. =PAM introduction= ==What is PAM== Most Linux applications require [[Authentication, authorization and privileges | authentication]] of some type or another. For [[Authentication, authorization and privileges | authentication]], multiple mechanisms are available, ranging from the standard Linux password through certificates all the way to smartcard readers, fingerprint readers and what have you not. To make use of one (or more) of these mechanisms, there are two main choices: either program the code required to interface with your authentication mechanism of choice, or make use of some framework that can take care of the interfacing with the authentication mechanism for you. Historically, an application that required a given user to be [[Authentication, authorization and privileges | authenticated]] had to be compiled to use a specific authentication mechanism. For example, in the case of traditional UN*X systems, the identity of the user is verified by the user entering a correct password. This password, after being prefixed by a two character "salt", is encrypted (with ''crypt''). The user is then authenticated if this encrypted password is identical to the second field of the user's entry in the system password database (the ''/etc/passwd'' file). On such systems, most if not all forms of [[Authentication, authorization and privileges | privileges]] are granted based on this single authentication scheme. [[Authentication, authorization and privileges | Privilege]] comes in the form of a personal user-identifier (UID) and membership of various groups. Services and applications are available based on the personal and group identity of the user. Traditionally, group membership has been assigned based on entries in the ''/etc/group'' file. This all means, that if you ever want to change something in the way users or groups are stored, then you'll have to rewrite and recompile each and every application that has the support for ''passwd'' and ''group'' hardcoded. And if you wanted to include support for some other authentication mechanism, you'd have to rewrite ''every'' application that's using authentication. Furthermore, the configuration of your authentication mechanism most likely takes place in the configuration file of each individual program. This means different configuration files, probably with different notations, syntax, et cetera. It will be clear that programming authentication mechanism support is not usually a smart move. Enter authentication frameworks. Suppose we create a framework that contains multiple authentication mechanisms, each conveniently shaped in the form of separate modules and libraries. Suppose we have a clearly defined interface, so that any program can easily link to this framework. Programs can then configure their interface to the framework to choose the authentication mechanisms they want themselves, and then delegate the [[Authentication, authorization and privileges | authenticity question]] to this framework; once a user is authenticated (or not), the framework passes the "yes" (or "no") back to the program. This makes connecting to a framework a one-time effort, requiring only extra effort if and when the framework itself changes. And here we encounter PAM, because PAM is just such a framework. Free after the PAM admin guide: Linux-PAM is a suite of shared libraries. Using these libraries, the local system administrator can specify how PAM-aware applications authenticate users. "PAM-aware" in this context means that the application is written to interface with the PAM framework. In other words, if an application or service is PAM-aware, then it is possible to select/combine/switch between the PAM authentication mechanism(s) you want it to use, without (rewriting and) recompiling program code. Indeed, one may entirely upgrade or reconfigure the local authentication system without touching the applications themselves. Furthermore, the administrative effort associated with authentication management is reduced, since all configuration is the same for any application using using the framework. In other words: admins have to learn only once to operate the framework, and can then deploy and configure any application using it. It is the purpose of the Linux-PAM project to separate the development of [[Authentication, authorization and privileges | privilege granting]] software from the development of secure and appropriate authentication schemes. This is accomplished by providing a library of functions that an application may use to request that a user be authenticated. This PAM library is configured locally with a series of configuration files located in ''/etc/pam.d/'' (or a system file, ''/etc/pam.conf'') to authenticate a user request via the locally available authentication modules. The modules themselves will usually be located in the directory ''/lib/security'' or ''/lib64/security'' and take the form of dynamically loadable object files. == Why use PAM == = PAM Principles = == PAM modules - in general == So we have these PAMs (or "PAM modules" as they're also referred to). Each module exists as a single file, usually beginning with ''pam_'' followed by a pretty descriptive name; for example ''pam_deny.so''. Each of these modules can be invoked by an application to answer a question about an authentication attempt. Furthermore, modules can be "stacked", so that you can call several modules sequentially. This makes it possible for an application to consult two different user repositories for a single login attempt: if ''both'' answer that the user is unknown, then the login attempt should probably fail, but if ''one'' of the two answers positively on the authentication request, then the user is authenticated, and the login attempt may continue. PAM has the necessary controls for this. These are named "control flags" and are treated further down. == PAM module types == So our modules can answer questions we have on an authentication request. But we can have several types of questions, like "may this user log in from this particular workstation" or "after logging in, what environment variables should the user get". PAM can handle these questions as well, because there are different types of modules. Or to be more precise: an individual module can address more than one of the module types. For instance pam_unix.so has components which address four module types. Currently, there ''are'' four module types, and they are explained below. === module type ''auth'' === ''auth'' type modules can answer [[Authentication, authorization and privileges |authentication requests]]. These are requests of the type "Is the user trying to log on REALLY user ''root''? Please verify using this password." But next to this, ''auth'' PAMs can also check for the application if system conditions are met, like "Is the user logging in from an acceptable device?" or "Is login currenly allowed (i.e. is the file ''/etc/nologin'' absent)?" Furthermore, this module type can also ''set'' credentials, like Kerberos tickets. === module type ''account'' === ''account'' type modules verify additional attributes of the digital identity trying to authenticate; these attributes could be described as "account data". Think of things like "is the user's account not disabled?", "Is the user entitled to accessing the specific resource?" (i.e. entitlement), et cetera. === module type ''password'' === When users can make use of a certain authentication mechanism, then they usually can also make some changes for their entry in that mechanism. For example, if a user can authenticate using a username/password, then he usually can also change his password. These changes can be made through this type of PAM; there usually is one ''password''-type PAM for every authentication method that the system is fitted with. === module type ''session'' === ''session'' type modules don't so much check the user login attempt, but they perform tasks that must be completed after a user has been authenticated. ''session'' type modules can load user limits, mount (home) directories, record login data for auditing purposes, or check system resources to see if there are enough resources to support the login attempt. == PAM control flags == So if a PAM is called to provide an answer, how do you determine what to do with the answer? To this end, we can -and must- make use of a control flag. These are the control flags that are available, ''plus'' a more complicated ''control value'' expression: === control flag ''required'' === This is quite a common control flag. A ''required'' module must be successfully checked in order to allow authentication. If a ''required module'' check fails, the user is not notified until all other modules of the same module type have been checked. === control flag ''requisite'' === A ''requisite'' module must be successfully checked in order for the authentication to be successful. However, if a ''requisite'' module check fails, the user is notified immediately with a message reflecting the first failed ''required'' or ''requisite'' module. === control flag ''sufficient'' === A ''sufficient'' module check is ignored if it fails. But, if a module flagged ''sufficient'' is successfully checked, and no ''required'' flagged modules above it have failed, then no other modules of this module type are checked and the user is authenticated. === control flag ''optional'' === An ''optional'' module check is always ignored if it fails. And if the module check is successful, it still doesn't play a role in the overall success or failure for that module type. The only time a module flagged as ''optional'' is necessary for successful authentication, is when no other modules of that type have succeeded or failed. ONLY in this case, an ''optional'' module determines the overall PAM authentication for that module type. === control value [expression] === Instead of one of the "classic" control flags, it is also possible to create a more complicated expression, as summarily mentioned in the [http://www.kernel.org/pub/linux/libs/pam/Linux-PAM-html/sag-configuration-file.html Linux-PAM SysAdmin guide]. The whole expression is enclosed in square brackets, with inbetween one or more expressions ''value=action''. Each ''value'' corresponds with must be one of this list: success, open_err, symbol_err, service_err, system_err, buf_err, perm_denied, auth_err, cred_insufficient, authinfo_unavail, user_unknown, maxtries, new_authtok_reqd, acct_expired, session_err, cred_unavail, cred_expired, cred_err, no_module_data, conv_err, authtok_err, authtok_recover_err, authtok_lock_busy, authtok_disable_aging, try_again, ignore, abort, authtok_expired, module_unknown, bad_item, conv_again, incomplete, and default.<br> Each ''action'' corresponds with one of these: * '''<number>''': if you list a number (an integer that's 1 or greater), then the effect will be that if your call to the module returns <value>, then your PAM process will skip the next <number> lines; this is a rudimentary form of flow control * '''ignore''': when used with a stack of modules, the module's return status will not contribute to the return code the application obtains. * '''bad''': this action indicates that the return code should be thought of as indicative of the module failing. If this module is the first in the stack to fail, its status value will be used for that of the whole stack. * '''die''': equivalent to bad with the side effect of terminating the module stack and PAM immediately returning to the application. * '''ok''': this tells PAM that the administrator thinks this return code should contribute directly to the return code of the full stack of modules. In other words, if the former state of the stack would lead to a return of PAM_SUCCESS, the module's return code will override this value. Note, if the former state of the stack holds some value that is indicative of a modules failure, this 'ok' value will not be used to override that value. * '''done''': equivalent to ok with the side effect of terminating the module stack and PAM immediately returning to the application. * '''reset''': clear all memory of the state of the module stack and start again with the next stacked module. If you've grasped the effects of the classic control flags, then you'll see that each of these makes use of these actions. == PAM module arguments == PAM can use "arguments" to pass information to a pluggable module during authentication. These arguments allow the PAM configuration files for particular programs to use a common PAM module, but in different ways. For example, the ''pam_userdb.so'' module uses secrets stored in a Berkeley DB file to authenticate the user. Berkeley DB is an open source database system designed to be embedded in many applications to track information. The module takes a "db argument", specifying the Berkeley DB filename to use, which can be different for different services. Thus, the ''pam_userdb.so'' line in a PAM configuration file can look like this: auth required /lib/security/pam_userdb.so db=path/to/file Invalid arguments are ignored, and do not otherwise affect the success or failure of the PAM module. When an invalid argument is passed, an error is usually written to the ''/var/log/messages'' file. However, since the reporting method is controlled by the PAM module itself, you depend on the module having been written correctly to log the error to this file. Usually this is the case, but be aware that exotic PAMs might write to a different location, or not at all. == PAM configuration lines== As was already shown in the previous section, a single line of PAM configuration code consists of the four fields we've now covered, separated by whitespace. The fields are: <module type> <control flag> <PAM> <optional arguments> Multiple arguments can be written one after another, separated by spaces (PAM simply interprets the whole rest of the line after the <PAM> as arguments). You can string lines like this after one another in a PAM configuration file, and the PAM framework will process them one after another at the time of an authentication request. A little extra: we can include files into our PAM configuration file using the ''@include'' statement. Thus, the file /etc/pam.d/sshd could contain the following lines: auth required pam_env.so auth required pam_env.so envfile=/etc/default/locale @include common-auth account required pam_nologin.so @include common-account @include common-session session optional pam_motd.so session optional pam_mail.so standard noenv session required pam_limits.so @include common-password The effect of this is that the files ''common-auth'', ''common-account'', ''common-session'' and ''common-passwd'' (all from directory ''/etc/pam.d/'' as well) are included into our sshd configuration. Not wholly surprisingly, file ''common-auth'' contains all common PAM authentication lines, ''common-account'' all common PAM account lines, etcetera. This makes it relatively easy to add authentication/authorisation mechanisms to our Debian server; we've only to add them to these ''common-'' files, and all services and processes will know about them. We can also include modules into our PAM configuration using the substack procedure. This includes all lines of given type from the configuration file specified as an argument to this control. A call using substack would look like this: auth substack common-auth This differs from include in that evaluation of the done and die actions in a substack does not cause skipping the rest of the complete module stack, but only of the substack. Jumps in a substack also can not make evaluation jump out of it, and the whole substack is counted as one module when the jump is done in a parent stack. The reset action will reset the state of a module stack to the state it was in as of beginning of the substack evaluation. == Invoking PAM == As you might expect from the previous texts, you can only use PAM if your application, service, daemon or program is "PAM-aware". This means, that it is coded and compiled to use PAM. Fortunately, in this day and age most applications, daemons et cetera are. However, this presents us with a true problem: that of ''choice''. When your application is PAM-aware, it means that your application can deletate just about any imaginable authentication-task to PAM - which YOU, the system administrator, must achieve by invoking PAM in just the right way. To this end, you must create a PAM configuration file, and fill it with just the right information as to have PAM perform all tasks that you want - and none other. This is because when a privilege granting application is started that is PAM aware, it activates its attachment to the PAM-API. This activation performs a number of tasks, the most important being the reading of the configuration file (more on that further on). This file list the PAMs (the "PAM modules") that will do the authentication tasks required by this application, and the appropriate behavior of the PAM-API in the event that individual PAMs fail. Now there are several ways to invoke PAM, and which ones are available to us under Debian will be more fully explored in a later section, but for now let's look at one particular method, that is also available under Debian. If we create a file in ''/etc/pam.d/'' with the name of the service that we want to have PAM perform authentication for, then that can contain the necessary PAM configuration lines, and that will be the PAM configuration for that particular service. Does that make sense? No? Then let me give you an example. Suppose we have some service with a name of ''sshd'', and we want that service to use PAM to check if a user that attempts to use the service is actuall allowed to do so. We then create ''/etc/pam.d/sshd'' and fill it with these two lines: auth required pam_unix.so session optional pam_motd.so This means we've now configured the ''sshd'' [[OpenSSH server | SSH daemon]] to use PAM for authentication/authorization. The exact instructions we've provided PAM are: check if the name and password provided to ''sshd'' by a user attempting to log in represent a valid name/password as they occur in our local Linux user account database (''/etc/passwd''). If so, we'll allow access. The second line furthermore shows a user logging in the [[MOTD_file | Message-of-the-day]], if that message exists. Think that that's easy? Almost looks like it, right? But ==An example: sshd configuration file == For a real SSH daemon, the PAM configuration file can look something like this: auth required pam_env.so auth required pam_env.so envfile=/etc/default/locale auth sufficient pam_unix.so nullok_secure auth requisite pam_succeed_if.so uid >= 1000 quiet auth sufficient pam_ldap.so use_first_pass auth required pam_deny.so account required pam_access.so account sufficient pam_unix.so account sufficient pam_succeed_if.so uid < 1000 quiet account [default=bad success=ok user_unknown=ignore] pam_ldap.so account required pam_permit.so session required pam_limits.so session required pam_unix.so session required pam_mkhomedir.so skel=/etc/skel/ umask=0022 session optional pam_ldap.so session optional pam_motd.so session optional pam_mail.so standard noenv session required pam_limits.so password sufficient pam_unix.so md5 obscure min=4 nullok try_first_pass password sufficient pam_ldap.so password required pam_deny.so Well that looks a bit intimidating, doesn't it? Do not worry, we'll explain everything in great detail, so we are quite sure that, once you get to the end of this document, you'll understand what files like this mean. And hopefully, you'll even be able to create or edit your own! In the example, there are five lines that begin with ''auth''. This means that for any authentication request, PAM consults five modules. Let's have a look at what they do: * ''auth required pam_env.so''<br>This line calls the ''pam_env.so'' PAM, which is a module that can ''only'' be called as an ''auth'' module. It is configured using the ''/etc/security/pam_env.conf'' file, and what it does is it sets a number of environmental variables for the user that tries to log in. These variables can be declared in the ''pam_env.conf'' file, and can be used to supply default values for environmental variables that are not (yet) set for the user, and to override other environmental variables for which the administrator wishes to provide different values from what the user might have configured. It's flagged ''required'', so this module must succeed or the user will be denied access. Fortunately, this module will always succeed. * '' auth required pam_env.so envfile=/etc/default/locale''<br>Hey, haven't we seen this one before? It's the same ''pam_env.so'', but now it's reading an ''envfile'', so as to set the variables that are in the file ''locale''. * '' auth sufficient pam_unix.so nullok_secure''<br>This calls the PAM named ''pam_unix.so'' in its authentication mode. The module is flagged ''sufficient'', so if this module recognises the user, then no other ''auth'' module will be consulted - effectively skipping the next three ''auth'' modules. See that order is important?<br>The module will check if the authentication attempt is made by a valid Unix user. The parameter nullok_secure makes sure that even login attempts by users with blank passwords fail, as long as they try to authenticate from a secure terminal * ''auth requisite pam_succeed_if.so uid >= 1000 quiet''<br>This module ''[http://linux.die.net/man/8/pam_succeed_if pam_succeed_if.so]'' brings a rudimentary form of flow control to our PAM configuration files. It can perform tests, and based on that test will cause a "success" or "fail" state to the ''auth'' section - but it WON'T return "success" or "fail" to the authentication attempt itself! Because it is here used with ''requisite'', a failure of this module would immediately be effective. The first argument (or set of arguments) is ''uid >= 1000''. This is the actual test that the module will be performing: if the user that is trying to authenticate has a user ID of LESS than 1000, the module will fail, and the ''requisite'' flag will cause PAM to perform no more ''auth'' module tests. The last argument of this module is a flag ''quiet'', which makes this module skip recording failure or success messages in the message log.<br>So what is now the effect of this module? For ordinary system users (who have an uid of 1000 or more), this module will do just nothing. But if this module is called for an authentication request by a service daemon, then the uid will be less than 1000, so ''pam_succeed_if.so'' will FAIL. The ''requisite'' control flag causes PAM to immediately end the ''auth'' stage of the login; that means all following ''auth'' modules will ONLY be processed for ordinary users, not service daemons. Neat, eh? * ''auth sufficient pam_ldap.so use_first_pass''<br>This module (because of the preceding line never called when daemons try to log in) will attempt to see if the user and password that need to be authenticated are valid in your LDAP server. The ''sufficient'' control flag makes sure that if the user is NOT a valid LDAP user, nothing happens. However, if he is, AND no previous ''auth'' modules have returned an auth failure, then the PAM returns "success" and the ''auth'' phase immediately ends. * ''auth required pam_deny.so''<br>This last ''auth'' module is the catchall; if no previous ''auth'' module of type ''sufficient'' has returned a success, then this module kicks in. And guess what? Called as an ''auth'' module, it ALWAYS returns "failure". The compound effect of this authentication section of the example PAM configuration is this: # Default environmental variables are set # The ''locale'' file is read # All valid Unix users, and Unix users with blank passwords from secure terminals, are authenticated OK # All valid Unix users = PAM on Debian= == PAM modules in Debian 5.0 'Lenny'== == PAM configuration files == = Configuration example= == Configuring PAM for LDAP == 5492d0533ad07d916db466ef640cd93c4dc95763 2015 2014 2008-11-16T11:51:58Z Saruman! 2 /* control value [expression] */ expounded expressions wikitext text/x-wiki '''Pluggable Authentication Modules for Linux''' (Linux-PAM) is a great way to fit your Linux server with [[Authentication, authorization and privileges | authentication-related]] services. However, we found their use pretty difficult, due to some aspects of PAM not being as obvious as the tutorial and howto-writers apparently expect. Thus, we here try to explain [[SaruWiki:About | ourselves]] (and you, dear reader) how PAM works. =PAM introduction= ==What is PAM== Most Linux applications require [[Authentication, authorization and privileges | authentication]] of some type or another. For [[Authentication, authorization and privileges | authentication]], multiple mechanisms are available, ranging from the standard Linux password through certificates all the way to smartcard readers, fingerprint readers and what have you not. To make use of one (or more) of these mechanisms, there are two main choices: either program the code required to interface with your authentication mechanism of choice, or make use of some framework that can take care of the interfacing with the authentication mechanism for you. Historically, an application that required a given user to be [[Authentication, authorization and privileges | authenticated]] had to be compiled to use a specific authentication mechanism. For example, in the case of traditional UN*X systems, the identity of the user is verified by the user entering a correct password. This password, after being prefixed by a two character "salt", is encrypted (with ''crypt''). The user is then authenticated if this encrypted password is identical to the second field of the user's entry in the system password database (the ''/etc/passwd'' file). On such systems, most if not all forms of [[Authentication, authorization and privileges | privileges]] are granted based on this single authentication scheme. [[Authentication, authorization and privileges | Privilege]] comes in the form of a personal user-identifier (UID) and membership of various groups. Services and applications are available based on the personal and group identity of the user. Traditionally, group membership has been assigned based on entries in the ''/etc/group'' file. This all means, that if you ever want to change something in the way users or groups are stored, then you'll have to rewrite and recompile each and every application that has the support for ''passwd'' and ''group'' hardcoded. And if you wanted to include support for some other authentication mechanism, you'd have to rewrite ''every'' application that's using authentication. Furthermore, the configuration of your authentication mechanism most likely takes place in the configuration file of each individual program. This means different configuration files, probably with different notations, syntax, et cetera. It will be clear that programming authentication mechanism support is not usually a smart move. Enter authentication frameworks. Suppose we create a framework that contains multiple authentication mechanisms, each conveniently shaped in the form of separate modules and libraries. Suppose we have a clearly defined interface, so that any program can easily link to this framework. Programs can then configure their interface to the framework to choose the authentication mechanisms they want themselves, and then delegate the [[Authentication, authorization and privileges | authenticity question]] to this framework; once a user is authenticated (or not), the framework passes the "yes" (or "no") back to the program. This makes connecting to a framework a one-time effort, requiring only extra effort if and when the framework itself changes. And here we encounter PAM, because PAM is just such a framework. Free after the PAM admin guide: Linux-PAM is a suite of shared libraries. Using these libraries, the local system administrator can specify how PAM-aware applications authenticate users. "PAM-aware" in this context means that the application is written to interface with the PAM framework. In other words, if an application or service is PAM-aware, then it is possible to select/combine/switch between the PAM authentication mechanism(s) you want it to use, without (rewriting and) recompiling program code. Indeed, one may entirely upgrade or reconfigure the local authentication system without touching the applications themselves. Furthermore, the administrative effort associated with authentication management is reduced, since all configuration is the same for any application using using the framework. In other words: admins have to learn only once to operate the framework, and can then deploy and configure any application using it. It is the purpose of the Linux-PAM project to separate the development of [[Authentication, authorization and privileges | privilege granting]] software from the development of secure and appropriate authentication schemes. This is accomplished by providing a library of functions that an application may use to request that a user be authenticated. This PAM library is configured locally with a series of configuration files located in ''/etc/pam.d/'' (or a system file, ''/etc/pam.conf'') to authenticate a user request via the locally available authentication modules. The modules themselves will usually be located in the directory ''/lib/security'' or ''/lib64/security'' and take the form of dynamically loadable object files. == Why use PAM == = PAM Principles = == PAM modules - in general == So we have these PAMs (or "PAM modules" as they're also referred to). Each module exists as a single file, usually beginning with ''pam_'' followed by a pretty descriptive name; for example ''pam_deny.so''. Each of these modules can be invoked by an application to answer a question about an authentication attempt. Furthermore, modules can be "stacked", so that you can call several modules sequentially. This makes it possible for an application to consult two different user repositories for a single login attempt: if ''both'' answer that the user is unknown, then the login attempt should probably fail, but if ''one'' of the two answers positively on the authentication request, then the user is authenticated, and the login attempt may continue. PAM has the necessary controls for this. These are named "control flags" and are treated further down. == PAM module types == So our modules can answer questions we have on an authentication request. But we can have several types of questions, like "may this user log in from this particular workstation" or "after logging in, what environment variables should the user get". PAM can handle these questions as well, because there are different types of modules. Or to be more precise: an individual module can address more than one of the module types. For instance pam_unix.so has components which address four module types. Currently, there ''are'' four module types, and they are explained below. === module type ''auth'' === ''auth'' type modules can answer [[Authentication, authorization and privileges |authentication requests]]. These are requests of the type "Is the user trying to log on REALLY user ''root''? Please verify using this password." But next to this, ''auth'' PAMs can also check for the application if system conditions are met, like "Is the user logging in from an acceptable device?" or "Is login currenly allowed (i.e. is the file ''/etc/nologin'' absent)?" Furthermore, this module type can also ''set'' credentials, like Kerberos tickets. === module type ''account'' === ''account'' type modules verify additional attributes of the digital identity trying to authenticate; these attributes could be described as "account data". Think of things like "is the user's account not disabled?", "Is the user entitled to accessing the specific resource?" (i.e. entitlement), et cetera. === module type ''password'' === When users can make use of a certain authentication mechanism, then they usually can also make some changes for their entry in that mechanism. For example, if a user can authenticate using a username/password, then he usually can also change his password. These changes can be made through this type of PAM; there usually is one ''password''-type PAM for every authentication method that the system is fitted with. === module type ''session'' === ''session'' type modules don't so much check the user login attempt, but they perform tasks that must be completed after a user has been authenticated. ''session'' type modules can load user limits, mount (home) directories, record login data for auditing purposes, or check system resources to see if there are enough resources to support the login attempt. == PAM control flags == So if a PAM is called to provide an answer, how do you determine what to do with the answer? To this end, we can -and must- make use of a control flag. These are the control flags that are available, ''plus'' a more complicated ''control value'' expression: === control flag ''required'' === This is quite a common control flag. A ''required'' module must be successfully checked in order to allow authentication. If a ''required module'' check fails, the user is not notified until all other modules of the same module type have been checked. === control flag ''requisite'' === A ''requisite'' module must be successfully checked in order for the authentication to be successful. However, if a ''requisite'' module check fails, the user is notified immediately with a message reflecting the first failed ''required'' or ''requisite'' module. === control flag ''sufficient'' === A ''sufficient'' module check is ignored if it fails. But, if a module flagged ''sufficient'' is successfully checked, and no ''required'' flagged modules above it have failed, then no other modules of this module type are checked and the user is authenticated. === control flag ''optional'' === An ''optional'' module check is always ignored if it fails. And if the module check is successful, it still doesn't play a role in the overall success or failure for that module type. The only time a module flagged as ''optional'' is necessary for successful authentication, is when no other modules of that type have succeeded or failed. ONLY in this case, an ''optional'' module determines the overall PAM authentication for that module type. === control value [expression] === Instead of one of the "classic" control flags, it is also possible to create a more complicated expression, as summarily mentioned in the [http://www.kernel.org/pub/linux/libs/pam/Linux-PAM-html/sag-configuration-file.html Linux-PAM SysAdmin guide]. The whole expression is enclosed in square brackets, with inbetween one or more expressions ''value=action''. Each ''value'' corresponds with must be one of this list: success, open_err, symbol_err, service_err, system_err, buf_err, perm_denied, auth_err, cred_insufficient, authinfo_unavail, user_unknown, maxtries, new_authtok_reqd, acct_expired, session_err, cred_unavail, cred_expired, cred_err, no_module_data, conv_err, authtok_err, authtok_recover_err, authtok_lock_busy, authtok_disable_aging, try_again, ignore, abort, authtok_expired, module_unknown, bad_item, conv_again, incomplete, and default.<br> Each ''action'' corresponds with one of these: * '''<number>''': if you list a number (an integer that's 1 or greater), then the effect will be that if your call to the module returns <value>, then your PAM process will skip the next <number> lines; this is a rudimentary form of flow control * '''ignore''': when used with a stack of modules, the module's return status will not contribute to the return code the application obtains. * '''bad''': this action indicates that the return code should be thought of as indicative of the module failing. If this module is the first in the stack to fail, its status value will be used for that of the whole stack. * '''die''': equivalent to bad with the side effect of terminating the module stack and PAM immediately returning to the application. * '''ok''': this tells PAM that the administrator thinks this return code should contribute directly to the return code of the full stack of modules. In other words, if the former state of the stack would lead to a return of PAM_SUCCESS, the module's return code will override this value. Note, if the former state of the stack holds some value that is indicative of a modules failure, this 'ok' value will not be used to override that value. * '''done''': equivalent to ok with the side effect of terminating the module stack and PAM immediately returning to the application. * '''reset''': clear all memory of the state of the module stack and start again with the next stacked module. If you've grasped the effects of the classic control flags, then you'll see that each of these makes use of these actions. To be precise: each of the classic control flags has an equivalent expression in terms of the [...] syntax. These equivalent expressions are: required [success=ok new_authtok_reqd=ok ignore=ignore default=bad] requisite [success=ok new_authtok_reqd=ok ignore=ignore default=die] sufficient [success=done new_authtok_reqd=done default=ignore] optional [success=ok new_authtok_reqd=ok default=ignore] == PAM module arguments == PAM can use "arguments" to pass information to a pluggable module during authentication. These arguments allow the PAM configuration files for particular programs to use a common PAM module, but in different ways. For example, the ''pam_userdb.so'' module uses secrets stored in a Berkeley DB file to authenticate the user. Berkeley DB is an open source database system designed to be embedded in many applications to track information. The module takes a "db argument", specifying the Berkeley DB filename to use, which can be different for different services. Thus, the ''pam_userdb.so'' line in a PAM configuration file can look like this: auth required /lib/security/pam_userdb.so db=path/to/file Invalid arguments are ignored, and do not otherwise affect the success or failure of the PAM module. When an invalid argument is passed, an error is usually written to the ''/var/log/messages'' file. However, since the reporting method is controlled by the PAM module itself, you depend on the module having been written correctly to log the error to this file. Usually this is the case, but be aware that exotic PAMs might write to a different location, or not at all. == PAM configuration lines== As was already shown in the previous section, a single line of PAM configuration code consists of the four fields we've now covered, separated by whitespace. The fields are: <module type> <control flag> <PAM> <optional arguments> Multiple arguments can be written one after another, separated by spaces (PAM simply interprets the whole rest of the line after the <PAM> as arguments). You can string lines like this after one another in a PAM configuration file, and the PAM framework will process them one after another at the time of an authentication request. A little extra: we can include files into our PAM configuration file using the ''@include'' statement. Thus, the file /etc/pam.d/sshd could contain the following lines: auth required pam_env.so auth required pam_env.so envfile=/etc/default/locale @include common-auth account required pam_nologin.so @include common-account @include common-session session optional pam_motd.so session optional pam_mail.so standard noenv session required pam_limits.so @include common-password The effect of this is that the files ''common-auth'', ''common-account'', ''common-session'' and ''common-passwd'' (all from directory ''/etc/pam.d/'' as well) are included into our sshd configuration. Not wholly surprisingly, file ''common-auth'' contains all common PAM authentication lines, ''common-account'' all common PAM account lines, etcetera. This makes it relatively easy to add authentication/authorisation mechanisms to our Debian server; we've only to add them to these ''common-'' files, and all services and processes will know about them. We can also include modules into our PAM configuration using the substack procedure. This includes all lines of given type from the configuration file specified as an argument to this control. A call using substack would look like this: auth substack common-auth This differs from include in that evaluation of the done and die actions in a substack does not cause skipping the rest of the complete module stack, but only of the substack. Jumps in a substack also can not make evaluation jump out of it, and the whole substack is counted as one module when the jump is done in a parent stack. The reset action will reset the state of a module stack to the state it was in as of beginning of the substack evaluation. == Invoking PAM == As you might expect from the previous texts, you can only use PAM if your application, service, daemon or program is "PAM-aware". This means, that it is coded and compiled to use PAM. Fortunately, in this day and age most applications, daemons et cetera are. However, this presents us with a true problem: that of ''choice''. When your application is PAM-aware, it means that your application can deletate just about any imaginable authentication-task to PAM - which YOU, the system administrator, must achieve by invoking PAM in just the right way. To this end, you must create a PAM configuration file, and fill it with just the right information as to have PAM perform all tasks that you want - and none other. This is because when a privilege granting application is started that is PAM aware, it activates its attachment to the PAM-API. This activation performs a number of tasks, the most important being the reading of the configuration file (more on that further on). This file list the PAMs (the "PAM modules") that will do the authentication tasks required by this application, and the appropriate behavior of the PAM-API in the event that individual PAMs fail. Now there are several ways to invoke PAM, and which ones are available to us under Debian will be more fully explored in a later section, but for now let's look at one particular method, that is also available under Debian. If we create a file in ''/etc/pam.d/'' with the name of the service that we want to have PAM perform authentication for, then that can contain the necessary PAM configuration lines, and that will be the PAM configuration for that particular service. Does that make sense? No? Then let me give you an example. Suppose we have some service with a name of ''sshd'', and we want that service to use PAM to check if a user that attempts to use the service is actuall allowed to do so. We then create ''/etc/pam.d/sshd'' and fill it with these two lines: auth required pam_unix.so session optional pam_motd.so This means we've now configured the ''sshd'' [[OpenSSH server | SSH daemon]] to use PAM for authentication/authorization. The exact instructions we've provided PAM are: check if the name and password provided to ''sshd'' by a user attempting to log in represent a valid name/password as they occur in our local Linux user account database (''/etc/passwd''). If so, we'll allow access. The second line furthermore shows a user logging in the [[MOTD_file | Message-of-the-day]], if that message exists. Think that that's easy? Almost looks like it, right? But ==An example: sshd configuration file == For a real SSH daemon, the PAM configuration file can look something like this: auth required pam_env.so auth required pam_env.so envfile=/etc/default/locale auth sufficient pam_unix.so nullok_secure auth requisite pam_succeed_if.so uid >= 1000 quiet auth sufficient pam_ldap.so use_first_pass auth required pam_deny.so account required pam_access.so account sufficient pam_unix.so account sufficient pam_succeed_if.so uid < 1000 quiet account [default=bad success=ok user_unknown=ignore] pam_ldap.so account required pam_permit.so session required pam_limits.so session required pam_unix.so session required pam_mkhomedir.so skel=/etc/skel/ umask=0022 session optional pam_ldap.so session optional pam_motd.so session optional pam_mail.so standard noenv session required pam_limits.so password sufficient pam_unix.so md5 obscure min=4 nullok try_first_pass password sufficient pam_ldap.so password required pam_deny.so Well that looks a bit intimidating, doesn't it? Do not worry, we'll explain everything in great detail, so we are quite sure that, once you get to the end of this document, you'll understand what files like this mean. And hopefully, you'll even be able to create or edit your own! In the example, there are five lines that begin with ''auth''. This means that for any authentication request, PAM consults five modules. Let's have a look at what they do: * ''auth required pam_env.so''<br>This line calls the ''pam_env.so'' PAM, which is a module that can ''only'' be called as an ''auth'' module. It is configured using the ''/etc/security/pam_env.conf'' file, and what it does is it sets a number of environmental variables for the user that tries to log in. These variables can be declared in the ''pam_env.conf'' file, and can be used to supply default values for environmental variables that are not (yet) set for the user, and to override other environmental variables for which the administrator wishes to provide different values from what the user might have configured. It's flagged ''required'', so this module must succeed or the user will be denied access. Fortunately, this module will always succeed. * '' auth required pam_env.so envfile=/etc/default/locale''<br>Hey, haven't we seen this one before? It's the same ''pam_env.so'', but now it's reading an ''envfile'', so as to set the variables that are in the file ''locale''. * '' auth sufficient pam_unix.so nullok_secure''<br>This calls the PAM named ''pam_unix.so'' in its authentication mode. The module is flagged ''sufficient'', so if this module recognises the user, then no other ''auth'' module will be consulted - effectively skipping the next three ''auth'' modules. See that order is important?<br>The module will check if the authentication attempt is made by a valid Unix user. The parameter nullok_secure makes sure that even login attempts by users with blank passwords fail, as long as they try to authenticate from a secure terminal * ''auth requisite pam_succeed_if.so uid >= 1000 quiet''<br>This module ''[http://linux.die.net/man/8/pam_succeed_if pam_succeed_if.so]'' brings a rudimentary form of flow control to our PAM configuration files. It can perform tests, and based on that test will cause a "success" or "fail" state to the ''auth'' section - but it WON'T return "success" or "fail" to the authentication attempt itself! Because it is here used with ''requisite'', a failure of this module would immediately be effective. The first argument (or set of arguments) is ''uid >= 1000''. This is the actual test that the module will be performing: if the user that is trying to authenticate has a user ID of LESS than 1000, the module will fail, and the ''requisite'' flag will cause PAM to perform no more ''auth'' module tests. The last argument of this module is a flag ''quiet'', which makes this module skip recording failure or success messages in the message log.<br>So what is now the effect of this module? For ordinary system users (who have an uid of 1000 or more), this module will do just nothing. But if this module is called for an authentication request by a service daemon, then the uid will be less than 1000, so ''pam_succeed_if.so'' will FAIL. The ''requisite'' control flag causes PAM to immediately end the ''auth'' stage of the login; that means all following ''auth'' modules will ONLY be processed for ordinary users, not service daemons. Neat, eh? * ''auth sufficient pam_ldap.so use_first_pass''<br>This module (because of the preceding line never called when daemons try to log in) will attempt to see if the user and password that need to be authenticated are valid in your LDAP server. The ''sufficient'' control flag makes sure that if the user is NOT a valid LDAP user, nothing happens. However, if he is, AND no previous ''auth'' modules have returned an auth failure, then the PAM returns "success" and the ''auth'' phase immediately ends. * ''auth required pam_deny.so''<br>This last ''auth'' module is the catchall; if no previous ''auth'' module of type ''sufficient'' has returned a success, then this module kicks in. And guess what? Called as an ''auth'' module, it ALWAYS returns "failure". The compound effect of this authentication section of the example PAM configuration is this: # Default environmental variables are set # The ''locale'' file is read # All valid Unix users, and Unix users with blank passwords from secure terminals, are authenticated OK # All valid Unix users = PAM on Debian= == PAM modules in Debian 5.0 'Lenny'== == PAM configuration files == = Configuration example= == Configuring PAM for LDAP == f2adec447d6ad3dcdb3ccc4e6476df92dc36d6d1 0 1482 1988 1834 2008-11-05T20:03:16Z Insomnia 3 Compiz wikitext text/x-wiki == NDISwrapper == NDISwrapper is a free software driver wrapper that enables the use of Microsoft Windows drivers for wireless network devices. Download the windows driver wich contains the .inf file<br> Install with ndiswrapper -i drivername.inf<br> check the device id with lsusb or lspci -n<br> Now execute with ndiswrapper -a deviceid driver ndiswrapper -a 0bda:8197 net8187b check the installed drivers ndiswrapper -l Write the configuration for modprobe ndiswrapper -m And use the module modprobe ndiswrapper == Compiz == To enable compiz install the Nvidia drivers and install CompizConfig Settings Manager sudo apt-get install simple-ccsm Now navigate to system > preferences > Appereance And go to the Visual effects tab. Choose custum there cd44db4e4ea045b2d494bfa51b549c6960484d17 1990 1988 2008-11-05T20:42:59Z 82.161.20.132 0 /* Compiz */ added table wikitext text/x-wiki == NDISwrapper == NDISwrapper is a free software driver wrapper that enables the use of Microsoft Windows drivers for wireless network devices. Download the windows driver wich contains the .inf file<br> Install with ndiswrapper -i drivername.inf<br> check the device id with lsusb or lspci -n<br> Now execute with ndiswrapper -a deviceid driver ndiswrapper -a 0bda:8197 net8187b check the installed drivers ndiswrapper -l Write the configuration for modprobe ndiswrapper -m And use the module modprobe ndiswrapper == Compiz == To enable compiz install the Nvidia drivers and install CompizConfig Settings Manager sudo apt-get install simple-ccsm Now navigate to system > preferences > Appereance And go to the Visual effects tab. Choose custum there {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Desktop Effects !style="background:#ffdead;"|Keyboard Shortcuts |- |Rotate Cube Manually |Ctrl + Alt + Left Mouse Button |- |Expo |Super + E (toggle) |- |Rotate Cube |Mousewheel on Desktop |- |Film Effect |Ctrl + Alt + Down Arrow |- |Scale Windows |Alt + Shift + Up Arrow |- |Ring Switcher |Super + Tab - overrides Shift Switcher |} 16b8c0b8dd7bb007508544cf3c1f09f53ff02ff8 1991 1990 2008-11-05T20:43:49Z 82.161.20.132 0 /* Compiz */ wikitext text/x-wiki == NDISwrapper == NDISwrapper is a free software driver wrapper that enables the use of Microsoft Windows drivers for wireless network devices. Download the windows driver wich contains the .inf file<br> Install with ndiswrapper -i drivername.inf<br> check the device id with lsusb or lspci -n<br> Now execute with ndiswrapper -a deviceid driver ndiswrapper -a 0bda:8197 net8187b check the installed drivers ndiswrapper -l Write the configuration for modprobe ndiswrapper -m And use the module modprobe ndiswrapper == Compiz == To enable compiz install the Nvidia drivers and install CompizConfig Settings Manager sudo apt-get install simple-ccsm Now navigate to system > preferences > Appereance And go to the Visual effects tab. Choose custum there {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Desktop Effects !style="background:#ffdead;"|Keyboard Shortcuts |- |Rotate Cube Manually |Ctrl + Alt + Left Mouse Button |- |Expo |Super + E (toggle) |- |Rotate Cube |Mousewheel on Desktop |- |Film Effect |Ctrl + Alt + Down Arrow |- |Scale Windows |Alt + Shift + Up Arrow |- |Ring Switcher |Super + Tab - overrides Shift Switcher |} Super key is the windows key :-) 3d0c16059d3c0bb66f64a8d3769e527cb8a804a8 1993 1991 2008-11-06T19:29:35Z Insomnia 3 Citrix client wikitext text/x-wiki == NDISwrapper == NDISwrapper is a free software driver wrapper that enables the use of Microsoft Windows drivers for wireless network devices. Download the windows driver wich contains the .inf file<br> Install with ndiswrapper -i drivername.inf<br> check the device id with lsusb or lspci -n<br> Now execute with ndiswrapper -a deviceid driver ndiswrapper -a 0bda:8197 net8187b check the installed drivers ndiswrapper -l Write the configuration for modprobe ndiswrapper -m And use the module modprobe ndiswrapper == Compiz == To enable compiz install the Nvidia drivers and install CompizConfig Settings Manager sudo apt-get install simple-ccsm Now navigate to system > preferences > Appereance And go to the Visual effects tab. Choose custum there {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Desktop Effects !style="background:#ffdead;"|Keyboard Shortcuts |- |Rotate Cube Manually |Ctrl + Alt + Left Mouse Button |- |Expo |Super + E (toggle) |- |Rotate Cube |Mousewheel on Desktop |- |Film Effect |Ctrl + Alt + Down Arrow |- |Scale Windows |Alt + Shift + Up Arrow |- |Ring Switcher |Super + Tab - overrides Shift Switcher |} Super key is the windows key :-) == Citrix Ica client == Download the Linux citrix ica client from Citrix http://citrix.com/English/SS/downloads/details.asp?downloadID=3323&productID=-1 Unpack the package and execute the installation script ./setupwfc Find the plugin directory of firefox. Probably is /usr/lib/firefox/plugins/ otherwise use find / -name plugins | grep -i "netscape\|firefox\|mozilla" Create a symlink to the citrix ica library ln –s /usr/lib/ICAClient/npica.so npica.so If you open a connection to your citrix server. The browser will ask you if you want to open or save the session. Browse to the ica client /usr/lib/ICAClient/wfica and tell it to use it for all applications. When you get a ssl error "you have not chosen to thrust....." Then copy the certificate in this location. /usr/lib/ICAClient/keystore/cacerts/ a6f42ae209edbd02c82eff47a3ca142fd7364f77 1994 1993 2008-11-07T17:58:12Z Insomnia 3 mount a share wikitext text/x-wiki == NDISwrapper == NDISwrapper is a free software driver wrapper that enables the use of Microsoft Windows drivers for wireless network devices. Download the windows driver wich contains the .inf file<br> Install with ndiswrapper -i drivername.inf<br> check the device id with lsusb or lspci -n<br> Now execute with ndiswrapper -a deviceid driver ndiswrapper -a 0bda:8197 net8187b check the installed drivers ndiswrapper -l Write the configuration for modprobe ndiswrapper -m And use the module modprobe ndiswrapper == Compiz == To enable compiz install the Nvidia drivers and install CompizConfig Settings Manager sudo apt-get install simple-ccsm Now navigate to system > preferences > Appereance And go to the Visual effects tab. Choose custum there {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Desktop Effects !style="background:#ffdead;"|Keyboard Shortcuts |- |Rotate Cube Manually |Ctrl + Alt + Left Mouse Button |- |Expo |Super + E (toggle) |- |Rotate Cube |Mousewheel on Desktop |- |Film Effect |Ctrl + Alt + Down Arrow |- |Scale Windows |Alt + Shift + Up Arrow |- |Ring Switcher |Super + Tab - overrides Shift Switcher |} Super key is the windows key :-) == Mount Network Share == First install smbfs apt-get install smbfs Then create a folder inside of the /media directory to mount the share on or choose you're own directory sudo mkdir /media/Storage Ik you get error whem you shut down the pc ''CIFS VFS: server not responding'' then you have to unmount first. Do this with the following ln -s /etc/init.d/umountnfs.sh /etc/rc0.d/K15umountnfs.sh ln -s /etc/init.d/umountnfs.sh /etc/rc6.d/K15umountnfs.sh == Citrix Ica client == Download the Linux citrix ica client from Citrix http://citrix.com/English/SS/downloads/details.asp?downloadID=3323&productID=-1 Unpack the package and execute the installation script ./setupwfc Find the plugin directory of firefox. Probably is /usr/lib/firefox/plugins/ otherwise use find / -name plugins | grep -i "netscape\|firefox\|mozilla" Create a symlink to the citrix ica library ln –s /usr/lib/ICAClient/npica.so npica.so If you open a connection to your citrix server. The browser will ask you if you want to open or save the session. Browse to the ica client /usr/lib/ICAClient/wfica and tell it to use it for all applications. When you get a ssl error "you have not chosen to thrust....." Then copy the certificate in this location. /usr/lib/ICAClient/keystore/cacerts/ e30c93b9af7784435d80a6cc716da191c04e81b7 1995 1994 2008-11-07T19:17:41Z Insomnia 3 /* Mount Network Share */ wikitext text/x-wiki == NDISwrapper == NDISwrapper is a free software driver wrapper that enables the use of Microsoft Windows drivers for wireless network devices. Download the windows driver wich contains the .inf file<br> Install with ndiswrapper -i drivername.inf<br> check the device id with lsusb or lspci -n<br> Now execute with ndiswrapper -a deviceid driver ndiswrapper -a 0bda:8197 net8187b check the installed drivers ndiswrapper -l Write the configuration for modprobe ndiswrapper -m And use the module modprobe ndiswrapper == Compiz == To enable compiz install the Nvidia drivers and install CompizConfig Settings Manager sudo apt-get install simple-ccsm Now navigate to system > preferences > Appereance And go to the Visual effects tab. Choose custum there {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Desktop Effects !style="background:#ffdead;"|Keyboard Shortcuts |- |Rotate Cube Manually |Ctrl + Alt + Left Mouse Button |- |Expo |Super + E (toggle) |- |Rotate Cube |Mousewheel on Desktop |- |Film Effect |Ctrl + Alt + Down Arrow |- |Scale Windows |Alt + Shift + Up Arrow |- |Ring Switcher |Super + Tab - overrides Shift Switcher |} Super key is the windows key :-) == Mount Network Share == First install smbfs apt-get install smbfs Then create a folder inside of the /media directory to mount the share on or choose you're own directory sudo mkdir /media/Storage Create a credentials file in /root so that you can save your password and have it protected by the root account: sudo gedit /root/.cifscredentials Add this to the file username=Guest password= sudo vi /etc/fstab Add the following line //192.168.0.10/SHARENAME /media/Storage cifs auto,iocharset=utf8,uid=USER,gid=users,credentials=/root/.cifscredentials,file_mode=0775,dir_mode=0775 0 0 To check if the file works sudo mount -a And you should see you're drives on the desktop Ik you get error when you shut down the pc ''CIFS VFS: server not responding'' then you have to unmount first. Do this with the following ln -s /etc/init.d/umountnfs.sh /etc/rc0.d/K15umountnfs.sh ln -s /etc/init.d/umountnfs.sh /etc/rc6.d/K15umountnfs.sh == Citrix Ica client == Download the Linux citrix ica client from Citrix http://citrix.com/English/SS/downloads/details.asp?downloadID=3323&productID=-1 Unpack the package and execute the installation script ./setupwfc Find the plugin directory of firefox. Probably is /usr/lib/firefox/plugins/ otherwise use find / -name plugins | grep -i "netscape\|firefox\|mozilla" Create a symlink to the citrix ica library ln –s /usr/lib/ICAClient/npica.so npica.so If you open a connection to your citrix server. The browser will ask you if you want to open or save the session. Browse to the ica client /usr/lib/ICAClient/wfica and tell it to use it for all applications. When you get a ssl error "you have not chosen to thrust....." Then copy the certificate in this location. /usr/lib/ICAClient/keystore/cacerts/ a2728d748503ece19d64605a1ce3a9b0c88cab3b 2009 1995 2008-11-11T17:05:49Z 82.161.20.132 0 Convert video_ts to iso wikitext text/x-wiki == NDISwrapper == NDISwrapper is a free software driver wrapper that enables the use of Microsoft Windows drivers for wireless network devices. Download the windows driver wich contains the .inf file<br> Install with ndiswrapper -i drivername.inf<br> check the device id with lsusb or lspci -n<br> Now execute with ndiswrapper -a deviceid driver ndiswrapper -a 0bda:8197 net8187b check the installed drivers ndiswrapper -l Write the configuration for modprobe ndiswrapper -m And use the module modprobe ndiswrapper == Compiz == To enable compiz install the Nvidia drivers and install CompizConfig Settings Manager sudo apt-get install simple-ccsm Now navigate to system > preferences > Appereance And go to the Visual effects tab. Choose custum there {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Desktop Effects !style="background:#ffdead;"|Keyboard Shortcuts |- |Rotate Cube Manually |Ctrl + Alt + Left Mouse Button |- |Expo |Super + E (toggle) |- |Rotate Cube |Mousewheel on Desktop |- |Film Effect |Ctrl + Alt + Down Arrow |- |Scale Windows |Alt + Shift + Up Arrow |- |Ring Switcher |Super + Tab - overrides Shift Switcher |} Super key is the windows key :-) == Mount Network Share == First install smbfs apt-get install smbfs Then create a folder inside of the /media directory to mount the share on or choose you're own directory sudo mkdir /media/Storage Create a credentials file in /root so that you can save your password and have it protected by the root account: sudo gedit /root/.cifscredentials Add this to the file username=Guest password= sudo vi /etc/fstab Add the following line //192.168.0.10/SHARENAME /media/Storage cifs auto,iocharset=utf8,uid=USER,gid=users,credentials=/root/.cifscredentials,file_mode=0775,dir_mode=0775 0 0 To check if the file works sudo mount -a And you should see you're drives on the desktop Ik you get error when you shut down the pc ''CIFS VFS: server not responding'' then you have to unmount first. Do this with the following ln -s /etc/init.d/umountnfs.sh /etc/rc0.d/K15umountnfs.sh ln -s /etc/init.d/umountnfs.sh /etc/rc6.d/K15umountnfs.sh == Citrix Ica client == Download the Linux citrix ica client from Citrix http://citrix.com/English/SS/downloads/details.asp?downloadID=3323&productID=-1 Unpack the package and execute the installation script ./setupwfc Find the plugin directory of firefox. Probably is /usr/lib/firefox/plugins/ otherwise use find / -name plugins | grep -i "netscape\|firefox\|mozilla" Create a symlink to the citrix ica library ln –s /usr/lib/ICAClient/npica.so npica.so If you open a connection to your citrix server. The browser will ask you if you want to open or save the session. Browse to the ica client /usr/lib/ICAClient/wfica and tell it to use it for all applications. When you get a ssl error "you have not chosen to thrust....." Then copy the certificate in this location. /usr/lib/ICAClient/keystore/cacerts/ == Make DVD == To make a video DVD you can burn you're image on the dvd. If you just have the VIDEO_TS files then the easiest way is to convert these into a iso. mkisofs -dvd-video -o ~/moviename.iso /path/to/the/VIDEO_TS 5846e9706aa9fa125de0bce3ae38db93a0d0e33b 0 1493 1997 2008-11-08T09:42:20Z Saruman! 2 Page started wikitext text/x-wiki When dealing with security, there are a couple of terms that keep coming back, and that are slightly ''narrower'' in scope than people usually believe. These terms are authentication, authorization and privilege, and they all deal with identity. ==Identity== When we're talking about IT security, we're essentially talking about things related to '''digital identity'''. Without recreating a whole scientific piece about it, we can put forward the following relevant observations: * a digital subject is an entity with a digital identity attached to it, e.g. the human Joe Sixpack with the digital identity "sixpacjo", or the machine humming in my attic with the digital identity ''www.saruman.biz'' attached to it; * a digital subject can be human or non-human. Examples are: a user (obviously), a server, a web site, a message et cetera; * a digital identity has one or more identity attributes. Examples are: a name, a login name, a surname, group membership(s), access flags, a URI, an email address, a picture file (digital photo) et cetera; * the holder of a digital identity does not want to present ''all'' the identity attributes to ''everyone''. E.g. you don't show your passport, drivers license and social security number to the waiter at the restaurant where you reserved a table, and you don't give your e-mail address to every website you visit (at least, we hope you don't!). Thus, for each process that needs a digital identity, the holder wishes to present only those attributes that are necessary and agreed upon by both sides. ==Authentication== The question of authentication can be reduced to a single central question: '''is the entity indeed who he/she/it claims to be?''' Slightly more formal: when an entity claims to be a certain digital subject, can we trust this to be true? For an example: the user logging in to the server claims to be "root" - but is this really our own administrator, or is this a malicious cracker? Usually, a digital identity authenticates itself by presenting a unique object, a unique piece of information. In real life, authentication can be by use of your passport or credit card; in computers, we very often see the use of passwords or passphrases. But of course, a user could authenticate by presenting a fingerprint scan, or a one-time pass token that the system knows has been issued to the user that this digital identity claims to be. ==Privilege== Ahh, this is what it's all about: what privileges can we get? A privilege can be reduced to the simple question '''what is it that the digital subject wants?''' This basically means read access to information, write access on information, permission to execute a program or script, or permission to perform any other action within the system. The simple fact that a user has sufficiently proven that he is who he claims to be (e.g. digital entity "sixpacjo") does NOT mean that he gets to perform the action that he requested; editing the time zone file ''/etc/timezone'' on my home server is strictly reserved to digital entity "root", even though "sixpacjo" ''does'' enjoy the privilege of reading this file, if he so pleases. ==Authorization== So with the above, it's now pretty clear what we mean by authorization: '''Is the user allowed to do this?''' Or a bit more formal: does the entity have permission to exercise a privilege? Thus, an authorization question should always be answerable with "yes", "no" or "not enough information". In the example above: user "sixpacjo" does not have the privilege of editing my timezone file; when he tries, the authorization mechanism in my server must provide answer "no" on his attempt. This means that when "sixpacjo" tries to write to my timezone file, he gets "permission denied" from the program that does the write attempt (e.g. the shell or [[vim | vi]]). ==Wrapup== Let's go through a scenario that uses all the above terms: a user surfs onto the Wiki [https://www.saruman.biz/wiki]. He 17cb3f47427eba744402bc06de908ba95c9c1c69 1998 1997 2008-11-08T10:04:29Z Saruman! 2 /* Wrapup */ created example wikitext text/x-wiki When dealing with security, there are a couple of terms that keep coming back, and that are slightly ''narrower'' in scope than people usually believe. These terms are authentication, authorization and privilege, and they all deal with identity. ==Identity== When we're talking about IT security, we're essentially talking about things related to '''digital identity'''. Without recreating a whole scientific piece about it, we can put forward the following relevant observations: * a digital subject is an entity with a digital identity attached to it, e.g. the human Joe Sixpack with the digital identity "sixpacjo", or the machine humming in my attic with the digital identity ''www.saruman.biz'' attached to it; * a digital subject can be human or non-human. Examples are: a user (obviously), a server, a web site, a message et cetera; * a digital identity has one or more identity attributes. Examples are: a name, a login name, a surname, group membership(s), access flags, a URI, an email address, a picture file (digital photo) et cetera; * the holder of a digital identity does not want to present ''all'' the identity attributes to ''everyone''. E.g. you don't show your passport, drivers license and social security number to the waiter at the restaurant where you reserved a table, and you don't give your e-mail address to every website you visit (at least, we hope you don't!). Thus, for each process that needs a digital identity, the holder wishes to present only those attributes that are necessary and agreed upon by both sides. ==Authentication== The question of authentication can be reduced to a single central question: '''is the entity indeed who he/she/it claims to be?''' Slightly more formal: when an entity claims to be a certain digital subject, can we trust this to be true? For an example: the user logging in to the server claims to be "root" - but is this really our own administrator, or is this a malicious cracker? Usually, a digital identity authenticates itself by presenting a unique object, a unique piece of information. In real life, authentication can be by use of your passport or credit card; in computers, we very often see the use of passwords or passphrases. But of course, a user could authenticate by presenting a fingerprint scan, or a one-time pass token that the system knows has been issued to the user that this digital identity claims to be. ==Privilege== Ahh, this is what it's all about: what privileges can we get? A privilege can be reduced to the simple question '''what is it that the digital subject wants?''' This basically means read access to information, write access on information, permission to execute a program or script, or permission to perform any other action within the system. The simple fact that a user has sufficiently proven that he is who he claims to be (e.g. digital entity "sixpacjo") does NOT mean that he gets to perform the action that he requested; editing the time zone file ''/etc/timezone'' on my home server is strictly reserved to digital entity "root", even though "sixpacjo" ''does'' enjoy the privilege of reading this file, if he so pleases. ==Authorization== So with the above, it's now pretty clear what we mean by authorization: '''Is the user allowed to do this?''' Or a bit more formal: does the entity have permission to exercise a privilege? Thus, an authorization question should always be answerable with "yes", "no" or "not enough information". In the example above: user "sixpacjo" does not have the privilege of editing my timezone file; when he tries, the authorization mechanism in my server must provide answer "no" on his attempt. This means that when "sixpacjo" tries to write to my timezone file, he gets "permission denied" from the program that does the write attempt (e.g. the shell or [[vim | vi]]). ==Wrapup== Let's go through a scenario that uses all the above terms: a user surfs onto the Wiki [http://www.saruman.biz/wiki www.saruman.biz/wiki]. The web server presents the home page to this '''entity''', which by default has the ''digital identity'' of the IP number he is surfing from. The user clicks on "log in" in the top right hand side, and provides the information "user = sixpacjo, password = SuperSecret". The information he puts in the "user" field is attached to this web session, and the user now has the '''digital identity''' of sixpacjo. However, the user is still unauthenticated! The Wiki software then checks the username and password against the information in the Wiki database; it turns out that the password provided by the alledged user sixpacjo matches the one stored in the database; since only user sixpacjo is supposed to know this password, the user is now '''authenticated''', i.e. the Wiki software now believes that in this web session it is dealing with the one and only user named sixpacjo. While surfing around, the user notices an omission in a web page, and clicks the "edit" button. After writing in the omitted data, he clicks "Save page". The write request is sent to the wiki software, which then performs an '''authorization''' test: it checks if for that particular Wiki page the user sixpacjo has the necessary writing '''privilege''' - which he has. Thus, the test "user sixpacjo is allowed to write to this wiki page?" comes back positive: "YES", and the Wiki software stores the edit. What muddles this example slightly is that all concepts (identity, authentication mechanism, authorization mechanism, privileges) exist in the single entity "wiki software". When we talk about bigger systems, e.g. your whole home server, these concepts can be distributed. e.g. identities can exist in multiple places (''passwd'' file and OpenLDAP database), both authentication and authorization can be performed by (separate) [[Pluggable Authentication Modules (PAM) | PAM]] modules, and the privileges consist of read/write/execute permissions on files and directories in the file system on the server. And other systems, like corporate networks, can have identities in one database, and policies (which provide the authorization data) in another. 6cc5ddc4251d2073093e588350049cf5dd0522bb 2 1410 1999 1901 2008-11-08T10:13:32Z Saruman! 2 minor edit wikitext text/x-wiki <big>'''Saruman!'''</big> I'm part of the [[Saruwiki:about | Administrators team]] of this site. As you can read under the team description, I work as a technical infrastructure consultant at a large IT company. As such, I help customers with Unix and Linux servers, identity management, security, virtualization, networks and documentation - although occasionally I have to work with Microsoft Windows networks as well. My qualifications are, amongst others, [http://www.lpi.org/ LPI] certifications ([http://www.lpi.org/en/lpi/english/certification/the_lpic_program LPIC1 and LPIC2] - LPIC 3 is too difficult for me, I fear). I give a small number of Linux/Unix classes and workshops to co-workers. Furthermore, I'm very interested in infrastructure architecture ("technical architecture"), and I'm working on the credentials needed to perform in that particular field. In my spare time (if any), I listen to progressive rock music (especially work by [http://www.the-company.com/ Fish]), organize my music in my oversized iTunes library, ride a hi-tech hybrid car, read sci-fi and fantasy (not nearly often enough, though :-(, and play a bit with my digital camera, a [http://www.canon-europe.com/For_Home/Product_Finder/Cameras/Digital_SLR/EOS_20th_Anniversary/2004-2007.asp Canon EOS350D]. I'm married and have one daughter. 12ba5045ffd611abbce09b5f8c7142f55d1bcfdb 0 1476 2004 1743 2008-11-09T10:55:58Z Saruman! 2 worked on m-a a-i wikitext text/x-wiki =Zaptel driver= To compile the Zaptel driver, we first install support for certain functions (a.o. deflate compression method): sudo apt-get install zlib1g-dev libssl-dev bison debhelper Specifically the last one (''debhelper'') can bring a whole slew of extra packages with it, a.o. ''build-essential'', ''po-debconf'', ''liburi-perl'' and ''patch'', just to name a few. Next up is to get the zaptel source code, as is delivered with Debian Lenny: sudo apt-get install zaptel-source If there are any dependencies not yet satisfied, you'll see those packages come with the source code (e.g. ''module-assistant''). Once the Zaptel source code is on our system, it is up to us to create the driver. Debian can't handle this for us, as the Zaptel driver has to precisely match both our hardware platform and the Linux kernel we're using. So we're going to compile our own driver - yippee!<br> Debian has placed the source file package in ''/usr/src'', and it's named ''zaptel.tar.bz2''. Normally you would think about unpacking it with ''sudo tar xjvf'' and get going with the code that's in it. HOWEVER Debian has a really cool utility called the ''module-assistant''. This program is the command-line tool for handling module-source packages that have been prepared for the Debian distribution. It helps users to build and install module packages easily for one or more kernels, even custom ones. We start from the beginning: * boot your system under the kernel for which you want to create the Zaptel drivers, if you haven't already done so * as root, run ''module-assistant prepare''. This checks the availability of your kernel source header files, creates a symlink ''/usr/src/linux'' that points to your kernel source files, and checks if you have all Debian packages you're going to need (e.g. ''build-essentials''). * Then, again as root, run ''module-assistant auto-install zaptel'' (or abbreviate it to ''m-a a-i zaptel''). After a while (may be multiple minutes) the command completes.The output hopefully ends with something like "Setting up zaptel-modules-2.6.27.5 (1:1.4.11~dfsg-2) ..." - note: the number before the parenthesis should match the kernel version for which you're compiling the module - in this case we're running kernel 2.6.27.5, and the Zaptel module we've compiled is for this specific kernel. * Some howto's now instruct you to run ''update-modules'', but with modern Debian distributions like 4.0 "Etch" or 5.0 "Lenny" this is not the case; running it won't harm you, because there's a pseudo-command installed, but it won't do a single thing either... * If you have hardware installed, you now run ''genzaptelconf -svdM''. It will stop any Asterisk you might have running, be verbose, detect any modules on your hardware, update ''/etc/modules'', and finally create your hardware config file ''/etc/zaptel.conf''; it probably will give you a nice error message too about not being able to write in the ''/etc/asterisk'' directory - that's simply because we haven't installed asterisk itself yet! Note: if you live outside the U.S.A., you might want to specify which country you live in, to get the correct dialing tones etcetera. It is as simple as specifying your country (two-letter code): ''genzaptelconf -svdM -c nl''. The output is pretty clear in what the command finds, and what it does with that information. * You may want to now edit the configuration file that's created for the channels. The configuration file should be ''/etc/zaptel.conf'', and its contents could look like the file given below. However, you rarely need to edit this file by hand: ''genzaptelconf'' can handle this bit usually better than we can. # Span 1: WCTDM/0 "Wildcard TDM410P Board 1" (MASTER) fxols=1 fxols=2 fxsks=3 # channel 4, WCTDM/0/3, no module. # Global data loadzone = us defaultzone = us * If you wish, you can create directory ''/etc/asterisk'', and run the ''genzaptelconf'' again; that way you can see the ''zapata-channels.conf'' file that is created as well. * If you now reboot (into the same kernel), then the ''dmesg'' command should confirm the presence of your Zaptel drivers with a short section like this: Zapata Telephony Interface Registered on major 196 Zaptel Version: 1.4.11 Zaptel Echo Canceller: MG2 Furthermore, you can find lines like these, if you have hardware installed: ACPI: PCI Interrupt 0000:03:07.0[A] -> GSI 21 (level, low) -> IRQ 21 Port 1: Installed -- AUTO FXS/DPO Port 2: Installed -- AUTO FXS/DPO Port 3: Installed -- AUTO FXO (FCC mode) Port 4: Not installed VPM100: Not Present Found a Wildcard TDM: Wildcard TDM410P (4 modules) =Zaptel tools= Next up, if you haven't yet done so during the preceding step, you now need to install the ''zaptel'' userland tools (v1.4.11 under Debian 5.0), which will in turn require ''fxload'' and ''libtonezone1''. Installation is simply performed by sudo apt-get install zaptel fxload libtonezone1 After installation, the ''zaptel'' driver checks for the existance of ''/etc/zaptel.conf''. When you've never before had Zaptel on your system, or haven't finished configuration in the preceding step, then you probably get the message zaptel : /etc/zaptel.conf fails test for exists and readable This is in fact a friendly reminder that you first have to create this file, before you try to load the driver. =libpri installation= Asterisk needs the ''libpri'' package; not only to handle ISDN-cards, but also for some other functions (although currently I don't know which ones :-). Before installing Asterisk, you could start by installing this package. In Debian 5.0 "Lenny", the packages is named ''libpri1.0'': apt-get install libpri1.0 d3c1be50c4bfe424e095d9af03a13f64988fbf0f 0 1467 2005 1714 2008-11-09T20:32:52Z Saruman! 2 added memberUid index wikitext text/x-wiki == OpenLDAP installation and configuration== Note: we're going to install OpenLDAP on our server as [http://www.openldap.org/doc/admin24/config.html#Local%20Directory%20Service the local directory service], without replication, referrals or other advanced features. Installing OpenLDAP on your Debian server is ridiculously simple. Just make sure your server is up-to-date (''sudo apt-get update'' followed by ''sudo apt-get upgrade''), and then install the two main components for your OpenLDAP server: sudo apt-get install slapd ldap-utils The Debian configuration script will ask you for only one single thing: an administrator password. As always: generate a strong password! When you've provided the password, the LDAP database is created with the administrator name "admin" and as a base directory path, something based on your DNS name. Suppose your internal domain is "amber.lan.", then the script will generate ''suffix "dc=amber,dc=lan,dc="''. The last, empty, domain component (''dc'') is caused by the trailing dot in your DNS name: the DNS root. Since this might not always be the most convenient configuration, we recommend that you run the configuration again using ''dpkg-reconfigure slapd''. Interestingly enough, this reconfiguration asks you many ''more'' questions. The answers could look like this: omit OpenLDAP config: no DNS domain name: saruman.biz Organization name: Saruman Administrator passwd: wEt3udes Database backend: HDB DB remove after purge: no Move old DB: yes Allow LDAPv2: no As you can see, the reconfiguration yields much more configuration options than plain installation - although really you'll probably answer most questions with their default values anyway, with the exception of the database backend, which by default is BDB.<br> Anyway, the above method of configuring yields you an LDAP database with only two objects in it: * a single Organization (o="Saruman") with Distinguished Name dn="dc=saruman,dc=biz" * a single administrator with Common Name cn="admin", and dn="cn=admin,dc=saruman,dc=biz" The database that your OpenLDAP server uses is a standard Berkeley DB (BDB) database. Now we most likely will require some other databases as well in our server setup, something modern like PostgreSQL or MySQL - so why don't we configure our OpenLDAP to use this same database as well? For the answer, see [http://www.openldap.org/doc/admin24/intro.html#LDAP%20vs%20RDBMS here] - in short, the LDAP tree structure does not lend itself very well to inclusion in a modern relational database. Thus, we advise to stick with the Berkeley database provided with OpenLDAP.<br> Now, for the database backend, we have the choice between two almost identical flavours: the ''bdb'' backend is the recommended primary backend for a normal slapd database. It uses the Oracle Berkeley DB package, referred to as ''BDB'', to store data. It makes extensive use of indexing and caching to speed data access. ''hdb'' is a variant of the ''bdb'' backend that uses a hierarchical database layout which supports subtree renames. It is otherwise identical to the ''bdb'' behavior, and all the same configuration options apply. To finetune the OpenLDAP configuration, we make some changes to the main configuration file for the OpenLDAP server, ''/etc/ldap/slapd.conf''. Note: make SURE that the permissions on this file are rw-r----- (640) and the owner is root:openldap. We find the line beginning with "loglevel" and change it from ''none'' to ''256''. This value means connections/operations/results wil be logged to the ''syslogd'' daemon. There, it will be logged to the ''LOG_LOCAL4'' facility. The default hash algorithm for encrypting user passwords is {SSHA}, which is the SHA-1 algorithm (FIPS160-1) wit a seed number. However, OpenLDAP can understand more hashes, even multiple at the same time. To specify which hash or hashes, we can specify something like password-hash {SSHA} {MD5} Valid hashes are {SHA}, {SSHA} (the default, {MD5}, {SMD5}, {CRYPT} and {CLEARTEXT}. We usually don't need to change the default, but if you do, put in the directive and restart your LDAP server. More information: "man 5 slapd.conf". We find the line beginning with ''index'', and add a second line to it. This will make the section look like this: index objectClass eq index uid eq index memberUid eq The purpose of this change is to make the OpenLDAP server create another index, on LDAP attribute ''uid'', and another one on LDAP attribute ''memberUid''. The ''uid'' index is important, because under some circumstances you might not receive any result on a valid query unless the searched entries are indexed. This entry makes sure all objects with a ''uid'' attribute are indexed, and thus can be found when queried. The ''memberUid'' index is not so important, but creating it will prevent a lot of informational messages in our syslog that go like Nov 9 20:24:40 dworkin slapd[13998]: <= bdb_equality_candidates: (memberUid) not indexed Finally, we check to be certain all necessary schema's are included: in the beginning of the file we should see include /etc/ldap/schema/core.schema include /etc/ldap/schema/cosine.schema include /etc/ldap/schema/nis.schema include /etc/ldap/schema/inetorgperson.schema If any line got missing, we need to (re)enter it in order to be able to create the LDAP entries that we want. After these little refinements, we must stop, reindex, and restart the OpenLDAP server. This can be done with the following sequence of commands: sudo invoke-rc.d slapd stop sudo -u openldap slapindex sudo invoke-rc.d slapd start Note: you need to have your ''sudo'' configured to allow you to ''su'' to user ''openldap'' in order to run the second command. ==Installing and configuring an LDAP Account Manager== It's perfectly normal to manipulate your LDAP from the command line using LDAP utilities like ''ldapsearch'', ''ldapadd'', ''ldapdelete'' and ''ldapmodify'', as well as ''slapcat'', ''slappasswd'' etcetera. However, many people find a GUI for LDAP indispensible. If you are amongst those, then for you, my friend, the question becomes: which graphic tool do you want to use? Many people speak highly of ''[http://gq-project.org/ gq]'', ''[http://luma.sourceforge.net/about.html luma]'' and ''[http://phpldapadmin.sourceforge.net/ phpldapadmin]''. We go for ''lam'' ([http://lam.sourceforge.net/index.htm LDAP acount Manager]).<br> To install ''lam'', first ensure that you have installed Apache2 and PHP5. Then we can use ''apt-get install ldap-account-manager''. After installation, we can right away surf to http://<server-IP>/lam, where we can log in. However, note that in the upper right, there's a link ''LAM configuration''. We'll go there first. Under the LAM configuration page, there are two links to areas, where settings can be specified. The first one is "Edit general settings", and clicking it prompts you for a master password - by default this is "lam". Behind that password is a simple settings page, that can be filled with values like this ('''bold''' values deviate from the default): * Security settings ** Session timeout: '''15''' (the amount of minutes of inactivity that's allowed before a user is logged off) ** Allowed hosts: '''192.168.67.*''' (the range of IP numbers from which LAM accepts connections; empty would mean "all" so we recommend limiting the scope to your internal network, or even less if possible. Multiple hosts or network ranges can be inserted below each other) * Password policy (in this section you can specify lower limits on your LDAP passwords - tho currently it's not clear to us what you're limiting. We suspect it's the creation of all LDAP passwords from within LAM). ** Minimum password length: '''6''' ** Minimum lowercase characters: 0 ** Minimum uppercase characters: 0 ** Minimum numeric characters: 0 ** Minimum symbolic characters: 0 ** Minimum character classes: '''3''' (The character classes are: lowercase, uppercase, numeric and symbols) * Logging ** Log level: notice (this is the most detailed level; "warning" logs less information, "error" less still) ** Log destination: syslog (outputs all LAM messages to the syslogger; alternatively specify "no logging" or a file name & location) * Change master password ** New master password: '''*****''' (this is the password that'll replace "lam" to log into the LAM configuration; it is NOT the password of your rootdn, and if anywhere possible, you should avoid using that particular password here - for safety. Generate [http://www.pctools.com/guides/password/ yet another strong password].) ** Reenter new master password: '''*****''' After entering the above settings, we at least know LAM is operational, and coarsely secured (it's not using SSL yet). Click ''OK'' to save, or ''back to login'' if you change your mind and just want to go back. The second link from the LAM configuration page, "Edit server profiles" will again prompt you. However, this password prompt page contains an extra pulldown option, currently filled with the word "lam". This is because there is only one server profile, named "lam", and filled with some default values for your LDAP server. And under those two boxes, there's a link "manage server profiles".<br> Now first we'll rename that profile to something more descriptive. Click the "manage server profiles" link, in the "profile management page" check the radio button next to ''&#091;lam&#093; Rename profile'', put in the new name (e.g. "sarumanbiz"), fill in the shiny new master LAM password &#8212; it should no longer be the default "lam" since you've changed it, in line with the paragraph above :-) &#8212; and then click OK. Presto! The server profile is renamed.<br> When you now enter your password to edit the server preferences for profile "sarumanbiz", you get to a page with a lot of settings; the only ones we're currently interested in are: * Server settings ** Server address: ldap://localhost:389 (verify that it's either localhost, if both the LDAP server and your LAM Apache2 are on the same machine, or a correct IP address or DNS name if that's not the case) ** Tree Suffix: '''dc=saruman,dc=biz''' (the same suffix you've installed your LDAP server with) * Account types ** Edit Account types *** Users **** LDAP Suffix: '''ou=people,dc=saruman,dc=biz''' (You'll have to designate an OU in which to store user accounts; it does not have to exist yet (LAM can create it for you any time you log in) but the base has to be accessible; in our example: saruman.biz. Any name will do, but since we're storing identities, and not specifically users, we're calling the OU "people") *** Groups **** LDAP Suffix: '''ou=groups,dc=saruman,dc=biz''' (This is the OU where groups will be stored) *** Hosts **** LDAP Suffix: '''ou=hosts,dc=saruman,dc=biz''' (This is where machines, i.e. hosts, will be stored) *** Samba domains **** LDAP Suffix: '''ou=domains,dc=saruman,dc=biz''' (This is where all Windows workgroups/domains will wind up) * Security settings ** List of valid users: '''cn=admin,dc=saruman,dc=biz''' (or whatever you've designated your root DN) ** New password: '''''leave empty''''' (because this is to change the master password to edit ''this'' server profile; when this remains empty, the "master master password" for LAM remains in effect) ** Reenter password: (make this the same as the new password, i.e. empty) Now click OK, and your LAM should be ready to go. When you first log into the LAM profile you've just created, LAM will ask you if it should create the four OU's you've designated for people/groups/machines/domains. This is a nice test: if LAM cannot create those OU's, then you've misconfigured it (or the LDAP tree itself). If it can, then you'll be able to click ''tree view'' and browse the LDAP tree. At least the administrator (e.g. cn=admin) and the four OU's (e.g. domains/groups/hosts/people) should be present under the root (e.g. dc=saruman,dc=biz).<br> Incidentally, the configuration you've just entered into LAM as profile "sarumanbiz" can also be found at ''/usr/share/ldap-account-manager/config/sarumanbiz.conf'', so if need be, you can edit the profile by hand. ==Securing LAM communications with SSL== Until just now, all communications with LAM have taken place over unencrypted connections - not a nice way to work in a production environment. We really need to use SSL to secure the LAM environment. Fortunately, that is as easy as enabling SSL on the underlying Apache2 webserver. ==Where to go from here== This completes the setup of the LDAP server. * To fill it with relevant data, go to [[Filling an OpenLDAP database | the next section]]. * To set your system to accept LDAP users logging in to the machine, [[Accessing_a_shell_with_LDAP_authentication | go here]]. f49b450eba236a439c65753cce7d94b25f2b0f2a 0 1472 2007 1698 2008-11-10T20:46:54Z Saruman! 2 /* Creating your first Organizational Units */ removed invalid "structuralobjectClass" wikitext text/x-wiki == Creating your first Organizational Units == On the offchance that you haven't installed LAM, and thus haven't created the organizational units ''people'', ''groups'', ''hosts'' and ''domains'', here's how to create them manually. Create a file containing the following information: <pre> dn: ou=people,dc=saruman,dc=biz ou: people objectClass: top objectClass: organizationalUnit dn: ou=groups,dc=saruman,dc=biz ou: groups objectClass: top objectClass: organizationalUnit dn: ou=hosts,dc=saruman,dc=biz ou: hosts objectClass: top objectClass: organizationalUnit dn: ou=domains,dc=saruman,dc=biz ou: domains objectClass: top objectClass: organizationalUnit </pre> Let's suppose this file is named ''orgunits.ldif''. Now from the directory that contains this file, feed the information into your OpenLDAP using the following commands: sudo invoke-rc.d slapd stop sudo slapadd -c -v -l orgunits.ldif sudo invoke-rc.d slapd start This effectively stops the server, writes the information directly into the database, and then starts the server again. Another way to do (almost) the ''same'' thing, would be to add the information with the ''ldapadd'' command: ldapadd -c -x -D cn=admin,dc=saruman,dc=biz -W -f orgunits.ldif This binds to the OpenLDAP server (which must be running) using the admin account. This in turn causes the command to request the admin password, and then feed the contents from the ''orgunits.ldif'' file into the database. However, adding data to a live database precludes you from adding system controlled attributes, as structuralObjectClass is. So for live addition, remove those four particular lines from the ''orgunits.ldif'' file. Explanation of this difference: ''slapadd'' is meant as a restore tool, so it must (and can) create system controlled attributes. ''ldapadd'' is a modification tool, so it shouldn't need to (and can't) create these attributes. ==Migrating User, Password and Group entries to an LDAP server== It's nice to have an LDAP, but it's ''much'' nicer if it is filled with information. We'll try to enter all existing users and groups from the host server into LDAP, using [[Migrating existing Unix users to OpenLDAP | the available migration tools]]. ==Creating new users == If we need new users (e.g. when the server you're setting up is spankin' new) then we can create them in several ways. Let's discuss two of them: === Adding a user with an LDIF file=== To add a user with the LDAP command line utilities, we first need to create an LDIF file. This file is a simple text file, created with a text editor like ''[[vim | vi]]''. The file could look something like the text below. In that file, we create a posix group "networkusers", and a user "sixpacjo" that's a member of this posix group. However, first we need to [http://www.pctools.com/guides/password/ generate a password] for our user, e.g. "raQaMad3", then hash it: slappasswd -u -h {SSHA} -s raQaMad3 {SSHA}OcAQWgcTCzpu6v8n4yUUthiKPM6rlODq Now with this hashed password, and all other information on user sixpacjo and group networkusers, we can create the actual LDIF file # Create the user group dn: cn=networkusers,ou=groups,dc=saruman,dc=biz objectClass: posixGroup gidNumber: 10001 cn: networkusers description: Internal network users # Create a new user: dn: uid=sixpacjo,ou=people,dc=saruman,dc=biz objectClass: top objectClass: posixAccount objectClass: shadowAccount objectClass: inetOrgPerson cn: Joe Sixpack description: Your Average Network User givenName: Joe sn: Sixpack mail: joe.sixpack@saruman.biz mail: j.sixpack@saruman.biz # The Unix login-name for the user: uid: sixpacjo # The group and user IDs: gidNumber: 10001 uidNumber: 10001 # The Unix account data: homeDirectory: /home/sixpacjo loginShell: /bin/bash # The encrypted password for the user: userPassword: {SSHA}OcAQWgcTCzpu6v8n4yUUthiKPM6rlODq For a line-by-line explanation of this LDIF file, go [[LDIF syntax explanation | here]]; we also explain the [[LDIF syntax explanation | password hashing]] there. If you need to create more users, you can put them all in the same LDIF file, as long as you leave empty lines between each user. To put the information from this file into our LDAP server, we have two options: # Shut down the OpenLDAP server, put the information straight into the database using ''slapadd'', and then starting the server again. This would be the recommended way to enter information if we hadn't just typed it in ourselves, but previously made a backup of some sorts from the LDAP server using ''slapcat''. # Keep the OpenLDAP running, and use the ''ldapadd'' utility to read the data into the live LDAP database. This makes use of the credentials of some user that has the right to write in the database, at least at the places where your LDIF file wants to store information (in the above example: in the ''groups'' and ''people'' OU's). The ''ldapadd'' method works like this: after creating the file, e.g. ''sixpack.ldif'' in a certain place, e.g. our home directory, we run the following command: ldapadd -v -x -D cn=admin.dc=saruman.dc=biz -W -f ~/sixpack.ldif The meaning of the options is as follows: * '''-v''' the everamusing "verbose" for extra diagnostic messages. * '''-x''' use "simple bind" and not a TLS-encrypted connection. * '''-D cn=admin.dc=saruman.dc=biz''' is the Distinguished Name with which to bind to the LDAP server. * '''-W''' prompt for the password of the -D credential. Alternatively, use ''-w <password>'', but ofcourse then the password winds up in your Bash history file et cetera. * '''-f ~/sixpack.ldif''' read the LDIF information from this particular file, instead of the StdIn The output of such an action could look like this: <pre> ldapadd -v -x -D cn=admin,dc=saruman,dc=biz -W -f sixpack.ldif ldap_initialize( <DEFAULT> ) Enter LDAP Password: add objectClass: posixGroup add gidNumber: 10001 add cn: networkusers add description: Internal network users adding new entry "cn=networkusers,ou=groups,dc=saruman,dc=biz" modify complete add objectClass: posixAccount shadowAccount inetOrgPerson add cn: Joe Sixpack add description: Your Average Network User .... (et cetera et cetera) .... adding new entry "uid=sixpacjo,ou=people,dc=saruman,dc=biz" modify complete </pre> There, wasn't that fun? We now have Joe Sixpack in our LDAP server with all data necessary for a valid account - even though he as yet can't do anything yet on our server! To === Adding a user with LAM=== To add a user with LAM is not exactly challenging. Log into LAM with an admin account; in the top menu, click Users; at the left bottom, you'll find a button "New user". Click it. You'll find yourself in a browser screen with four "tabs": Personal, Unix, Shadow, and Samba3. Incidentally, if the system complains about "No Samba3 domains found in LDAP": ignore that for now. In the first tab Personal, we find a (large) number of attributes that we can fill; the mandatory attributes are marked with an asterisk. At a minimum, fill in those required attributes. Then switch to the next tab, Unix. Here we fill in the required attributes, taking care to select a unique UID number, selecting the right primary group (that you've made beforehand, naturally, e.g. with the LDIF file mentioned previously), and setting a password. We don't need to add anything to the 3rd and 4th tab, so we can finish by clicking save at the left top hand. LAM should respond with "LDAP operation succesfull". == The next phase: shell access == For the next phase, we want to start using LDAP for two separate goals: authentication and authentication for Linux shell access, and authentication for SSH access. For these two steps, [[Accessing a shell with LDAP authentication | go here]]. d4633753bcede2dd2d318441628532b9d47269aa 2011 2007 2008-11-13T19:46:48Z Saruman! 2 added second link to shell access page wikitext text/x-wiki == Creating your first Organizational Units == On the offchance that you haven't installed LAM, and thus haven't created the organizational units ''people'', ''groups'', ''hosts'' and ''domains'', here's how to create them manually. Create a file containing the following information: <pre> dn: ou=people,dc=saruman,dc=biz ou: people objectClass: top objectClass: organizationalUnit dn: ou=groups,dc=saruman,dc=biz ou: groups objectClass: top objectClass: organizationalUnit dn: ou=hosts,dc=saruman,dc=biz ou: hosts objectClass: top objectClass: organizationalUnit dn: ou=domains,dc=saruman,dc=biz ou: domains objectClass: top objectClass: organizationalUnit </pre> Let's suppose this file is named ''orgunits.ldif''. Now from the directory that contains this file, feed the information into your OpenLDAP using the following commands: sudo invoke-rc.d slapd stop sudo slapadd -c -v -l orgunits.ldif sudo invoke-rc.d slapd start This effectively stops the server, writes the information directly into the database, and then starts the server again. Another way to do (almost) the ''same'' thing, would be to add the information with the ''ldapadd'' command: ldapadd -c -x -D cn=admin,dc=saruman,dc=biz -W -f orgunits.ldif This binds to the OpenLDAP server (which must be running) using the admin account. This in turn causes the command to request the admin password, and then feed the contents from the ''orgunits.ldif'' file into the database. However, adding data to a live database precludes you from adding system controlled attributes, as structuralObjectClass is. So for live addition, remove those four particular lines from the ''orgunits.ldif'' file. Explanation of this difference: ''slapadd'' is meant as a restore tool, so it must (and can) create system controlled attributes. ''ldapadd'' is a modification tool, so it shouldn't need to (and can't) create these attributes. ==Migrating User, Password and Group entries to an LDAP server== It's nice to have an LDAP, but it's ''much'' nicer if it is filled with information. We'll try to enter all existing users and groups from the host server into LDAP, using [[Migrating existing Unix users to OpenLDAP | the available migration tools]]. ==Creating new users == If we need new users (e.g. when the server you're setting up is spankin' new) then we can create them in several ways. Let's discuss two of them: === Adding a user with an LDIF file=== To add a user with the LDAP command line utilities, we first need to create an LDIF file. This file is a simple text file, created with a text editor like ''[[vim | vi]]''. The file could look something like the text below. In that file, we create a posix group "networkusers", and a user "sixpacjo" that's a member of this posix group. However, first we need to [http://www.pctools.com/guides/password/ generate a password] for our user, e.g. "raQaMad3", then hash it: slappasswd -u -h {SSHA} -s raQaMad3 {SSHA}OcAQWgcTCzpu6v8n4yUUthiKPM6rlODq Now with this hashed password, and all other information on user sixpacjo and group networkusers, we can create the actual LDIF file # Create the user group dn: cn=networkusers,ou=groups,dc=saruman,dc=biz objectClass: posixGroup gidNumber: 10001 cn: networkusers description: Internal network users # Create a new user: dn: uid=sixpacjo,ou=people,dc=saruman,dc=biz objectClass: top objectClass: posixAccount objectClass: shadowAccount objectClass: inetOrgPerson cn: Joe Sixpack description: Your Average Network User givenName: Joe sn: Sixpack mail: joe.sixpack@saruman.biz mail: j.sixpack@saruman.biz # The Unix login-name for the user: uid: sixpacjo # The group and user IDs: gidNumber: 10001 uidNumber: 10001 # The Unix account data: homeDirectory: /home/sixpacjo loginShell: /bin/bash # The encrypted password for the user: userPassword: {SSHA}OcAQWgcTCzpu6v8n4yUUthiKPM6rlODq For a line-by-line explanation of this LDIF file, go [[LDIF syntax explanation | here]]; we also explain the [[LDIF syntax explanation | password hashing]] there. If you need to create more users, you can put them all in the same LDIF file, as long as you leave empty lines between each user. To put the information from this file into our LDAP server, we have two options: # Shut down the OpenLDAP server, put the information straight into the database using ''slapadd'', and then starting the server again. This would be the recommended way to enter information if we hadn't just typed it in ourselves, but previously made a backup of some sorts from the LDAP server using ''slapcat''. # Keep the OpenLDAP running, and use the ''ldapadd'' utility to read the data into the live LDAP database. This makes use of the credentials of some user that has the right to write in the database, at least at the places where your LDIF file wants to store information (in the above example: in the ''groups'' and ''people'' OU's). The ''ldapadd'' method works like this: after creating the file, e.g. ''sixpack.ldif'' in a certain place, e.g. our home directory, we run the following command: ldapadd -v -x -D cn=admin.dc=saruman.dc=biz -W -f ~/sixpack.ldif The meaning of the options is as follows: * '''-v''' the everamusing "verbose" for extra diagnostic messages. * '''-x''' use "simple bind" and not a TLS-encrypted connection. * '''-D cn=admin.dc=saruman.dc=biz''' is the Distinguished Name with which to bind to the LDAP server. * '''-W''' prompt for the password of the -D credential. Alternatively, use ''-w <password>'', but ofcourse then the password winds up in your Bash history file et cetera. * '''-f ~/sixpack.ldif''' read the LDIF information from this particular file, instead of the StdIn The output of such an action could look like this: <pre> ldapadd -v -x -D cn=admin,dc=saruman,dc=biz -W -f sixpack.ldif ldap_initialize( <DEFAULT> ) Enter LDAP Password: add objectClass: posixGroup add gidNumber: 10001 add cn: networkusers add description: Internal network users adding new entry "cn=networkusers,ou=groups,dc=saruman,dc=biz" modify complete add objectClass: posixAccount shadowAccount inetOrgPerson add cn: Joe Sixpack add description: Your Average Network User .... (et cetera et cetera) .... adding new entry "uid=sixpacjo,ou=people,dc=saruman,dc=biz" modify complete </pre> There, wasn't that fun? We now have Joe Sixpack in our LDAP server with all data necessary for a valid account - even though he as yet can't do anything yet on our server! To change that, we'll have to instruct our server to give user ''sixpacjo'' [[Accessing a shell with LDAP authentication | shell access]]. === Adding a user with LAM=== To add a user with LAM is not exactly challenging. Log into LAM with an admin account; in the top menu, click Users; at the left bottom, you'll find a button "New user". Click it. You'll find yourself in a browser screen with four "tabs": Personal, Unix, Shadow, and Samba3. Incidentally, if the system complains about "No Samba3 domains found in LDAP": ignore that for now. In the first tab Personal, we find a (large) number of attributes that we can fill; the mandatory attributes are marked with an asterisk. At a minimum, fill in those required attributes. Then switch to the next tab, Unix. Here we fill in the required attributes, taking care to select a unique UID number, selecting the right primary group (that you've made beforehand, naturally, e.g. with the LDIF file mentioned previously), and setting a password. We don't need to add anything to the 3rd and 4th tab, so we can finish by clicking save at the left top hand. LAM should respond with "LDAP operation succesfull". == The next phase: shell access == For the next phase, we want to start using LDAP for two separate goals: authentication and authentication for Linux shell access, and authentication for SSH access. For these two steps, [[Accessing a shell with LDAP authentication | go here]]. f4ad4a2e8583d3a031653a565f6c4af2c48c1627 0 1474 2012 1708 2008-11-13T21:23:44Z Saruman! 2 split libnss-ldapd from libpam-ldap wikitext text/x-wiki == Shell access with LDAP authentication and authorization == === Preparatory steps === Before we configure the use of LDAP, we confirm that the Linux system knows the ''root'' account, but does not know any ''sixpajo'' account. We do this with the command ''id'': hostname:~# id root uid=0(root) gid=0(root) groups=0(root) hostname:~# id sixpajo id: sixpajo: No such user Yes, exactly what we'd expect. But once we've enabled LDAP, we expect the second command to return a valid user. To be able to use the LDAP database for authentication, we must have the right software. So as usual, we install it using ''apt-get'' or ''aptitude''. The software we need consists of two packages: * ''libpam-ldap'', the PAM module that allows LDAP interfaces * ''libnss-ldapd'', the NSS module that can use LDAP as a naming service Note: some HOWTO's speak of ''libnss-ldap'' and the separate package ''nscd''; however since there were some problems switching libraries from SSL to TLS, the ''libnss-ldap'' project forked ''libnss-ldapd''. And when you install ''libnss-ldapd'', you automatically get ''nslcd'' That extra "d" thus matters a lot :-) However, since all these files depend on a single configuration file (either ''nss-ldapd.conf'' or ''nss-ldap.conf'') there is little difference in the implementation of either. We suggest you start by installing ''libpam-ldap''. Installing it will make your Debian package manager (debconf) ask you a couple of questions. * the LDAP server Uniform Resource Identifier; it'll suggest ''ldapi:///'', but you should submit ''ldap://127.0.0.1/'' or whatever the IP address on your LDAP server's internal NIC is. Note: use "ldap:" and not "ldapi:". The difference is "ldapi:" signals LDAP over a Unix socket (and, to be complete, "ldaps:" signals LDAP over SSL). * the DN of the LDAP search base: in our example this was "dc=saruman,dc=biz". * the verions of the LDAP protocol to use - only when you have pressing reasons to use version 2 should you do so; version 3 should always be your LDAP protocol version. * whether the local root user gets to be database admin: usually you'll answer "yes"; this makes dpkg-reconfigure store the LDAP admin user password in a file ''/etc/ldap.secret''; this file is secured so that only user root can read it. However, with certain custom setups this might not be the best idea. The example dpkg-reconfigure itself offers is that of an NFS mounted ''/etc'' directory: NFS hasn't got proper security, so the database admin password could be up for grabs. In those cases, you shouldn't do this. We don't cover these custom cases though; we just answer "yes". * whether the LDAP database requires login; in other words, wheter anonymous binds are disallowed. We allow anonymous binds, so we can answer the default of "no". * Next, you'll be asked the LDAP administrator account and password, e.g. "cn=admin,dc=saruman,dc=biz" and "wEt3udes". The former gets stored in the configuration file, the latter is stored in unencrypted form in a separate file, that is readable only for user root. After these questions, you can see the configuration file ''/etc/pam_ldap.conf'' having been created, and (if you've chosen local root to get database admin powers) ''pam_ldap.secret''. You can always use ''dpkg-reconfigure'' to re-answer all these questions. The only notable thing is that you'll then get a bonus question: * what "local crypt" to use when passwords must be changed; the default is "crypt", the standard Linux password encryption method, but other options are a.o. "exop" (LDAP extended operation) and "md5". Next up, we'll install * a list of services for which to enable LDAP lookups; select services ''group'', ''passwd'' and ''shadow'' - which should be the default. When installing ''libnss-ldapd'', Debian asks the following questions: === Configuring PAM for LDAP authentication === First, let's check if the Debian installation has used the right information. Check ''/etc/pam_ldap.conf'' to contain the correct information on your LDAP server. If you run the correct cat-and-grep, you should see something like this: hostname:~# cat /etc/pam_ldap.conf | grep -v ^# | grep -v ^$ base dc=saruman,dc=biz uri ldap://127.0.0.1/ ldap_version 3 pam_password crypt Next, check if ''libnss-ldapd.conf'' has the right information as well: hostname:~# cat nss-ldapd.conf | grep -v ^# | grep -v ^$ uid nslcd gid nslcd uri ldap:///192.168.67.10 base dc=saruman,dc=biz All correct, and with [http://en.wikipedia.org/wiki/Advanced_Packaging_Tool APT] we wouldn't expect otherwise. Now we'll configure PAM to use LDAP. This means editing PAM configuration files in ''/etc/pam.d''. '''BE CAREFUL!''' Since PAM is quite fragile, it breaks easily when you make small mistakes in these files! In ''/etc/pam.d/common-account'', change ''account-required pam_unix.so'' into account sufficient pam_unix.so account required pam_ldap.so In ''/etc/pam.d/common-auth'', change ''auth required pam_unix.so nullok_secure'' into auth [success=1 default=ignore] pam_unix.so nullok_secure auth required pam_ldap.so use_first_pass auth required pam_permit.so In ''/etc/pam.d/common-session'', add a line after ''session required pam_unix.so'' so you get session required pam_unix.so session required pam_mkhomedir.so skel=/etc/skel/ umask=0022 === Configuring NSS to consult the LDAP server === To change NSS, we only have to change ''/etc/nsswitch.conf''. There are multiple entries in there, but we're only interested in the two lines that start with ''passwd:'', ''group:'' and ''shadow''. Probably they look like this: passwd: compat group: compat shadow: compat This means that for password, group and shadow information, the system will look into the normal files, and if no suitable answer is found there, in Sun's ancient NIS database. We don't employ NIS, but we do want to employ LDAP, so we change these three lines to: passwd: files ldap group: files ldap shadow: files ldap === Testing the new configuration === The ''nslcd'' program is very nice for caching and generally speeding up all things LDAP, but when testing we don't want it to interfere. Stop the daemon with ''sudo invoke-rc.d nslcd stop''. If we now test for the presence of root and Joe Sixpack: id root uid=0(root) gid=0(root) groups=0(root) id sixpacjo uid=10001(sixpacjo) gid=10001(networkusers) groups=10001(networkusers) Success! Root is still read from the Linux files (no object with a UID of "root" exists in your LDAP, at least not if you've followed this Wiki), and Joe Sixpack's account is found from the LDAP server. Note that if you restart your server, ''nslcd'' will be running automatically again. If you don't want to restart your server any time soon, you can manually start the ''nslcd'' daemon with ''sudo invoke-rc.d nslcd start''. == LDAP authentication for SSH == By default, your Debian 5.0 "Lenny" setup is all ready to receive LDAP users. This is because by default the line usePAM yes is present; this makes SSH use the PAM settings in ''/etc/pam.d/sshd'', which point to the standard PAM login methods "common-auth", "common-account" and "common-session". Thus, all settings you've made for shell access via the console automatically apply for SSH as well. However, if you've configured your SSH server [[OpenSSH_server | as we've outlined here]], then to actually allow certain users, you need two distinct steps, that you've either performed already, or will need to do now: # add all LDAP users that you want to allow SSH acces to one or more LDAP groups, e.g. "ldapwheel"; # add those group or groups to your SSH configuration in the ''AllowGroup'' line, e.g. ''AllowGroup wheel ldapwheel''. Ofcourse, if you've edited ''sshd_config'', you'll need to restart the SSH server. 0a40f6fa10cea0ed18d73f57ca290d74e12f2fbd 0 1414 2016 1490 2008-11-17T12:23:01Z 80.101.181.4 0 wikitext text/x-wiki ==Essential system software== The following packages we deem quite essential for any Debian (home) server: [[Big Bag'o'utilities]] (not "a" package, but a collection of essential tools like ''less'' and ''sudo'')<br> [[OpenSSH server]]<br> [[vim]] which stands for VI iMproved<br> [[Crontab]]<br> [[iproute2]]<br> [[Compilation software]]<br> [[IPtables and firewall]]<br> [[IPsec software]]<br> [[kerneloops]] ef4cfc7a2d878ee04124539877a5bc52b4d534cb 0 1494 2017 2008-11-18T16:49:43Z Saruman! 2 Page started wikitext text/x-wiki = The Samba Section= == Preparations == First off, get yourself [http://oreilly.com/catalog/9780596007690/index.html this wonderful book] - and READ IT. Next, make sure our user backend of choice, OpenLDAP, is properly installed and can be used to authenticate users. If you haven't yet installed OpenLDAP, go to [[OpenLDAP | the relevant section]] of this wiki, and get going. Make sure 83812d1e6c9d7f1e1d55488bc47bdafcdc0e7a8b 2018 2017 2008-11-21T13:41:53Z Saruman! 2 put in schema change wikitext text/x-wiki == The Samba Section== == Preparations == First off, get yourself [http://oreilly.com/catalog/9780596007690/index.html this wonderful book] - and READ IT. Next, make sure our user backend of choice, OpenLDAP, is properly installed and can be used to authenticate users. If you haven't yet installed OpenLDAP, go to [[OpenLDAP | the relevant section]] of this wiki, and get going. Make sure your OpenLDAP is running well. === Software installation === This is easy: using ''aptitude'', install the packages ''samba'', ''samba-tools'' and ''samba-doc'' - note that we NEED ''samba-doc'', as this package contains a configuration file that we need. As usual, Debian is asking us for the configuration details. For SaMBa 3.2, there are only two simple questions: * What do you want to be your Windows workgroup name? (we provide the name "AMBER") * Do you want to modify ''smb.conf'' to use WINS setting from DHCP? (we provide "yes") === OpenLDAP adaptation === In order for our OpenLDAP server to recognise the SaMBa-specific attributes that we're going to use, we need to add the "samba" schema to the OpenLDAP server. After installation of ''samba-doc'', we can find this schema in ''/usr/share/doc/samba-doc/examples/LDAP'', where it sits gzipped between some other schema files; as the README explains, what we need is ''samba.schema.gz'', so we unzip it and copy it to our OpenLDAP schema directory cd /usr/share/doc/samba-doc/examples/LDAP gunzip samba.schema.gz cp samba.schema /etc/ldap/schema Next up, we include this schema into our LDAP configuration, by adding the following line to ''/etc/ldap/slapd.conf'': include /etc/ldap/schema/samba.schema After this addition, we'll need to restart our LDAP server: /etc/init.d/slapd restart 193caf1bb6c5ba048a7ca73f23701e21bb4b5254 2019 2018 2008-11-21T15:59:41Z Saruman! 2 WINS added wikitext text/x-wiki == The Samba Section== == Preparations == First off, get yourself [http://oreilly.com/catalog/9780596007690/index.html this wonderful book] - and READ IT. Next, make sure our user backend of choice, OpenLDAP, is properly installed and can be used to authenticate users. If you haven't yet installed OpenLDAP, go to [[OpenLDAP | the relevant section]] of this wiki, and get going. Make sure your OpenLDAP is running well. === Software installation === This is easy: using ''aptitude'', install the packages ''samba'', ''samba-tools'' and ''samba-doc'' - note that we NEED ''samba-doc'', as this package contains a configuration file that we need. As usual, Debian is asking us for the configuration details. For SaMBa 3.2, there are only two simple questions: * What do you want to be your Windows workgroup name? (we provide the name "AMBER") * Do you want to modify ''smb.conf'' to use WINS setting from DHCP? (we provide "no") Now we have our SaMBa configuration file as ''/etc/samba/smb.conf'', but we're going to follow two time-honoured tradions: we're going to save the original configuration file for future reference, and we're going to rename our configuration file to ''smb.conf.master'', while providing SaMBa with a comment-stripped version of it: cd /etc/samba cp smb.conf smb.conf.sample mv smb.conf smb.conf.master testparm smb.conf.master testparm -s smb.conf.master > smb.conf Now remember: when we want to change our SaMBa configuration, we edit ''smb.conf.master''. Once we're ready with that, we ALWAYS need to run those last two lines; the first of those will check our updated configuration, to see if we haven't made some silly typo that renders the configuration wholly or partially crippled, and the second one creates a comment-stripped version of it that SaMBa will actually be using. === WINS configuration === To enable WINS, we add the following lines to ''smb.conf.master'': ## Browsing/Identification ### workgroup = AMBER netbios name = DWORKIN # Windows Internet Name Serving Support Section: # WINS Support - Tells the NMBD component of Samba to enable its WINS Server wins support = yes os level = 33 domain master = yes local master = yes preferred master = yes name resolve order = wins lmhosts hosts bcast dns proxy = yes Now this does a whole lot of things with the SaMBa ''nmbd'' daemon - at least when you remember to save the master config file, test it with ''testparm'' and write the actual ''smb.conf'' as desribed previously, AND then restart your ''nmbd'' daemon: /etc/init.d/samba restart OK so what do the configuration lines mean? * ''workgroup = AMBER'' - this line makes the SaMBa server a member of workgroup AMBER. * ''netbios name = DWORKIN'' - here we define the server NetBIOS name to be "dworkin". * ''wins support = yes'' - this line actually turns on the WINS support, so it instructs the ''nmbd'' daemon to start acting as a WINS server. * ''os level = 33'' - this gives our WINS server a "rank" of 33, meaning that it will be sure to become the WINS master browser, even if there are Windows servers on the network tat act as domain controllers. * ''domain master = yes'' - this will tell our server that it will not be just any master browser, but a '''domain''' master browser, so that our server will be the master browser on each and every subnet that it is connected to. * ''local master = yes'' - this setting is vital to being a domain master browser, as it ensures that our WINS server is also the local master browser. * ''preferred master = yes'' - adding this line makes the ''nmbd'' daemon initiate a browser election as soon as it starts up, so that it essentially gets the master browser role as fast as possible. * ''name resolve order = wins lmhosts hosts bcast'' - this ensures that for a WINS request, the ''nmbd'' daemon not only checks its WINS database, but also the local ''lmhosts'' file (if it exists), the Linux ''/etc/hosts'' file, and finally, to revert to a broadcast to see if it can locate the requested name by shouting out for it. * ''dns proxy = yes'' - this makes ''nmbd'' to check a requested name with the DNS server, if it cannot be found in the WINS database itself. After restarting, we can see if our Linux server is now a WINS master browser by inspecting the SaMBa log file, by default ''/var/log/samba/nmbd.log''. It should show something like [2008/11/21 16:18:03, 0] nmbd/nmbd.c:main(849) nmbd version 3.2.4 started. Copyright Andrew Tridgell and the Samba Team 1992-2008 [2008/11/21 16:18:03, 0] nmbd/asyncdns.c:start_async_dns(155) started asyncdns process 25707 [2008/11/21 16:18:03, 0] nmbd/nmbd_become_dmb.c:become_domain_master_browser_wins(336) become_domain_master_browser_wins: Attempting to become domain master browser on workgroup AMBER, subnet UNICAST_SUBNET. [2008/11/21 16:18:03, 0] nmbd/nmbd_become_dmb.c:become_domain_master_browser_wins(350) become_domain_master_browser_wins: querying WINS server from IP 192.168.67.10 for domain master browser name AMBER<1b> on workgroup AMBER [2008/11/21 16:18:03, 0] nmbd/nmbd_become_dmb.c:become_domain_master_stage2(110) ***** Samba server DWORKIN is now a domain master browser for workgroup AMBER on subnet UNICAST_SUBNET ***** [2008/11/21 16:18:03, 0] nmbd/nmbd_become_dmb.c:become_domain_master_browser_bcast(291) become_domain_master_browser_bcast: Attempting to become domain master browser on workgroup AMBER on subnet 192.168.67.10 [2008/11/21 16:18:03, 0] nmbd/nmbd_become_dmb.c:become_domain_master_browser_bcast(304) become_domain_master_browser_bcast: querying subnet 192.168.67.9 for domain master browser on workgroup AMBER [2008/11/21 16:18:11, 0] nmbd/nmbd_become_dmb.c:become_domain_master_stage2(110) ***** Samba server DWORKIN is now a domain master browser for workgroup AMBER on subnet 192.168.67.10 ***** [2008/11/21 16:18:26, 0] nmbd/nmbd_become_lmb.c:become_local_master_stage2(395) ***** Samba name server DWORKIN is now a local master browser for workgroup AMBER on subnet 192.168.67.10 ***** Furthermore, we can test on the server itself if a WINS lookup succeeds: dworkin:# nmblookup -M amber querying amber on 127.255.255.255 192.168.67.10 amber<1d> Finally, we tell our DHCP server to provide clients with the IP address of our WINS server. We do this by adding the following line to ''/etc/dhcp3-server/dhcpd.conf'': option netbios-name-servers 192.168.67.10 This line can either be added to the global section, or within the ''subnet'' declaration for each individual subnet that you want to inform of this WINS server. === OpenLDAP adaptation === In order for our OpenLDAP server to recognise the SaMBa-specific attributes that we're going to use, we need to add the "samba" schema to the OpenLDAP server. After installation of ''samba-doc'', we can find this schema in ''/usr/share/doc/samba-doc/examples/LDAP'', where it sits gzipped between some other schema files; as the README explains, what we need is ''samba.schema.gz'', so we unzip it and copy it to our OpenLDAP schema directory cd /usr/share/doc/samba-doc/examples/LDAP gunzip samba.schema.gz cp samba.schema /etc/ldap/schema Next up, we include this schema into our LDAP configuration, by adding the following line to ''/etc/ldap/slapd.conf'': include /etc/ldap/schema/samba.schema After this addition, we'll need to restart our LDAP server: /etc/init.d/slapd restart Check to see if the Samba objects are now usable in your LDAP server, e.g. by opening your LDAP Account Manager, and go to tools > schema browser; you should have objects like "sambaConfig" and "sambaDomain". 3032fbd45080d1d2675e793ff3ed1ab6b53030f0 2020 2019 2008-11-21T18:44:34Z Saruman! 2 /* OpenLDAP adaptation */ added extra indices wikitext text/x-wiki == The Samba Section== == Preparations == First off, get yourself [http://oreilly.com/catalog/9780596007690/index.html this wonderful book] - and READ IT. Next, make sure our user backend of choice, OpenLDAP, is properly installed and can be used to authenticate users. If you haven't yet installed OpenLDAP, go to [[OpenLDAP | the relevant section]] of this wiki, and get going. Make sure your OpenLDAP is running well. === Software installation === This is easy: using ''aptitude'', install the packages ''samba'', ''samba-tools'' and ''samba-doc'' - note that we NEED ''samba-doc'', as this package contains a configuration file that we need. As usual, Debian is asking us for the configuration details. For SaMBa 3.2, there are only two simple questions: * What do you want to be your Windows workgroup name? (we provide the name "AMBER") * Do you want to modify ''smb.conf'' to use WINS setting from DHCP? (we provide "no") Now we have our SaMBa configuration file as ''/etc/samba/smb.conf'', but we're going to follow two time-honoured tradions: we're going to save the original configuration file for future reference, and we're going to rename our configuration file to ''smb.conf.master'', while providing SaMBa with a comment-stripped version of it: cd /etc/samba cp smb.conf smb.conf.sample mv smb.conf smb.conf.master testparm smb.conf.master testparm -s smb.conf.master > smb.conf Now remember: when we want to change our SaMBa configuration, we edit ''smb.conf.master''. Once we're ready with that, we ALWAYS need to run those last two lines; the first of those will check our updated configuration, to see if we haven't made some silly typo that renders the configuration wholly or partially crippled, and the second one creates a comment-stripped version of it that SaMBa will actually be using. === WINS configuration === To enable WINS, we add the following lines to ''smb.conf.master'': ## Browsing/Identification ### workgroup = AMBER netbios name = DWORKIN # Windows Internet Name Serving Support Section: # WINS Support - Tells the NMBD component of Samba to enable its WINS Server wins support = yes os level = 33 domain master = yes local master = yes preferred master = yes name resolve order = wins lmhosts hosts bcast dns proxy = yes Now this does a whole lot of things with the SaMBa ''nmbd'' daemon - at least when you remember to save the master config file, test it with ''testparm'' and write the actual ''smb.conf'' as desribed previously, AND then restart your ''nmbd'' daemon: /etc/init.d/samba restart OK so what do the configuration lines mean? * ''workgroup = AMBER'' - this line makes the SaMBa server a member of workgroup AMBER. * ''netbios name = DWORKIN'' - here we define the server NetBIOS name to be "dworkin". * ''wins support = yes'' - this line actually turns on the WINS support, so it instructs the ''nmbd'' daemon to start acting as a WINS server. * ''os level = 33'' - this gives our WINS server a "rank" of 33, meaning that it will be sure to become the WINS master browser, even if there are Windows servers on the network tat act as domain controllers. * ''domain master = yes'' - this will tell our server that it will not be just any master browser, but a '''domain''' master browser, so that our server will be the master browser on each and every subnet that it is connected to. * ''local master = yes'' - this setting is vital to being a domain master browser, as it ensures that our WINS server is also the local master browser. * ''preferred master = yes'' - adding this line makes the ''nmbd'' daemon initiate a browser election as soon as it starts up, so that it essentially gets the master browser role as fast as possible. * ''name resolve order = wins lmhosts hosts bcast'' - this ensures that for a WINS request, the ''nmbd'' daemon not only checks its WINS database, but also the local ''lmhosts'' file (if it exists), the Linux ''/etc/hosts'' file, and finally, to revert to a broadcast to see if it can locate the requested name by shouting out for it. * ''dns proxy = yes'' - this makes ''nmbd'' to check a requested name with the DNS server, if it cannot be found in the WINS database itself. After restarting, we can see if our Linux server is now a WINS master browser by inspecting the SaMBa log file, by default ''/var/log/samba/nmbd.log''. It should show something like [2008/11/21 16:18:03, 0] nmbd/nmbd.c:main(849) nmbd version 3.2.4 started. Copyright Andrew Tridgell and the Samba Team 1992-2008 [2008/11/21 16:18:03, 0] nmbd/asyncdns.c:start_async_dns(155) started asyncdns process 25707 [2008/11/21 16:18:03, 0] nmbd/nmbd_become_dmb.c:become_domain_master_browser_wins(336) become_domain_master_browser_wins: Attempting to become domain master browser on workgroup AMBER, subnet UNICAST_SUBNET. [2008/11/21 16:18:03, 0] nmbd/nmbd_become_dmb.c:become_domain_master_browser_wins(350) become_domain_master_browser_wins: querying WINS server from IP 192.168.67.10 for domain master browser name AMBER<1b> on workgroup AMBER [2008/11/21 16:18:03, 0] nmbd/nmbd_become_dmb.c:become_domain_master_stage2(110) ***** Samba server DWORKIN is now a domain master browser for workgroup AMBER on subnet UNICAST_SUBNET ***** [2008/11/21 16:18:03, 0] nmbd/nmbd_become_dmb.c:become_domain_master_browser_bcast(291) become_domain_master_browser_bcast: Attempting to become domain master browser on workgroup AMBER on subnet 192.168.67.10 [2008/11/21 16:18:03, 0] nmbd/nmbd_become_dmb.c:become_domain_master_browser_bcast(304) become_domain_master_browser_bcast: querying subnet 192.168.67.9 for domain master browser on workgroup AMBER [2008/11/21 16:18:11, 0] nmbd/nmbd_become_dmb.c:become_domain_master_stage2(110) ***** Samba server DWORKIN is now a domain master browser for workgroup AMBER on subnet 192.168.67.10 ***** [2008/11/21 16:18:26, 0] nmbd/nmbd_become_lmb.c:become_local_master_stage2(395) ***** Samba name server DWORKIN is now a local master browser for workgroup AMBER on subnet 192.168.67.10 ***** Furthermore, we can test on the server itself if a WINS lookup succeeds: dworkin:# nmblookup -M amber querying amber on 127.255.255.255 192.168.67.10 amber<1d> Finally, we tell our DHCP server to provide clients with the IP address of our WINS server. We do this by adding the following line to ''/etc/dhcp3-server/dhcpd.conf'': option netbios-name-servers 192.168.67.10 This line can either be added to the global section, or within the ''subnet'' declaration for each individual subnet that you want to inform of this WINS server. === OpenLDAP adaptation === In order for our OpenLDAP server to recognise the SaMBa-specific attributes that we're going to use, we need to add the "samba" schema to the OpenLDAP server. After installation of ''samba-doc'', we can find this schema in ''/usr/share/doc/samba-doc/examples/LDAP'', where it sits gzipped between some other schema files; as the README explains, what we need is ''samba.schema.gz'', so we unzip it and copy it to our OpenLDAP schema directory cd /usr/share/doc/samba-doc/examples/LDAP gunzip samba.schema.gz cp samba.schema /etc/ldap/schema Next up, we include this schema into our LDAP configuration, by adding the following line to ''/etc/ldap/slapd.conf'': include /etc/ldap/schema/samba.schema Not only do we need schema updates, we could also do with some more indices. Thus, we change the relevant section of ''/etc/ldap/slapd.conf'' to read: # Indexing options for database #1 index objectClass,uidNumber,gidNumber eq index cn,sn,uid,displayName pres,sub,eq index memberUid,mail,givenname eq,subinitial index sambaSID,sambaPrimaryGroupSID,sambaDomainName eq Ofcourse, it's not just enough to add these parameters, we also need to generate the indices, and restart our LDAP server: sudo invoke-rc.d slapd stop sudo -u openldap slapindex sudo invoke-rc.d slapd start Check to see if the Samba objects are now usable in your LDAP server, e.g. by opening your LDAP Account Manager, and go to tools > schema browser; you should have objects like "sambaConfig" and "sambaDomain". e8f02705e046c69828e9c7ca3634fa21e668df8a 2021 2020 2008-11-21T22:11:49Z Saruman! 2 Started LDAP authentication wikitext text/x-wiki == The Samba Section== == Preparations == First off, get yourself [http://oreilly.com/catalog/9780596007690/index.html this wonderful book] - and READ IT. Next, make sure our user backend of choice, OpenLDAP, is properly installed and can be used to authenticate users. If you haven't yet installed OpenLDAP, go to [[OpenLDAP | the relevant section]] of this wiki, and get going. Make sure your OpenLDAP is running well. === Software installation === This is easy: using ''aptitude'', install the following packages: * ''samba'', the actual server. * ''samba-tools'', a set of utilities. * ''samba-doc'' - note that we NEED ''samba-doc'', as this package contains a configuration file that we need (the LDAP schema file). * ''smbclient'', that can make your Linux server work with a Windows or SaMBa server; we need this to test our own server. As usual, Debian is asking us for the configuration details. For SaMBa 3.2, there are only two simple questions: * What do you want to be your Windows workgroup name? (we provide the name "AMBER") * Do you want to modify ''smb.conf'' to use WINS setting from DHCP? (we provide "no") Now we have our SaMBa configuration file as ''/etc/samba/smb.conf'', but we're going to follow two time-honoured tradions: we're going to save the original configuration file for future reference, and we're going to rename our configuration file to ''smb.conf.master'', while providing SaMBa with a comment-stripped version of it: cd /etc/samba cp smb.conf smb.conf.sample mv smb.conf smb.conf.master testparm smb.conf.master testparm -s smb.conf.master > smb.conf Now remember: when we want to change our SaMBa configuration, we edit ''smb.conf.master''. Once we're ready with that, we ALWAYS need to run those last two lines; the first of those will check our updated configuration, to see if we haven't made some silly typo that renders the configuration wholly or partially crippled, and the second one creates a comment-stripped version of it that SaMBa will actually be using. === WINS configuration === To enable WINS, we add the following lines to ''smb.conf.master'': ## Browsing/Identification ### workgroup = AMBER netbios name = DWORKIN # Windows Internet Name Serving Support Section: # WINS Support - Tells the NMBD component of Samba to enable its WINS Server wins support = yes os level = 33 domain master = yes local master = yes preferred master = yes name resolve order = wins lmhosts hosts bcast dns proxy = yes Now this does a whole lot of things with the SaMBa ''nmbd'' daemon - at least when you remember to save the master config file, test it with ''testparm'' and write the actual ''smb.conf'' as desribed previously, AND then restart your ''nmbd'' daemon: /etc/init.d/samba restart OK so what do the configuration lines mean? * ''workgroup = AMBER'' - this line makes the SaMBa server a member of workgroup AMBER. * ''netbios name = DWORKIN'' - here we define the server NetBIOS name to be "dworkin". * ''wins support = yes'' - this line actually turns on the WINS support, so it instructs the ''nmbd'' daemon to start acting as a WINS server. * ''os level = 33'' - this gives our WINS server a "rank" of 33, meaning that it will be sure to become the WINS master browser, even if there are Windows servers on the network tat act as domain controllers. * ''domain master = yes'' - this will tell our server that it will not be just any master browser, but a '''domain''' master browser, so that our server will be the master browser on each and every subnet that it is connected to. * ''local master = yes'' - this setting is vital to being a domain master browser, as it ensures that our WINS server is also the local master browser. * ''preferred master = yes'' - adding this line makes the ''nmbd'' daemon initiate a browser election as soon as it starts up, so that it essentially gets the master browser role as fast as possible. * ''name resolve order = wins lmhosts hosts bcast'' - this ensures that for a WINS request, the ''nmbd'' daemon not only checks its WINS database, but also the local ''lmhosts'' file (if it exists), the Linux ''/etc/hosts'' file, and finally, to revert to a broadcast to see if it can locate the requested name by shouting out for it. * ''dns proxy = yes'' - this makes ''nmbd'' to check a requested name with the DNS server, if it cannot be found in the WINS database itself. After restarting, we can see if our Linux server is now a WINS master browser by inspecting the SaMBa log file, by default ''/var/log/samba/nmbd.log''. It should show something like [2008/11/21 16:18:03, 0] nmbd/nmbd.c:main(849) nmbd version 3.2.4 started. Copyright Andrew Tridgell and the Samba Team 1992-2008 [2008/11/21 16:18:03, 0] nmbd/asyncdns.c:start_async_dns(155) started asyncdns process 25707 [2008/11/21 16:18:03, 0] nmbd/nmbd_become_dmb.c:become_domain_master_browser_wins(336) become_domain_master_browser_wins: Attempting to become domain master browser on workgroup AMBER, subnet UNICAST_SUBNET. [2008/11/21 16:18:03, 0] nmbd/nmbd_become_dmb.c:become_domain_master_browser_wins(350) become_domain_master_browser_wins: querying WINS server from IP 192.168.67.10 for domain master browser name AMBER<1b> on workgroup AMBER [2008/11/21 16:18:03, 0] nmbd/nmbd_become_dmb.c:become_domain_master_stage2(110) ***** Samba server DWORKIN is now a domain master browser for workgroup AMBER on subnet UNICAST_SUBNET ***** [2008/11/21 16:18:03, 0] nmbd/nmbd_become_dmb.c:become_domain_master_browser_bcast(291) become_domain_master_browser_bcast: Attempting to become domain master browser on workgroup AMBER on subnet 192.168.67.10 [2008/11/21 16:18:03, 0] nmbd/nmbd_become_dmb.c:become_domain_master_browser_bcast(304) become_domain_master_browser_bcast: querying subnet 192.168.67.9 for domain master browser on workgroup AMBER [2008/11/21 16:18:11, 0] nmbd/nmbd_become_dmb.c:become_domain_master_stage2(110) ***** Samba server DWORKIN is now a domain master browser for workgroup AMBER on subnet 192.168.67.10 ***** [2008/11/21 16:18:26, 0] nmbd/nmbd_become_lmb.c:become_local_master_stage2(395) ***** Samba name server DWORKIN is now a local master browser for workgroup AMBER on subnet 192.168.67.10 ***** Furthermore, we can test on the server itself if a WINS lookup succeeds: dworkin:# nmblookup -M amber querying amber on 127.255.255.255 192.168.67.10 amber<1d> Finally, we tell our DHCP server to provide clients with the IP address of our WINS server. We do this by adding the following line to ''/etc/dhcp3-server/dhcpd.conf'': option netbios-name-servers 192.168.67.10 This line can either be added to the global section, or within the ''subnet'' declaration for each individual subnet that you want to inform of this WINS server. === OpenLDAP adaptation === In order for our OpenLDAP server to recognise the SaMBa-specific attributes that we're going to use, we need to add the "samba" schema to the OpenLDAP server. After installation of ''samba-doc'', we can find this schema in ''/usr/share/doc/samba-doc/examples/LDAP'', where it sits gzipped between some other schema files; as the README explains, what we need is ''samba.schema.gz'', so we unzip it and copy it to our OpenLDAP schema directory cd /usr/share/doc/samba-doc/examples/LDAP gunzip samba.schema.gz cp samba.schema /etc/ldap/schema Next up, we include this schema into our LDAP configuration, by adding the following line to ''/etc/ldap/slapd.conf'': include /etc/ldap/schema/samba.schema Not only do we need schema updates, we could also do with some more indices. Thus, we change the relevant section of ''/etc/ldap/slapd.conf'' to read: # Indexing options for database #1 index objectClass,uidNumber,gidNumber eq index cn,sn,uid,displayName pres,sub,eq index memberUid,mail,givenname eq,subinitial index sambaSID,sambaPrimaryGroupSID,sambaDomainName eq Ofcourse, it's not just enough to add these parameters, we also need to generate the indices, and restart our LDAP server: sudo invoke-rc.d slapd stop sudo -u openldap slapindex sudo invoke-rc.d slapd start Check to see if the Samba objects are now usable in your LDAP server, e.g. by opening your LDAP Account Manager, and go to tools > schema browser; you should have objects like "sambaConfig" and "sambaDomain". == Samba configuration for LDAP authentication== To get SaMBA to use OpenLDAP as a backend is actually quite straightforward. The main work is done in ''smb.conf.master'', where we add the following section: passdb backend = ldapsam:ldap://127.0.0.1 ldap suffix = dc=saruman,dc=biz ldap machine suffix = ou=hosts ldap user suffix = ou=people ldap group suffix = ou=groups ldap admin dn = cn=admin,dc=saruman,dc=biz ldap delete dn = no # allow user privileges enable privileges = yes 2e04b155eaea7f3947500cd21402d2b0e2f8b001 2022 2021 2008-11-21T22:32:40Z Saruman! 2 /* Samba configuration for LDAP authentication */ added order note wikitext text/x-wiki == The Samba Section== == Preparations == First off, get yourself [http://oreilly.com/catalog/9780596007690/index.html this wonderful book] - and READ IT. Next, make sure our user backend of choice, OpenLDAP, is properly installed and can be used to authenticate users. If you haven't yet installed OpenLDAP, go to [[OpenLDAP | the relevant section]] of this wiki, and get going. Make sure your OpenLDAP is running well. === Software installation === This is easy: using ''aptitude'', install the following packages: * ''samba'', the actual server. * ''samba-tools'', a set of utilities. * ''samba-doc'' - note that we NEED ''samba-doc'', as this package contains a configuration file that we need (the LDAP schema file). * ''smbclient'', that can make your Linux server work with a Windows or SaMBa server; we need this to test our own server. As usual, Debian is asking us for the configuration details. For SaMBa 3.2, there are only two simple questions: * What do you want to be your Windows workgroup name? (we provide the name "AMBER") * Do you want to modify ''smb.conf'' to use WINS setting from DHCP? (we provide "no") Now we have our SaMBa configuration file as ''/etc/samba/smb.conf'', but we're going to follow two time-honoured tradions: we're going to save the original configuration file for future reference, and we're going to rename our configuration file to ''smb.conf.master'', while providing SaMBa with a comment-stripped version of it: cd /etc/samba cp smb.conf smb.conf.sample mv smb.conf smb.conf.master testparm smb.conf.master testparm -s smb.conf.master > smb.conf Now remember: when we want to change our SaMBa configuration, we edit ''smb.conf.master''. Once we're ready with that, we ALWAYS need to run those last two lines; the first of those will check our updated configuration, to see if we haven't made some silly typo that renders the configuration wholly or partially crippled, and the second one creates a comment-stripped version of it that SaMBa will actually be using. === WINS configuration === To enable WINS, we add the following lines to ''smb.conf.master'': ## Browsing/Identification ### workgroup = AMBER netbios name = DWORKIN # Windows Internet Name Serving Support Section: # WINS Support - Tells the NMBD component of Samba to enable its WINS Server wins support = yes os level = 33 domain master = yes local master = yes preferred master = yes name resolve order = wins lmhosts hosts bcast dns proxy = yes Now this does a whole lot of things with the SaMBa ''nmbd'' daemon - at least when you remember to save the master config file, test it with ''testparm'' and write the actual ''smb.conf'' as desribed previously, AND then restart your ''nmbd'' daemon: /etc/init.d/samba restart OK so what do the configuration lines mean? * ''workgroup = AMBER'' - this line makes the SaMBa server a member of workgroup AMBER. * ''netbios name = DWORKIN'' - here we define the server NetBIOS name to be "dworkin". * ''wins support = yes'' - this line actually turns on the WINS support, so it instructs the ''nmbd'' daemon to start acting as a WINS server. * ''os level = 33'' - this gives our WINS server a "rank" of 33, meaning that it will be sure to become the WINS master browser, even if there are Windows servers on the network tat act as domain controllers. * ''domain master = yes'' - this will tell our server that it will not be just any master browser, but a '''domain''' master browser, so that our server will be the master browser on each and every subnet that it is connected to. * ''local master = yes'' - this setting is vital to being a domain master browser, as it ensures that our WINS server is also the local master browser. * ''preferred master = yes'' - adding this line makes the ''nmbd'' daemon initiate a browser election as soon as it starts up, so that it essentially gets the master browser role as fast as possible. * ''name resolve order = wins lmhosts hosts bcast'' - this ensures that for a WINS request, the ''nmbd'' daemon not only checks its WINS database, but also the local ''lmhosts'' file (if it exists), the Linux ''/etc/hosts'' file, and finally, to revert to a broadcast to see if it can locate the requested name by shouting out for it. * ''dns proxy = yes'' - this makes ''nmbd'' to check a requested name with the DNS server, if it cannot be found in the WINS database itself. After restarting, we can see if our Linux server is now a WINS master browser by inspecting the SaMBa log file, by default ''/var/log/samba/nmbd.log''. It should show something like [2008/11/21 16:18:03, 0] nmbd/nmbd.c:main(849) nmbd version 3.2.4 started. Copyright Andrew Tridgell and the Samba Team 1992-2008 [2008/11/21 16:18:03, 0] nmbd/asyncdns.c:start_async_dns(155) started asyncdns process 25707 [2008/11/21 16:18:03, 0] nmbd/nmbd_become_dmb.c:become_domain_master_browser_wins(336) become_domain_master_browser_wins: Attempting to become domain master browser on workgroup AMBER, subnet UNICAST_SUBNET. [2008/11/21 16:18:03, 0] nmbd/nmbd_become_dmb.c:become_domain_master_browser_wins(350) become_domain_master_browser_wins: querying WINS server from IP 192.168.67.10 for domain master browser name AMBER<1b> on workgroup AMBER [2008/11/21 16:18:03, 0] nmbd/nmbd_become_dmb.c:become_domain_master_stage2(110) ***** Samba server DWORKIN is now a domain master browser for workgroup AMBER on subnet UNICAST_SUBNET ***** [2008/11/21 16:18:03, 0] nmbd/nmbd_become_dmb.c:become_domain_master_browser_bcast(291) become_domain_master_browser_bcast: Attempting to become domain master browser on workgroup AMBER on subnet 192.168.67.10 [2008/11/21 16:18:03, 0] nmbd/nmbd_become_dmb.c:become_domain_master_browser_bcast(304) become_domain_master_browser_bcast: querying subnet 192.168.67.9 for domain master browser on workgroup AMBER [2008/11/21 16:18:11, 0] nmbd/nmbd_become_dmb.c:become_domain_master_stage2(110) ***** Samba server DWORKIN is now a domain master browser for workgroup AMBER on subnet 192.168.67.10 ***** [2008/11/21 16:18:26, 0] nmbd/nmbd_become_lmb.c:become_local_master_stage2(395) ***** Samba name server DWORKIN is now a local master browser for workgroup AMBER on subnet 192.168.67.10 ***** Furthermore, we can test on the server itself if a WINS lookup succeeds: dworkin:# nmblookup -M amber querying amber on 127.255.255.255 192.168.67.10 amber<1d> Finally, we tell our DHCP server to provide clients with the IP address of our WINS server. We do this by adding the following line to ''/etc/dhcp3-server/dhcpd.conf'': option netbios-name-servers 192.168.67.10 This line can either be added to the global section, or within the ''subnet'' declaration for each individual subnet that you want to inform of this WINS server. === OpenLDAP adaptation === In order for our OpenLDAP server to recognise the SaMBa-specific attributes that we're going to use, we need to add the "samba" schema to the OpenLDAP server. After installation of ''samba-doc'', we can find this schema in ''/usr/share/doc/samba-doc/examples/LDAP'', where it sits gzipped between some other schema files; as the README explains, what we need is ''samba.schema.gz'', so we unzip it and copy it to our OpenLDAP schema directory cd /usr/share/doc/samba-doc/examples/LDAP gunzip samba.schema.gz cp samba.schema /etc/ldap/schema Next up, we include this schema into our LDAP configuration, by adding the following line to ''/etc/ldap/slapd.conf'': include /etc/ldap/schema/samba.schema Not only do we need schema updates, we could also do with some more indices. Thus, we change the relevant section of ''/etc/ldap/slapd.conf'' to read: # Indexing options for database #1 index objectClass,uidNumber,gidNumber eq index cn,sn,uid,displayName pres,sub,eq index memberUid,mail,givenname eq,subinitial index sambaSID,sambaPrimaryGroupSID,sambaDomainName eq Ofcourse, it's not just enough to add these parameters, we also need to generate the indices, and restart our LDAP server: sudo invoke-rc.d slapd stop sudo -u openldap slapindex sudo invoke-rc.d slapd start Check to see if the Samba objects are now usable in your LDAP server, e.g. by opening your LDAP Account Manager, and go to tools > schema browser; you should have objects like "sambaConfig" and "sambaDomain". == Samba configuration for LDAP authentication== To get SaMBA to use OpenLDAP as a backend is actually quite straightforward. The main work is done in ''smb.conf.master'', where we add the following section: passdb backend = ldapsam:ldap://127.0.0.1 ldap suffix = dc=saruman,dc=biz ldap machine suffix = ou=hosts ldap user suffix = ou=people ldap group suffix = ou=groups ldap admin dn = cn=admin,dc=saruman,dc=biz ldap delete dn = no # allow user privileges enable privileges = yes One note: if you use ''testparm -s'' to test and convert ''smb.conf.master'', then it's possible that your ''ldap suffix'' statement gets lower than one or more than the other ''ldap'' statements; you should rectify that before starting SaMBa, because otherwise SaMBa gets mighty confused, and cannot find the right LDAP OU's. Now the above declares the LDAP account ''admin,saruman,biz'' to be the LDAP admin account - but SaMBa hasn't got the admin password yet, so it can't do much. To this end, we let SaMBa store the password for this admin account in its own little secret file ''/etc/samba/secrets.tdb''. We do this by running smbpasswd -W Setting stored password for "cn=admin,dc=saruman,dc=biz" in secrets.tdb New SMB password: Retype new SMB password: If we used a lowercase ''-w'', then we could have specified the password on the command line (''smbpasswd -w SuperSecret''). f73a28873c618d3a4ea442b2863f7febb18c400c 2023 2022 2008-11-22T10:12:03Z Saruman! 2 Started share config wikitext text/x-wiki == The Samba Section== == Preparations == First off, get yourself [http://oreilly.com/catalog/9780596007690/index.html this wonderful book] - and READ IT. Next, make sure our user backend of choice, OpenLDAP, is properly installed and can be used to authenticate users. If you haven't yet installed OpenLDAP, go to [[OpenLDAP | the relevant section]] of this wiki, and get going. Make sure your OpenLDAP is running well. === Software installation === This is easy: using ''aptitude'', install the following packages: * ''samba'', the actual server. * ''samba-tools'', a set of utilities. * ''samba-doc'' - note that we NEED ''samba-doc'', as this package contains a configuration file that we need (the LDAP schema file). * ''smbclient'', that can make your Linux server work with a Windows or SaMBa server; we need this to test our own server. As usual, Debian is asking us for the configuration details. For SaMBa 3.2, there are only two simple questions: * What do you want to be your Windows workgroup name? (we provide the name "AMBER") * Do you want to modify ''smb.conf'' to use WINS setting from DHCP? (we provide "no") Now we have our SaMBa configuration file as ''/etc/samba/smb.conf'', but we're going to follow two time-honoured tradions: we're going to save the original configuration file for future reference, and we're going to rename our configuration file to ''smb.conf.master'', while providing SaMBa with a comment-stripped version of it: cd /etc/samba cp smb.conf smb.conf.sample mv smb.conf smb.conf.master testparm smb.conf.master testparm -s smb.conf.master > smb.conf Now remember: when we want to change our SaMBa configuration, we edit ''smb.conf.master''. Once we're ready with that, we ALWAYS need to run those last two lines; the first of those will check our updated configuration, to see if we haven't made some silly typo that renders the configuration wholly or partially crippled, and the second one creates a comment-stripped version of it that SaMBa will actually be using. === WINS configuration === To enable WINS, we add the following lines to ''smb.conf.master'': ## Browsing/Identification ### workgroup = AMBER netbios name = DWORKIN # Windows Internet Name Serving Support Section: # WINS Support - Tells the NMBD component of Samba to enable its WINS Server wins support = yes os level = 33 domain master = yes local master = yes preferred master = yes name resolve order = wins lmhosts hosts bcast dns proxy = yes Now this does a whole lot of things with the SaMBa ''nmbd'' daemon - at least when you remember to save the master config file, test it with ''testparm'' and write the actual ''smb.conf'' as desribed previously, AND then restart your ''nmbd'' daemon: /etc/init.d/samba restart OK so what do the configuration lines mean? * ''workgroup = AMBER'' - this line makes the SaMBa server a member of workgroup AMBER. * ''netbios name = DWORKIN'' - here we define the server NetBIOS name to be "dworkin". * ''wins support = yes'' - this line actually turns on the WINS support, so it instructs the ''nmbd'' daemon to start acting as a WINS server. * ''os level = 33'' - this gives our WINS server a "rank" of 33, meaning that it will be sure to become the WINS master browser, even if there are Windows servers on the network tat act as domain controllers. * ''domain master = yes'' - this will tell our server that it will not be just any master browser, but a '''domain''' master browser, so that our server will be the master browser on each and every subnet that it is connected to. * ''local master = yes'' - this setting is vital to being a domain master browser, as it ensures that our WINS server is also the local master browser. * ''preferred master = yes'' - adding this line makes the ''nmbd'' daemon initiate a browser election as soon as it starts up, so that it essentially gets the master browser role as fast as possible. * ''name resolve order = wins lmhosts hosts bcast'' - this ensures that for a WINS request, the ''nmbd'' daemon not only checks its WINS database, but also the local ''lmhosts'' file (if it exists), the Linux ''/etc/hosts'' file, and finally, to revert to a broadcast to see if it can locate the requested name by shouting out for it. * ''dns proxy = yes'' - this makes ''nmbd'' to check a requested name with the DNS server, if it cannot be found in the WINS database itself. After restarting, we can see if our Linux server is now a WINS master browser by inspecting the SaMBa log file, by default ''/var/log/samba/nmbd.log''. It should show something like [2008/11/21 16:18:03, 0] nmbd/nmbd.c:main(849) nmbd version 3.2.4 started. Copyright Andrew Tridgell and the Samba Team 1992-2008 [2008/11/21 16:18:03, 0] nmbd/asyncdns.c:start_async_dns(155) started asyncdns process 25707 [2008/11/21 16:18:03, 0] nmbd/nmbd_become_dmb.c:become_domain_master_browser_wins(336) become_domain_master_browser_wins: Attempting to become domain master browser on workgroup AMBER, subnet UNICAST_SUBNET. [2008/11/21 16:18:03, 0] nmbd/nmbd_become_dmb.c:become_domain_master_browser_wins(350) become_domain_master_browser_wins: querying WINS server from IP 192.168.67.10 for domain master browser name AMBER<1b> on workgroup AMBER [2008/11/21 16:18:03, 0] nmbd/nmbd_become_dmb.c:become_domain_master_stage2(110) ***** Samba server DWORKIN is now a domain master browser for workgroup AMBER on subnet UNICAST_SUBNET ***** [2008/11/21 16:18:03, 0] nmbd/nmbd_become_dmb.c:become_domain_master_browser_bcast(291) become_domain_master_browser_bcast: Attempting to become domain master browser on workgroup AMBER on subnet 192.168.67.10 [2008/11/21 16:18:03, 0] nmbd/nmbd_become_dmb.c:become_domain_master_browser_bcast(304) become_domain_master_browser_bcast: querying subnet 192.168.67.9 for domain master browser on workgroup AMBER [2008/11/21 16:18:11, 0] nmbd/nmbd_become_dmb.c:become_domain_master_stage2(110) ***** Samba server DWORKIN is now a domain master browser for workgroup AMBER on subnet 192.168.67.10 ***** [2008/11/21 16:18:26, 0] nmbd/nmbd_become_lmb.c:become_local_master_stage2(395) ***** Samba name server DWORKIN is now a local master browser for workgroup AMBER on subnet 192.168.67.10 ***** Furthermore, we can test on the server itself if a WINS lookup succeeds: dworkin:# nmblookup -M amber querying amber on 127.255.255.255 192.168.67.10 amber<1d> Finally, we tell our DHCP server to provide clients with the IP address of our WINS server. We do this by adding the following line to ''/etc/dhcp3-server/dhcpd.conf'': option netbios-name-servers 192.168.67.10 This line can either be added to the global section, or within the ''subnet'' declaration for each individual subnet that you want to inform of this WINS server. === OpenLDAP adaptation === In order for our OpenLDAP server to recognise the SaMBa-specific attributes that we're going to use, we need to add the "samba" schema to the OpenLDAP server. After installation of ''samba-doc'', we can find this schema in ''/usr/share/doc/samba-doc/examples/LDAP'', where it sits gzipped between some other schema files; as the README explains, what we need is ''samba.schema.gz'', so we unzip it and copy it to our OpenLDAP schema directory cd /usr/share/doc/samba-doc/examples/LDAP gunzip samba.schema.gz cp samba.schema /etc/ldap/schema Next up, we include this schema into our LDAP configuration, by adding the following line to ''/etc/ldap/slapd.conf'': include /etc/ldap/schema/samba.schema Not only do we need schema updates, we could also do with some more indices. Thus, we change the relevant section of ''/etc/ldap/slapd.conf'' to read: # Indexing options for database #1 index objectClass,uidNumber,gidNumber eq index cn,sn,uid,displayName pres,sub,eq index memberUid,mail,givenname eq,subinitial index sambaSID,sambaPrimaryGroupSID,sambaDomainName eq Ofcourse, it's not just enough to add these parameters, we also need to generate the indices, and restart our LDAP server: sudo invoke-rc.d slapd stop sudo -u openldap slapindex sudo invoke-rc.d slapd start Check to see if the Samba objects are now usable in your LDAP server, e.g. by opening your LDAP Account Manager, and go to tools > schema browser; you should have objects like "sambaConfig" and "sambaDomain". == Samba configuration for LDAP authentication== To get SaMBA to use OpenLDAP as a backend is actually quite straightforward. The main work is done in ''smb.conf.master'', where we add the following section: passdb backend = ldapsam:ldap://127.0.0.1 ldap suffix = dc=saruman,dc=biz ldap machine suffix = ou=hosts ldap user suffix = ou=people ldap group suffix = ou=groups ldap admin dn = cn=admin,dc=saruman,dc=biz ldap delete dn = no # allow user privileges enable privileges = yes One note: if you use ''testparm -s'' to test and convert ''smb.conf.master'', then it's possible that your ''ldap suffix'' statement gets lower than one or more than the other ''ldap'' statements; you should rectify that before starting SaMBa, because otherwise SaMBa gets mighty confused, and cannot find the right LDAP OU's. Now the above declares the LDAP account ''admin,saruman,biz'' to be the LDAP admin account - but SaMBa hasn't got the admin password yet, so it can't do much. To this end, we let SaMBa store the password for this admin account in its own little secret file ''/etc/samba/secrets.tdb''. We do this by running smbpasswd -W Setting stored password for "cn=admin,dc=saruman,dc=biz" in secrets.tdb New SMB password: Retype new SMB password: If we used a lowercase ''-w'', then we could have specified the password on the command line (''smbpasswd -w SuperSecret''). = Samba share configuration With the above configuration, we should now be able to create a share, and make it available to our LDAP accounts. To this end, we create a directory that we're going to share, and give it a workable set of permissions. Suppose we have an LDAP user "jan" and an LDAP group "networkusers". We could then, as root, do this: cd /data/samba mkdir Data chown jan:networkusers Data chmod 1777 Data This ensures that user "jan", as well as every user that's a member of "networkusers", is allowed to read and write in this share. However, thanks to the "sticky bit" set with the ''chmod'' command, all files that are written to this directory will get "jan:networkusers" as their owner. Next step would be to share this directory, by adding the following section to ''smb.conf.master'': [Data] comment = Data directory for us all browseable = yes path = /data/samba/Data guest ok = no read only = no create mask = 0660 fc0fdb3112fd3fa2a499f77cbf292f599c2e39ae 2024 2023 2008-11-22T11:18:30Z Saruman! 2 /* Feed OpenLDAP with Samba information */ started with LAM input wikitext text/x-wiki == The Samba Section== == Preparations == First off, get yourself [http://oreilly.com/catalog/9780596007690/index.html this wonderful book] - and READ IT. Next, make sure our user backend of choice, OpenLDAP, is properly installed and can be used to authenticate users. If you haven't yet installed OpenLDAP, go to [[OpenLDAP | the relevant section]] of this wiki, and get going. Make sure your OpenLDAP is running well. === Software installation === This is easy: using ''aptitude'', install the following packages: * ''samba'', the actual server. * ''samba-tools'', a set of utilities. * ''samba-doc'' - note that we NEED ''samba-doc'', as this package contains a configuration file that we need (the LDAP schema file). * ''smbclient'', that can make your Linux server work with a Windows or SaMBa server; we need this to test our own server. As usual, Debian is asking us for the configuration details. For SaMBa 3.2, there are only two simple questions: * What do you want to be your Windows workgroup name? (we provide the name "AMBER") * Do you want to modify ''smb.conf'' to use WINS setting from DHCP? (we provide "no") Now we have our SaMBa configuration file as ''/etc/samba/smb.conf'', but we're going to follow two time-honoured tradions: we're going to save the original configuration file for future reference, and we're going to rename our configuration file to ''smb.conf.master'', while providing SaMBa with a comment-stripped version of it: cd /etc/samba cp smb.conf smb.conf.sample mv smb.conf smb.conf.master testparm smb.conf.master testparm -s smb.conf.master > smb.conf Now remember: when we want to change our SaMBa configuration, we edit ''smb.conf.master''. Once we're ready with that, we ALWAYS need to run those last two lines; the first of those will check our updated configuration, to see if we haven't made some silly typo that renders the configuration wholly or partially crippled, and the second one creates a comment-stripped version of it that SaMBa will actually be using. === WINS configuration === To enable WINS, we add the following lines to ''smb.conf.master'': ## Browsing/Identification ### workgroup = AMBER netbios name = DWORKIN # Windows Internet Name Serving Support Section: # WINS Support - Tells the NMBD component of Samba to enable its WINS Server wins support = yes os level = 33 domain master = yes local master = yes preferred master = yes name resolve order = wins lmhosts hosts bcast dns proxy = yes Now this does a whole lot of things with the SaMBa ''nmbd'' daemon - at least when you remember to save the master config file, test it with ''testparm'' and write the actual ''smb.conf'' as desribed previously, AND then restart your ''nmbd'' daemon: /etc/init.d/samba restart OK so what do the configuration lines mean? * ''workgroup = AMBER'' - this line makes the SaMBa server a member of workgroup AMBER. * ''netbios name = DWORKIN'' - here we define the server NetBIOS name to be "dworkin". * ''wins support = yes'' - this line actually turns on the WINS support, so it instructs the ''nmbd'' daemon to start acting as a WINS server. * ''os level = 33'' - this gives our WINS server a "rank" of 33, meaning that it will be sure to become the WINS master browser, even if there are Windows servers on the network tat act as domain controllers. * ''domain master = yes'' - this will tell our server that it will not be just any master browser, but a '''domain''' master browser, so that our server will be the master browser on each and every subnet that it is connected to. * ''local master = yes'' - this setting is vital to being a domain master browser, as it ensures that our WINS server is also the local master browser. * ''preferred master = yes'' - adding this line makes the ''nmbd'' daemon initiate a browser election as soon as it starts up, so that it essentially gets the master browser role as fast as possible. * ''name resolve order = wins lmhosts hosts bcast'' - this ensures that for a WINS request, the ''nmbd'' daemon not only checks its WINS database, but also the local ''lmhosts'' file (if it exists), the Linux ''/etc/hosts'' file, and finally, to revert to a broadcast to see if it can locate the requested name by shouting out for it. * ''dns proxy = yes'' - this makes ''nmbd'' to check a requested name with the DNS server, if it cannot be found in the WINS database itself. After restarting, we can see if our Linux server is now a WINS master browser by inspecting the SaMBa log file, by default ''/var/log/samba/nmbd.log''. It should show something like [2008/11/21 16:18:03, 0] nmbd/nmbd.c:main(849) nmbd version 3.2.4 started. Copyright Andrew Tridgell and the Samba Team 1992-2008 [2008/11/21 16:18:03, 0] nmbd/asyncdns.c:start_async_dns(155) started asyncdns process 25707 [2008/11/21 16:18:03, 0] nmbd/nmbd_become_dmb.c:become_domain_master_browser_wins(336) become_domain_master_browser_wins: Attempting to become domain master browser on workgroup AMBER, subnet UNICAST_SUBNET. [2008/11/21 16:18:03, 0] nmbd/nmbd_become_dmb.c:become_domain_master_browser_wins(350) become_domain_master_browser_wins: querying WINS server from IP 192.168.67.10 for domain master browser name AMBER<1b> on workgroup AMBER [2008/11/21 16:18:03, 0] nmbd/nmbd_become_dmb.c:become_domain_master_stage2(110) ***** Samba server DWORKIN is now a domain master browser for workgroup AMBER on subnet UNICAST_SUBNET ***** [2008/11/21 16:18:03, 0] nmbd/nmbd_become_dmb.c:become_domain_master_browser_bcast(291) become_domain_master_browser_bcast: Attempting to become domain master browser on workgroup AMBER on subnet 192.168.67.10 [2008/11/21 16:18:03, 0] nmbd/nmbd_become_dmb.c:become_domain_master_browser_bcast(304) become_domain_master_browser_bcast: querying subnet 192.168.67.9 for domain master browser on workgroup AMBER [2008/11/21 16:18:11, 0] nmbd/nmbd_become_dmb.c:become_domain_master_stage2(110) ***** Samba server DWORKIN is now a domain master browser for workgroup AMBER on subnet 192.168.67.10 ***** [2008/11/21 16:18:26, 0] nmbd/nmbd_become_lmb.c:become_local_master_stage2(395) ***** Samba name server DWORKIN is now a local master browser for workgroup AMBER on subnet 192.168.67.10 ***** Furthermore, we can test on the server itself if a WINS lookup succeeds: dworkin:# nmblookup -M amber querying amber on 127.255.255.255 192.168.67.10 amber<1d> Finally, we tell our DHCP server to provide clients with the IP address of our WINS server. We do this by adding the following line to ''/etc/dhcp3-server/dhcpd.conf'': option netbios-name-servers 192.168.67.10 This line can either be added to the global section, or within the ''subnet'' declaration for each individual subnet that you want to inform of this WINS server. === OpenLDAP adaptation === In order for our OpenLDAP server to recognise the SaMBa-specific attributes that we're going to use, we need to add the "samba" schema to the OpenLDAP server. After installation of ''samba-doc'', we can find this schema in ''/usr/share/doc/samba-doc/examples/LDAP'', where it sits gzipped between some other schema files; as the README explains, what we need is ''samba.schema.gz'', so we unzip it and copy it to our OpenLDAP schema directory cd /usr/share/doc/samba-doc/examples/LDAP gunzip samba.schema.gz cp samba.schema /etc/ldap/schema Next up, we include this schema into our LDAP configuration, by adding the following line to ''/etc/ldap/slapd.conf'': include /etc/ldap/schema/samba.schema Not only do we need schema updates, we could also do with some more indices. Thus, we change the relevant section of ''/etc/ldap/slapd.conf'' to read: # Indexing options for database #1 index objectClass,uidNumber,gidNumber eq index cn,sn,uid,displayName pres,sub,eq index memberUid,mail,givenname eq,subinitial index sambaSID,sambaPrimaryGroupSID,sambaDomainName eq Ofcourse, it's not just enough to add these parameters, we also need to generate the indices, and restart our LDAP server: sudo invoke-rc.d slapd stop sudo -u openldap slapindex sudo invoke-rc.d slapd start Check to see if the Samba objects are now usable in your LDAP server, e.g. by opening your LDAP Account Manager, and go to tools > schema browser; you should have objects like "sambaConfig" and "sambaDomain". === Feed OpenLDAP with Samba information=== Now we can add the Samba3 account information to our LDAP server. There are two ways of doing that: create an LDAP ldif file with the necessary information, or use the graphic LDAP manager to add it. For small amounts of users, the last way is quickest. What you need is to take two steps: '''Add the SaMBa domain to the LDAP tree'''<br> For this step, as root you perform the following command net getlocalsid This will a string like "SID for domain DWORKIN is: S-1-5-21-2406862431-3150385097-213705319". With this SID, we can create the LDAP object that represents the SaMBa domain. To that end we log into our LDAP account manager, go to "Samba domains", and create our domain. There are only three pieces of information that are mandatory: * the domain name, in our example "amber" * the forementioned SID, in our example "S-1-5-21-2406862431-3150385097-213705319". * the RID base; this has a default of 1000, which you should not change unless you know exactly what you're doing. However, there are other options that you might find it worth setting, like the minimal password length, password history length, if users should be disconnected "outside logon hours" etcetera. We would advise you to not set too many options until you've finished testing all basic functionality of your SaMBa server. In case you're curious, the LDAP ldif file for such an account could look like this: dn: sambaDomainName=amber,ou=domains,dc=saruman,dc=biz objectClass: sambaDomain sambaDomainName: amber sambaSID: S-1-5-21-2476862421-3150885297-210706319 sambaAlgorithmicRidBase: 1000 sambaMinPwdLength: 7 sambaPwdHistoryLength: 5 sambaLogonToChgPwd: 0 sambaForceLogoff: -1 sambaRefuseMachinePwdChange: 1 dn: sambaDomainName=DWORKIN,dc=saruman,dc=biz objectClass: sambaDomain sambaDomainName: DWORKIN sambaSID: S-1-5-21-2476862421-3150885297-210706319 sambaAlgorithmicRidBase: 1000 sambaNextUserRid: 1000 sambaMinPwdLength: 5 sambaPwdHistoryLength: 0 sambaLogonToChgPwd: 0 sambaMaxPwdAge: -1 sambaMinPwdAge: 0 sambaLockoutDuration: 30 sambaLockoutObservationWindow: 30 sambaLockoutThreshold: 0 sambaForceLogoff: -1 sambaRefuseMachinePwdChange: 0 '''Add the SaMBa account information to LDAP user accounts'''<br> Again we use our LDAP account manager, and we now go to a user that we want to provide access to SaMBa. When you choose to edit the user, there should be a tab "Samba 3". In this tab, you can click the button "Add Samba 3 account"; until you've done that, this user has no access at all to the Samba server.<br> When adding (or changing) a users Samba account information, there is actually only one mandatory field: * "Domain": from this pulldown list you can choose the SaMBa/Windows domain that the user will belong to. When you have only your one SaMBa domain entered in your LDAP, this field will show the name of that domain. Furthermore, there are a few more fields that you might want to fill. They are: * "Display name": the name that Windows shows for a user * "Samba password": this may be a different password from a Unix account that the user may have * Windows group: this is the primary group that the user belongs to, from a SaMBa perspective instead of a Unix perspective. Having added the necessary information, the user should be able from a Windows machine to browse the SaMBa server, and see all non-hidden shares that are available to him. Furthermore, from a Linux prompt, you could use ''smbclient'' to verify that SaMBa honours the users name and password: smbclient //192.168.67.10/Data -U jan If the Data share has been made (for that: see further down), and if user "jan" has a Samba account in LDAP, and if you type the correct password, then you're greeted with an SMB client prompt: smb: \> Here you can type commands like "dir", "del" and "mkdir"; type "help" to see all available commands. == Samba configuration for LDAP authentication== To get SaMBA to use OpenLDAP as a backend is actually quite straightforward. The main work is done in ''smb.conf.master'', where we add the following section: passdb backend = ldapsam:ldap://127.0.0.1 ldap suffix = dc=saruman,dc=biz ldap machine suffix = ou=hosts ldap user suffix = ou=people ldap group suffix = ou=groups ldap admin dn = cn=admin,dc=saruman,dc=biz ldap delete dn = no # allow user privileges enable privileges = yes One note: if you use ''testparm -s'' to test and convert ''smb.conf.master'', then it's possible that your ''ldap suffix'' statement gets lower than one or more than the other ''ldap'' statements; you should rectify that before starting SaMBa, because otherwise SaMBa gets mighty confused, and cannot find the right LDAP OU's. Now the above declares the LDAP account ''admin,saruman,biz'' to be the LDAP admin account - but SaMBa hasn't got the admin password yet, so it can't do much. To this end, we let SaMBa store the password for this admin account in its own little secret file ''/etc/samba/secrets.tdb''. We do this by running smbpasswd -W Setting stored password for "cn=admin,dc=saruman,dc=biz" in secrets.tdb New SMB password: Retype new SMB password: If we used a lowercase ''-w'', then we could have specified the password on the command line (''smbpasswd -w SuperSecret''). = Samba share configuration With the above configuration, we should now be able to create a share, and make it available to our LDAP accounts. To this end, we create a directory that we're going to share, and give it a workable set of permissions. Suppose we have an LDAP user "jan" and an LDAP group "networkusers". We could then, as root, do this: cd /data/samba mkdir Data chown jan:networkusers Data chmod 1777 Data This ensures that user "jan", as well as every user that's a member of "networkusers", is allowed to read and write in this share. However, thanks to the "sticky bit" set with the ''chmod'' command, all files that are written to this directory will get "jan:networkusers" as their owner. Next step would be to share this directory, by adding the following section to ''smb.conf.master'': [Data] comment = Data directory for us all browseable = yes path = /data/samba/Data guest ok = no read only = no create mask = 0660 689d8cbdcbec880d474dfb36191df8f8f4537389 2025 2024 2008-11-22T17:22:04Z Saruman! 2 /* Samba share configuration */ started wikitext text/x-wiki == The Samba Section== == Preparations == First off, get yourself [http://oreilly.com/catalog/9780596007690/index.html this wonderful book] - and READ IT. Next, make sure our user backend of choice, OpenLDAP, is properly installed and can be used to authenticate users. If you haven't yet installed OpenLDAP, go to [[OpenLDAP | the relevant section]] of this wiki, and get going. Make sure your OpenLDAP is running well. === Software installation === This is easy: using ''aptitude'', install the following packages: * ''samba'', the actual server. * ''samba-tools'', a set of utilities. * ''samba-doc'' - note that we NEED ''samba-doc'', as this package contains a configuration file that we need (the LDAP schema file). * ''smbclient'', that can make your Linux server work with a Windows or SaMBa server; we need this to test our own server. As usual, Debian is asking us for the configuration details. For SaMBa 3.2, there are only two simple questions: * What do you want to be your Windows workgroup name? (we provide the name "AMBER") * Do you want to modify ''smb.conf'' to use WINS setting from DHCP? (we provide "no") Now we have our SaMBa configuration file as ''/etc/samba/smb.conf'', but we're going to follow two time-honoured tradions: we're going to save the original configuration file for future reference, and we're going to rename our configuration file to ''smb.conf.master'', while providing SaMBa with a comment-stripped version of it: cd /etc/samba cp smb.conf smb.conf.sample mv smb.conf smb.conf.master testparm smb.conf.master testparm -s smb.conf.master > smb.conf Now remember: when we want to change our SaMBa configuration, we edit ''smb.conf.master''. Once we're ready with that, we ALWAYS need to run those last two lines; the first of those will check our updated configuration, to see if we haven't made some silly typo that renders the configuration wholly or partially crippled, and the second one creates a comment-stripped version of it that SaMBa will actually be using. === WINS configuration === To enable WINS, we add the following lines to ''smb.conf.master'': ## Browsing/Identification ### workgroup = AMBER netbios name = DWORKIN # Windows Internet Name Serving Support Section: # WINS Support - Tells the NMBD component of Samba to enable its WINS Server wins support = yes os level = 33 domain master = yes local master = yes preferred master = yes name resolve order = wins lmhosts hosts bcast dns proxy = yes Now this does a whole lot of things with the SaMBa ''nmbd'' daemon - at least when you remember to save the master config file, test it with ''testparm'' and write the actual ''smb.conf'' as desribed previously, AND then restart your ''nmbd'' daemon: /etc/init.d/samba restart OK so what do the configuration lines mean? * ''workgroup = AMBER'' - this line makes the SaMBa server a member of workgroup AMBER. * ''netbios name = DWORKIN'' - here we define the server NetBIOS name to be "dworkin". * ''wins support = yes'' - this line actually turns on the WINS support, so it instructs the ''nmbd'' daemon to start acting as a WINS server. * ''os level = 33'' - this gives our WINS server a "rank" of 33, meaning that it will be sure to become the WINS master browser, even if there are Windows servers on the network tat act as domain controllers. * ''domain master = yes'' - this will tell our server that it will not be just any master browser, but a '''domain''' master browser, so that our server will be the master browser on each and every subnet that it is connected to. * ''local master = yes'' - this setting is vital to being a domain master browser, as it ensures that our WINS server is also the local master browser. * ''preferred master = yes'' - adding this line makes the ''nmbd'' daemon initiate a browser election as soon as it starts up, so that it essentially gets the master browser role as fast as possible. * ''name resolve order = wins lmhosts hosts bcast'' - this ensures that for a WINS request, the ''nmbd'' daemon not only checks its WINS database, but also the local ''lmhosts'' file (if it exists), the Linux ''/etc/hosts'' file, and finally, to revert to a broadcast to see if it can locate the requested name by shouting out for it. * ''dns proxy = yes'' - this makes ''nmbd'' to check a requested name with the DNS server, if it cannot be found in the WINS database itself. After restarting, we can see if our Linux server is now a WINS master browser by inspecting the SaMBa log file, by default ''/var/log/samba/nmbd.log''. It should show something like [2008/11/21 16:18:03, 0] nmbd/nmbd.c:main(849) nmbd version 3.2.4 started. Copyright Andrew Tridgell and the Samba Team 1992-2008 [2008/11/21 16:18:03, 0] nmbd/asyncdns.c:start_async_dns(155) started asyncdns process 25707 [2008/11/21 16:18:03, 0] nmbd/nmbd_become_dmb.c:become_domain_master_browser_wins(336) become_domain_master_browser_wins: Attempting to become domain master browser on workgroup AMBER, subnet UNICAST_SUBNET. [2008/11/21 16:18:03, 0] nmbd/nmbd_become_dmb.c:become_domain_master_browser_wins(350) become_domain_master_browser_wins: querying WINS server from IP 192.168.67.10 for domain master browser name AMBER<1b> on workgroup AMBER [2008/11/21 16:18:03, 0] nmbd/nmbd_become_dmb.c:become_domain_master_stage2(110) ***** Samba server DWORKIN is now a domain master browser for workgroup AMBER on subnet UNICAST_SUBNET ***** [2008/11/21 16:18:03, 0] nmbd/nmbd_become_dmb.c:become_domain_master_browser_bcast(291) become_domain_master_browser_bcast: Attempting to become domain master browser on workgroup AMBER on subnet 192.168.67.10 [2008/11/21 16:18:03, 0] nmbd/nmbd_become_dmb.c:become_domain_master_browser_bcast(304) become_domain_master_browser_bcast: querying subnet 192.168.67.9 for domain master browser on workgroup AMBER [2008/11/21 16:18:11, 0] nmbd/nmbd_become_dmb.c:become_domain_master_stage2(110) ***** Samba server DWORKIN is now a domain master browser for workgroup AMBER on subnet 192.168.67.10 ***** [2008/11/21 16:18:26, 0] nmbd/nmbd_become_lmb.c:become_local_master_stage2(395) ***** Samba name server DWORKIN is now a local master browser for workgroup AMBER on subnet 192.168.67.10 ***** Furthermore, we can test on the server itself if a WINS lookup succeeds: dworkin:# nmblookup -M amber querying amber on 127.255.255.255 192.168.67.10 amber<1d> Finally, we tell our DHCP server to provide clients with the IP address of our WINS server. We do this by adding the following line to ''/etc/dhcp3-server/dhcpd.conf'': option netbios-name-servers 192.168.67.10 This line can either be added to the global section, or within the ''subnet'' declaration for each individual subnet that you want to inform of this WINS server. === OpenLDAP adaptation === In order for our OpenLDAP server to recognise the SaMBa-specific attributes that we're going to use, we need to add the "samba" schema to the OpenLDAP server. After installation of ''samba-doc'', we can find this schema in ''/usr/share/doc/samba-doc/examples/LDAP'', where it sits gzipped between some other schema files; as the README explains, what we need is ''samba.schema.gz'', so we unzip it and copy it to our OpenLDAP schema directory cd /usr/share/doc/samba-doc/examples/LDAP gunzip samba.schema.gz cp samba.schema /etc/ldap/schema Next up, we include this schema into our LDAP configuration, by adding the following line to ''/etc/ldap/slapd.conf'': include /etc/ldap/schema/samba.schema Not only do we need schema updates, we could also do with some more indices. Thus, we change the relevant section of ''/etc/ldap/slapd.conf'' to read: # Indexing options for database #1 index objectClass,uidNumber,gidNumber eq index cn,sn,uid,displayName pres,sub,eq index memberUid,mail,givenname eq,subinitial index sambaSID,sambaPrimaryGroupSID,sambaDomainName eq Ofcourse, it's not just enough to add these parameters, we also need to generate the indices, and restart our LDAP server: sudo invoke-rc.d slapd stop sudo -u openldap slapindex sudo invoke-rc.d slapd start Check to see if the Samba objects are now usable in your LDAP server, e.g. by opening your LDAP Account Manager, and go to tools > schema browser; you should have objects like "sambaConfig" and "sambaDomain". === Feed OpenLDAP with Samba information=== Now we can add the Samba3 account information to our LDAP server. There are two ways of doing that: create an LDAP ldif file with the necessary information, or use the graphic LDAP manager to add it. For small amounts of users, the last way is quickest. What you need is to take two steps: '''Add the SaMBa domain to the LDAP tree'''<br> For this step, as root you perform the following command net getlocalsid This will a string like "SID for domain DWORKIN is: S-1-5-21-2406862431-3150385097-213705319". With this SID, we can create the LDAP object that represents the SaMBa domain. To that end we log into our LDAP account manager, go to "Samba domains", and create our domain. There are only three pieces of information that are mandatory: * the domain name, in our example "amber" * the forementioned SID, in our example "S-1-5-21-2406862431-3150385097-213705319". * the RID base; this has a default of 1000, which you should not change unless you know exactly what you're doing. However, there are other options that you might find it worth setting, like the minimal password length, password history length, if users should be disconnected "outside logon hours" etcetera. We would advise you to not set too many options until you've finished testing all basic functionality of your SaMBa server. In case you're curious, the LDAP ldif file for such an account could look like this: dn: sambaDomainName=amber,ou=domains,dc=saruman,dc=biz objectClass: sambaDomain sambaDomainName: amber sambaSID: S-1-5-21-2476862421-3150885297-210706319 sambaAlgorithmicRidBase: 1000 sambaMinPwdLength: 7 sambaPwdHistoryLength: 5 sambaLogonToChgPwd: 0 sambaForceLogoff: -1 sambaRefuseMachinePwdChange: 1 dn: sambaDomainName=DWORKIN,dc=saruman,dc=biz objectClass: sambaDomain sambaDomainName: DWORKIN sambaSID: S-1-5-21-2476862421-3150885297-210706319 sambaAlgorithmicRidBase: 1000 sambaNextUserRid: 1000 sambaMinPwdLength: 5 sambaPwdHistoryLength: 0 sambaLogonToChgPwd: 0 sambaMaxPwdAge: -1 sambaMinPwdAge: 0 sambaLockoutDuration: 30 sambaLockoutObservationWindow: 30 sambaLockoutThreshold: 0 sambaForceLogoff: -1 sambaRefuseMachinePwdChange: 0 '''Add the SaMBa account information to LDAP user accounts'''<br> Again we use our LDAP account manager, and we now go to a user that we want to provide access to SaMBa. When you choose to edit the user, there should be a tab "Samba 3". In this tab, you can click the button "Add Samba 3 account"; until you've done that, this user has no access at all to the Samba server.<br> When adding (or changing) a users Samba account information, there is actually only one mandatory field: * "Domain": from this pulldown list you can choose the SaMBa/Windows domain that the user will belong to. When you have only your one SaMBa domain entered in your LDAP, this field will show the name of that domain. Furthermore, there are a few more fields that you might want to fill. They are: * "Display name": the name that Windows shows for a user * "Samba password": this may be a different password from a Unix account that the user may have * Windows group: this is the primary group that the user belongs to, from a SaMBa perspective instead of a Unix perspective. Having added the necessary information, the user should be able from a Windows machine to browse the SaMBa server, and see all non-hidden shares that are available to him. Furthermore, from a Linux prompt, you could use ''smbclient'' to verify that SaMBa honours the users name and password: smbclient //192.168.67.10/Data -U jan If the Data share has been made (for that: see further down), and if user "jan" has a Samba account in LDAP, and if you type the correct password, then you're greeted with an SMB client prompt: smb: \> Here you can type commands like "dir", "del" and "mkdir"; type "help" to see all available commands. == Samba configuration for LDAP authentication== To get SaMBA to use OpenLDAP as a backend is actually quite straightforward. The main work is done in ''smb.conf.master'', where we add the following section: passdb backend = ldapsam:ldap://127.0.0.1 ldap suffix = dc=saruman,dc=biz ldap machine suffix = ou=hosts ldap user suffix = ou=people ldap group suffix = ou=groups ldap admin dn = cn=admin,dc=saruman,dc=biz ldap delete dn = no # allow user privileges enable privileges = yes One note: if you use ''testparm -s'' to test and convert ''smb.conf.master'', then it's possible that your ''ldap suffix'' statement gets lower than one or more than the other ''ldap'' statements; you should rectify that before starting SaMBa, because otherwise SaMBa gets mighty confused, and cannot find the right LDAP OU's. Now the above declares the LDAP account ''admin,saruman,biz'' to be the LDAP admin account - but SaMBa hasn't got the admin password yet, so it can't do much. To this end, we let SaMBa store the password for this admin account in its own little secret file ''/etc/samba/secrets.tdb''. We do this by running smbpasswd -W Setting stored password for "cn=admin,dc=saruman,dc=biz" in secrets.tdb New SMB password: Retype new SMB password: If we used a lowercase ''-w'', then we could have specified the password on the command line (''smbpasswd -w SuperSecret''). = Samba share configuration = With the above configuration, we should now be able to create a share, and make it available to our LDAP accounts. To this end, we create a directory that we're going to share, and give it a workable set of permissions. Suppose we have an LDAP user "jan" and an LDAP group "networkusers". We could then, as root, do this: cd /data/samba mkdir Data chown jan:networkusers Data chmod g+rwxs,o-rwx Data This ensures that user "jan", as well as every user that's a member of "networkusers", is allowed to read and write in this share. However, thanks to the "sticky bit" set for the group with the ''chmod'' command, files that are written to this directory are automatically owned by the group "networkusers", who have read & write rights. Next step would be to share this directory, by adding the following section to ''smb.conf.master'': [Data] comment = Data directory for us all browseable = yes path = /data/samba/Data guest ok = no read only = no create mask = 0770 create directory mask = 0770 This makes the directory usable via the share "Data". Notice that we do not allow unauthenticated users ("guest ok = no"), that we allow writing in this share ("read only = no", although we could also have used "writeable = yes", which is the same), and that we mask every create operation (for both files and directories) so that they can set any right under "user" and "group", but cannot set any rights under "other". This prevents anyone other than the "networkusers" to read (let alone write) the files in this share. e713bec6eb9dc6482d76ebed24eed0c6b5be68d4 0 1441 2029 1963 2008-12-05T11:29:22Z 125.63.66.202 0 0 wikitext text/x-wiki 04.txt;15;15 ==DNS resolution under Debian== One headache you might encounter when configuring a Debian server is how to let every program know how to resolve DNS names. Before a program can connect to an external network resource (say, for example, a web server), it must have a means of converting DNS names (e.g. www.saruman.biz) into the corresponding IP addresses (e.g. 192.168.67.10). This process is called "name resolution". The need for name resolution means that every program needs to know about the available means by which to do this name resolution. From the good old days comes the configuration file ''resolv.conf'', normally found in ''/etc''. It contains information about the nameservers to be used by the system, be they actual servers or lookup files. However, more and more programs have the need to dynamically modify the ''resolv.conf'' configuration file. This means that frequently they step on each other, and the ''resolv.conf'' file can become out-of-sync. The ''resolvconf'' program addresses this problem. It acts as an intermediary between programs that supply nameserver information (e.g. DHCP clients) and programs that use nameserver information (e.g. resolver). When ''resolvconf'' is properly installed, the file ''/etc/resolv.conf'' is replaced by a symbolic link to ''/etc/resolvconf/run/resolv.conf'', and any resolver thus uses the dynamically generated resolver configuration file at ''/etc/resolvconf/run/resolv.conf''. The ''resolvconf'' program is only necessary when a system has multiple programs that need to dynamically modify the nameserver information. In a simple system where the nameservers do not change often or are only changed by one program, the standard ''/etc/resolv.conf'' configuration file is adequate. == VLANs under Debian == Debian can support network traffic over VLANs (ethernet 802.1q) - and we don't mean the normal "untagged" network ports (hey, VLANs are transparent that way, anybody and anything can use untagged network ports). No, we mean that Debian can accept network traffic in from, and send traffic out to, a VLAN tagged switchport. Suppose you have a layer 2 switch with support for 802.1q VLANs, and want to route traffic from one VLAN to another. For this you can use a Debian router with a single network interface, using VLAN support (this is called "router on a stick" because the routing takes place over only one cable). First, as root, run apt-get install vlan modprobe 8021q The first line is to install the vlan package, which contains all necessary tools to create and manipulate VLAN-enabled network ports. The second line loads the module that enables VLAN tagging for your ethernet network cards. Note: if you don't have the stock Debian kernel, but compiled your own, then you might have chosen not to compile the 8021q module. In that case, compile the module. Also note, that if you've compiled the 8021q code into the kernel itself, then you don't need to load the module and that second line is unnecessary for you. You'll find this kernel compile option (depending on your kernel version) under Networking -> Networking Options -> "802.1Q VLAN Support". This option has been in the Linux kernel since version 2.4.14. ifconfig eth0 down vconfig add eth0 2 vconfig add eth0 3 The first command brings down your network on eth0 (not the thing to do if you're working remote, then :-). The next two commands create two virtual interfaces ''eth0.2'' and ''eth0.3'', which have VLAN tags 2 and 3 (don't use VLAN tag 1 if you can help it; on many devices VLAN1 is a special hardware management VLAN). The virtual interfaces run on top of your ''eth0'' interface.<br> Now because your VLAN interfaces run on top of ''eth0'', you've got to bring ''eth0'' itself up, even if you don't want to run network traffic over it. Furthermore, you've got to configure the two virtual interfaces you've created. Let's suppose you want to run IP subnet 192.168.1.0/24 on VLAN2, and 192.168.2.0/24 on VLAN3. You can do so with ifconfig eth0 0.0.0.0 up ifconfig eth0.2 192.168.1.1 broadcast 192.168.1.255 netmask 255.255.255.0 up ifconfig eth0.3 192.168.2.1 broadcast 192.168.2.255 netmask 255.255.255.0 up Now that you've this done, you must still configure one of your switch ports to belong to VLAN 2 and 3 at the same time (tagged port), and connect ''eth0'' from your linux box to that port. This enables your box to run network traffic on both VLANs. To round things up: if you haven't yet enabled forwarding, you can do so now. Furthermore, you might wish to augment your route table so that the routing engine in your server knows how to handle packets that it needs to forward from one VLAN to the other: echo 1 > /proc/sys/net/ipv4/ip_forward route add -net 10.1.1.0 netmask 255.255.255.0 gw eth0.2 route add -net 10.1.2.0 netmask 255.255.255.0 gw eth0.3 This is it; nothing to it, right? d0966eded495d89ede08fca58b7d828632c999e7 2030 2029 2008-12-05T13:19:15Z 76.180.28.191 0 /* DNS resolution under Debian */ wikitext text/x-wiki 04.txt;15;15 07.txt;15;15 == VLANs under Debian == Debian can support network traffic over VLANs (ethernet 802.1q) - and we don't mean the normal "untagged" network ports (hey, VLANs are transparent that way, anybody and anything can use untagged network ports). No, we mean that Debian can accept network traffic in from, and send traffic out to, a VLAN tagged switchport. Suppose you have a layer 2 switch with support for 802.1q VLANs, and want to route traffic from one VLAN to another. For this you can use a Debian router with a single network interface, using VLAN support (this is called "router on a stick" because the routing takes place over only one cable). First, as root, run apt-get install vlan modprobe 8021q The first line is to install the vlan package, which contains all necessary tools to create and manipulate VLAN-enabled network ports. The second line loads the module that enables VLAN tagging for your ethernet network cards. Note: if you don't have the stock Debian kernel, but compiled your own, then you might have chosen not to compile the 8021q module. In that case, compile the module. Also note, that if you've compiled the 8021q code into the kernel itself, then you don't need to load the module and that second line is unnecessary for you. You'll find this kernel compile option (depending on your kernel version) under Networking -> Networking Options -> "802.1Q VLAN Support". This option has been in the Linux kernel since version 2.4.14. ifconfig eth0 down vconfig add eth0 2 vconfig add eth0 3 The first command brings down your network on eth0 (not the thing to do if you're working remote, then :-). The next two commands create two virtual interfaces ''eth0.2'' and ''eth0.3'', which have VLAN tags 2 and 3 (don't use VLAN tag 1 if you can help it; on many devices VLAN1 is a special hardware management VLAN). The virtual interfaces run on top of your ''eth0'' interface.<br> Now because your VLAN interfaces run on top of ''eth0'', you've got to bring ''eth0'' itself up, even if you don't want to run network traffic over it. Furthermore, you've got to configure the two virtual interfaces you've created. Let's suppose you want to run IP subnet 192.168.1.0/24 on VLAN2, and 192.168.2.0/24 on VLAN3. You can do so with ifconfig eth0 0.0.0.0 up ifconfig eth0.2 192.168.1.1 broadcast 192.168.1.255 netmask 255.255.255.0 up ifconfig eth0.3 192.168.2.1 broadcast 192.168.2.255 netmask 255.255.255.0 up Now that you've this done, you must still configure one of your switch ports to belong to VLAN 2 and 3 at the same time (tagged port), and connect ''eth0'' from your linux box to that port. This enables your box to run network traffic on both VLANs. To round things up: if you haven't yet enabled forwarding, you can do so now. Furthermore, you might wish to augment your route table so that the routing engine in your server knows how to handle packets that it needs to forward from one VLAN to the other: echo 1 > /proc/sys/net/ipv4/ip_forward route add -net 10.1.1.0 netmask 255.255.255.0 gw eth0.2 route add -net 10.1.2.0 netmask 255.255.255.0 gw eth0.3 This is it; nothing to it, right? 268df082b1057cd4d6bdf65f00a1062aa7a43658 2031 2030 2008-12-05T13:51:23Z 78.105.14.211 0 0 wikitext text/x-wiki 04.txt;15;15 07.txt;15;15 08.txt;15;15 b157d9e836bacb74cda1697bc100c1ca318a744a 2032 2031 2008-12-05T13:59:22Z Saruman! 2 Reverted edits by [[Special:Contributions/78.105.14.211|78.105.14.211]] ([[User talk:78.105.14.211|Talk]]); changed back to last version by [[User:76.180.28.191|76.180.28.191]] wikitext text/x-wiki 04.txt;15;15 07.txt;15;15 == VLANs under Debian == Debian can support network traffic over VLANs (ethernet 802.1q) - and we don't mean the normal "untagged" network ports (hey, VLANs are transparent that way, anybody and anything can use untagged network ports). No, we mean that Debian can accept network traffic in from, and send traffic out to, a VLAN tagged switchport. Suppose you have a layer 2 switch with support for 802.1q VLANs, and want to route traffic from one VLAN to another. For this you can use a Debian router with a single network interface, using VLAN support (this is called "router on a stick" because the routing takes place over only one cable). First, as root, run apt-get install vlan modprobe 8021q The first line is to install the vlan package, which contains all necessary tools to create and manipulate VLAN-enabled network ports. The second line loads the module that enables VLAN tagging for your ethernet network cards. Note: if you don't have the stock Debian kernel, but compiled your own, then you might have chosen not to compile the 8021q module. In that case, compile the module. Also note, that if you've compiled the 8021q code into the kernel itself, then you don't need to load the module and that second line is unnecessary for you. You'll find this kernel compile option (depending on your kernel version) under Networking -> Networking Options -> "802.1Q VLAN Support". This option has been in the Linux kernel since version 2.4.14. ifconfig eth0 down vconfig add eth0 2 vconfig add eth0 3 The first command brings down your network on eth0 (not the thing to do if you're working remote, then :-). The next two commands create two virtual interfaces ''eth0.2'' and ''eth0.3'', which have VLAN tags 2 and 3 (don't use VLAN tag 1 if you can help it; on many devices VLAN1 is a special hardware management VLAN). The virtual interfaces run on top of your ''eth0'' interface.<br> Now because your VLAN interfaces run on top of ''eth0'', you've got to bring ''eth0'' itself up, even if you don't want to run network traffic over it. Furthermore, you've got to configure the two virtual interfaces you've created. Let's suppose you want to run IP subnet 192.168.1.0/24 on VLAN2, and 192.168.2.0/24 on VLAN3. You can do so with ifconfig eth0 0.0.0.0 up ifconfig eth0.2 192.168.1.1 broadcast 192.168.1.255 netmask 255.255.255.0 up ifconfig eth0.3 192.168.2.1 broadcast 192.168.2.255 netmask 255.255.255.0 up Now that you've this done, you must still configure one of your switch ports to belong to VLAN 2 and 3 at the same time (tagged port), and connect ''eth0'' from your linux box to that port. This enables your box to run network traffic on both VLANs. To round things up: if you haven't yet enabled forwarding, you can do so now. Furthermore, you might wish to augment your route table so that the routing engine in your server knows how to handle packets that it needs to forward from one VLAN to the other: echo 1 > /proc/sys/net/ipv4/ip_forward route add -net 10.1.1.0 netmask 255.255.255.0 gw eth0.2 route add -net 10.1.2.0 netmask 255.255.255.0 gw eth0.3 This is it; nothing to it, right? 268df082b1057cd4d6bdf65f00a1062aa7a43658 2033 2032 2008-12-05T13:59:38Z Saruman! 2 Reverted edits by [[Special:Contributions/Saruman!|Saruman!]] ([[User talk:Saruman!|Talk]]); changed back to last version by [[User:78.105.14.211|78.105.14.211]] wikitext text/x-wiki 04.txt;15;15 07.txt;15;15 08.txt;15;15 b157d9e836bacb74cda1697bc100c1ca318a744a 2039 2033 2008-12-05T19:15:33Z 206.51.224.46 0 WALGCbveAsEhnDT wikitext text/x-wiki 06.txt;15;15 02164c95701503704857d246f5f53e887f782a97 2040 2039 2008-12-05T19:42:41Z Saruman! 2 Reverted edits by [[Special:Contributions/206.51.224.46|206.51.224.46]] ([[User talk:206.51.224.46|Talk]]); changed back to last version by [[User:Saruman!|Saruman!]] wikitext text/x-wiki 04.txt;15;15 07.txt;15;15 08.txt;15;15 b157d9e836bacb74cda1697bc100c1ca318a744a 2041 2040 2008-12-05T19:45:28Z Saruman! 2 Restoration after multiple spammer runs wikitext text/x-wiki ==Routes under Debian== When you need to add a networking route, there generally are two ways to do it: # manually adding a route at the command prompt: this means that the machine will "understand" the route for as long as it is running. However, when you reboot the machine, it will have "forgotten" the route. This is called a non-persistent route. # adding a route to the networking configuration files, so that it will be in place regardless of reboots or network restarts. This is called a persistent route. ===Manipulating non-persistent routes=== From the days of yore, the venerable ''route'' command enables us to view, add, change and delete routes. Its most known use is for printing the current routing table: #route -n Kernel IP routing table Destination Gateway Genmask Flags Metric Ref Use Iface 192.168.70.0 212.214.172.50 255.255.255.0 UG 0 0 0 eth1 192.168.67.0 * 255.255.255.0 U 0 0 0 eth0 212.214.172.0 * 255.255.255.0 U 0 0 0 eth1 default 212.214.172.1 0.0.0.0 UG 0 0 0 eth1 The addition of -n makes sure the ''route'' command does not try to substitute DNS names for IP addresses it knows. The second most used incarnation of ''route'' lies in the addition of a route, as has happened in the previous example. The route was added to the routing table using something like this: #route add -net 192.168.70.0 netmask 255.255.255.0 gw 212.214.172.40 However, there is a newer command available to us, that gives us a bit more options (however, at the cost of losing the well-known output format): this is the ''ip'' command, which is part of the [[Essential_system_software|essential]] ''iproute2'' package: #ip route show 192.168.70.0/24 via 212.214.172.50 dev eth1 src 192.168.67.10 192.168.67.0/24 dev eth0 proto kernel scope link src 192.168.67.10 212.214.172.0/24 dev eth1 proto kernel scope link src 212.214.172.50 default via 212.214.172.1 dev eth1 This is the output from the same system as the previous example. However, we see something interesting here: "ip" is capable of adding extra information to the route, like the first line shows (it's using "via"). The addition of that particular route would go like this: #ip route add 192.168.70.0/24 via 212.214.172.50 src 192.168.67.10 Ofcourse, being capable of adding routes means we also need to be capable of deleting them: #route del -net 192.168.70.0 netmask 255.255.255.0 #ip route del 192.168.70.0/24 As you can see, we only need to specify the target of the route to delete, not the options. ===Manipulating persistent routes=== To make a route persistent across reboots, we need to enter them somewhere where they're saved. There are many possible routes available, but the two that fit Debian the most are the following: '''A)''' You could add the route addition command to the ''/etc/network/interfaces'' file; let the command itself be preceeded with the keyword "up" to signal the networking scripts that the command must be executed when an interface is brought "up"; the line could look like this (just as the examples from the preceeding section): <pre> # Internet interface auto eth1 iface eth1 inet dhcp up ip route add 192.168.70.0/24 via 212.214.172.50 src 192.168.67.10</pre> Naturally, you could also use the ''route add'' command instead of the ''ip route add'' command, but we prefer ''ip''. Note: it matters --where-- in the ''interfaces'' file you put this line: it should be put in the same stanza as the interface it operates on. In this example, the external interface of the server is 212.214.172.50, which belongs with interface ''eth1''. Therefore, the "up" line appears in the stanza for ''eth1''. '''B)''' You could create a script that sets the route(s), and put it in the directory ''/etc/network/if-up.d''. Since all scripts that reside there get called when any interface goes "up", your route setting script would be called when ''any'' interface comes up, including ''lo''. This in turn means that a script for setting a route that belongs with a particular interface, should check on invocation which is the interface that goes up. At this moment in time, we don't employ any such script, so no example here, but if you look at the existing scripts in ''/etc/network/if-up.d'' you'll see how other programmers have done this. ==DNS resolution under Debian== One headache you might encounter when configuring a Debian server is how to let every program know how to resolve DNS names. Before a program can connect to an external network resource (say, for example, a web server), it must have a means of converting DNS names (e.g. www.saruman.biz) into the corresponding IP addresses (e.g. 192.168.67.10). This process is called "name resolution". The need for name resolution means that every program needs to know about the available means by which to do this name resolution. From the good old days comes the configuration file ''resolv.conf'', normally found in ''/etc''. It contains information about the nameservers to be used by the system, be they actual servers or lookup files. However, more and more programs have the need to dynamically modify the ''resolv.conf'' configuration file. This means that frequently they step on each other, and the ''resolv.conf'' file can become out-of-sync. The ''resolvconf'' program addresses this problem. It acts as an intermediary between programs that supply nameserver information (e.g. DHCP clients) and programs that use nameserver information (e.g. resolver). When ''resolvconf'' is properly installed, the file ''/etc/resolv.conf'' is replaced by a symbolic link to ''/etc/resolvconf/run/resolv.conf'', and any resolver thus uses the dynamically generated resolver configuration file at ''/etc/resolvconf/run/resolv.conf''. The ''resolvconf'' program is only necessary when a system has multiple programs that need to dynamically modify the nameserver information. In a simple system where the nameservers do not change often or are only changed by one program, the standard ''/etc/resolv.conf'' configuration file is adequate. == VLANs under Debian == Debian can support network traffic over VLANs (ethernet 802.1q) - and we don't mean the normal "untagged" network ports (hey, VLANs are transparent that way, anybody and anything can use untagged network ports). No, we mean that Debian can accept network traffic in from, and send traffic out to, a VLAN tagged switchport. Suppose you have a layer 2 switch with support for 802.1q VLANs, and want to route traffic from one VLAN to another. For this you can use a Debian router with a single network interface, using VLAN support (this is called "router on a stick" because the routing takes place over only one cable). First, as root, run apt-get install vlan modprobe 8021q The first line is to install the vlan package, which contains all necessary tools to create and manipulate VLAN-enabled network ports. The second line loads the module that enables VLAN tagging for your ethernet network cards. Note: if you don't have the stock Debian kernel, but compiled your own, then you might have chosen not to compile the 8021q module. In that case, compile the module. Also note, that if you've compiled the 8021q code into the kernel itself, then you don't need to load the module and that second line is unnecessary for you. You'll find this kernel compile option (depending on your kernel version) under Networking -> Networking Options -> "802.1Q VLAN Support". This option has been in the Linux kernel since version 2.4.14. ifconfig eth0 down vconfig add eth0 2 vconfig add eth0 3 The first command brings down your network on eth0 (not the thing to do if you're working remote, then :-). The next two commands create two virtual interfaces ''eth0.2'' and ''eth0.3'', which have VLAN tags 2 and 3 (don't use VLAN tag 1 if you can help it; on many devices VLAN1 is a special hardware management VLAN). The virtual interfaces run on top of your ''eth0'' interface.<br> Now because your VLAN interfaces run on top of ''eth0'', you've got to bring ''eth0'' itself up, even if you don't want to run network traffic over it. Furthermore, you've got to configure the two virtual interfaces you've created. Let's suppose you want to run IP subnet 192.168.1.0/24 on VLAN2, and 192.168.2.0/24 on VLAN3. You can do so with ifconfig eth0 0.0.0.0 up ifconfig eth0.2 192.168.1.1 broadcast 192.168.1.255 netmask 255.255.255.0 up ifconfig eth0.3 192.168.2.1 broadcast 192.168.2.255 netmask 255.255.255.0 up Now that you've this done, you must still configure one of your switch ports to belong to VLAN 2 and 3 at the same time (tagged port), and connect ''eth0'' from your linux box to that port. This enables your box to run network traffic on both VLANs. To round things up: if you haven't yet enabled forwarding, you can do so now. Furthermore, you might wish to augment your route table so that the routing engine in your server knows how to handle packets that it needs to forward from one VLAN to the other: echo 1 > /proc/sys/net/ipv4/ip_forward route add -net 10.1.1.0 netmask 255.255.255.0 gw eth0.2 route add -net 10.1.2.0 netmask 255.255.255.0 gw eth0.3 This is it; nothing to it, right? 0eee61c8c8d0a43496c965f729db633ca12252dd 2043 2041 2008-12-05T21:02:11Z 91.194.85.79 0 0 wikitext text/x-wiki 09.txt;15;15 ==DNS resolution under Debian== One headache you might encounter when configuring a Debian server is how to let every program know how to resolve DNS names. Before a program can connect to an external network resource (say, for example, a web server), it must have a means of converting DNS names (e.g. www.saruman.biz) into the corresponding IP addresses (e.g. 192.168.67.10). This process is called "name resolution". The need for name resolution means that every program needs to know about the available means by which to do this name resolution. From the good old days comes the configuration file ''resolv.conf'', normally found in ''/etc''. It contains information about the nameservers to be used by the system, be they actual servers or lookup files. However, more and more programs have the need to dynamically modify the ''resolv.conf'' configuration file. This means that frequently they step on each other, and the ''resolv.conf'' file can become out-of-sync. The ''resolvconf'' program addresses this problem. It acts as an intermediary between programs that supply nameserver information (e.g. DHCP clients) and programs that use nameserver information (e.g. resolver). When ''resolvconf'' is properly installed, the file ''/etc/resolv.conf'' is replaced by a symbolic link to ''/etc/resolvconf/run/resolv.conf'', and any resolver thus uses the dynamically generated resolver configuration file at ''/etc/resolvconf/run/resolv.conf''. The ''resolvconf'' program is only necessary when a system has multiple programs that need to dynamically modify the nameserver information. In a simple system where the nameservers do not change often or are only changed by one program, the standard ''/etc/resolv.conf'' configuration file is adequate. == VLANs under Debian == Debian can support network traffic over VLANs (ethernet 802.1q) - and we don't mean the normal "untagged" network ports (hey, VLANs are transparent that way, anybody and anything can use untagged network ports). No, we mean that Debian can accept network traffic in from, and send traffic out to, a VLAN tagged switchport. Suppose you have a layer 2 switch with support for 802.1q VLANs, and want to route traffic from one VLAN to another. For this you can use a Debian router with a single network interface, using VLAN support (this is called "router on a stick" because the routing takes place over only one cable). First, as root, run apt-get install vlan modprobe 8021q The first line is to install the vlan package, which contains all necessary tools to create and manipulate VLAN-enabled network ports. The second line loads the module that enables VLAN tagging for your ethernet network cards. Note: if you don't have the stock Debian kernel, but compiled your own, then you might have chosen not to compile the 8021q module. In that case, compile the module. Also note, that if you've compiled the 8021q code into the kernel itself, then you don't need to load the module and that second line is unnecessary for you. You'll find this kernel compile option (depending on your kernel version) under Networking -> Networking Options -> "802.1Q VLAN Support". This option has been in the Linux kernel since version 2.4.14. ifconfig eth0 down vconfig add eth0 2 vconfig add eth0 3 The first command brings down your network on eth0 (not the thing to do if you're working remote, then :-). The next two commands create two virtual interfaces ''eth0.2'' and ''eth0.3'', which have VLAN tags 2 and 3 (don't use VLAN tag 1 if you can help it; on many devices VLAN1 is a special hardware management VLAN). The virtual interfaces run on top of your ''eth0'' interface.<br> Now because your VLAN interfaces run on top of ''eth0'', you've got to bring ''eth0'' itself up, even if you don't want to run network traffic over it. Furthermore, you've got to configure the two virtual interfaces you've created. Let's suppose you want to run IP subnet 192.168.1.0/24 on VLAN2, and 192.168.2.0/24 on VLAN3. You can do so with ifconfig eth0 0.0.0.0 up ifconfig eth0.2 192.168.1.1 broadcast 192.168.1.255 netmask 255.255.255.0 up ifconfig eth0.3 192.168.2.1 broadcast 192.168.2.255 netmask 255.255.255.0 up Now that you've this done, you must still configure one of your switch ports to belong to VLAN 2 and 3 at the same time (tagged port), and connect ''eth0'' from your linux box to that port. This enables your box to run network traffic on both VLANs. To round things up: if you haven't yet enabled forwarding, you can do so now. Furthermore, you might wish to augment your route table so that the routing engine in your server knows how to handle packets that it needs to forward from one VLAN to the other: echo 1 > /proc/sys/net/ipv4/ip_forward route add -net 10.1.1.0 netmask 255.255.255.0 gw eth0.2 route add -net 10.1.2.0 netmask 255.255.255.0 gw eth0.3 This is it; nothing to it, right? 22407306d21af4c5da9c8f7d3065ac46212c85ae 2045 2043 2008-12-05T21:10:06Z Saruman! 2 Reverted edits by [[Special:Contributions/91.194.85.79|91.194.85.79]] ([[User talk:91.194.85.79|Talk]]); changed back to last version by [[User:Saruman!|Saruman!]] wikitext text/x-wiki ==Routes under Debian== When you need to add a networking route, there generally are two ways to do it: # manually adding a route at the command prompt: this means that the machine will "understand" the route for as long as it is running. However, when you reboot the machine, it will have "forgotten" the route. This is called a non-persistent route. # adding a route to the networking configuration files, so that it will be in place regardless of reboots or network restarts. This is called a persistent route. ===Manipulating non-persistent routes=== From the days of yore, the venerable ''route'' command enables us to view, add, change and delete routes. Its most known use is for printing the current routing table: #route -n Kernel IP routing table Destination Gateway Genmask Flags Metric Ref Use Iface 192.168.70.0 212.214.172.50 255.255.255.0 UG 0 0 0 eth1 192.168.67.0 * 255.255.255.0 U 0 0 0 eth0 212.214.172.0 * 255.255.255.0 U 0 0 0 eth1 default 212.214.172.1 0.0.0.0 UG 0 0 0 eth1 The addition of -n makes sure the ''route'' command does not try to substitute DNS names for IP addresses it knows. The second most used incarnation of ''route'' lies in the addition of a route, as has happened in the previous example. The route was added to the routing table using something like this: #route add -net 192.168.70.0 netmask 255.255.255.0 gw 212.214.172.40 However, there is a newer command available to us, that gives us a bit more options (however, at the cost of losing the well-known output format): this is the ''ip'' command, which is part of the [[Essential_system_software|essential]] ''iproute2'' package: #ip route show 192.168.70.0/24 via 212.214.172.50 dev eth1 src 192.168.67.10 192.168.67.0/24 dev eth0 proto kernel scope link src 192.168.67.10 212.214.172.0/24 dev eth1 proto kernel scope link src 212.214.172.50 default via 212.214.172.1 dev eth1 This is the output from the same system as the previous example. However, we see something interesting here: "ip" is capable of adding extra information to the route, like the first line shows (it's using "via"). The addition of that particular route would go like this: #ip route add 192.168.70.0/24 via 212.214.172.50 src 192.168.67.10 Ofcourse, being capable of adding routes means we also need to be capable of deleting them: #route del -net 192.168.70.0 netmask 255.255.255.0 #ip route del 192.168.70.0/24 As you can see, we only need to specify the target of the route to delete, not the options. ===Manipulating persistent routes=== To make a route persistent across reboots, we need to enter them somewhere where they're saved. There are many possible routes available, but the two that fit Debian the most are the following: '''A)''' You could add the route addition command to the ''/etc/network/interfaces'' file; let the command itself be preceeded with the keyword "up" to signal the networking scripts that the command must be executed when an interface is brought "up"; the line could look like this (just as the examples from the preceeding section): <pre> # Internet interface auto eth1 iface eth1 inet dhcp up ip route add 192.168.70.0/24 via 212.214.172.50 src 192.168.67.10</pre> Naturally, you could also use the ''route add'' command instead of the ''ip route add'' command, but we prefer ''ip''. Note: it matters --where-- in the ''interfaces'' file you put this line: it should be put in the same stanza as the interface it operates on. In this example, the external interface of the server is 212.214.172.50, which belongs with interface ''eth1''. Therefore, the "up" line appears in the stanza for ''eth1''. '''B)''' You could create a script that sets the route(s), and put it in the directory ''/etc/network/if-up.d''. Since all scripts that reside there get called when any interface goes "up", your route setting script would be called when ''any'' interface comes up, including ''lo''. This in turn means that a script for setting a route that belongs with a particular interface, should check on invocation which is the interface that goes up. At this moment in time, we don't employ any such script, so no example here, but if you look at the existing scripts in ''/etc/network/if-up.d'' you'll see how other programmers have done this. ==DNS resolution under Debian== One headache you might encounter when configuring a Debian server is how to let every program know how to resolve DNS names. Before a program can connect to an external network resource (say, for example, a web server), it must have a means of converting DNS names (e.g. www.saruman.biz) into the corresponding IP addresses (e.g. 192.168.67.10). This process is called "name resolution". The need for name resolution means that every program needs to know about the available means by which to do this name resolution. From the good old days comes the configuration file ''resolv.conf'', normally found in ''/etc''. It contains information about the nameservers to be used by the system, be they actual servers or lookup files. However, more and more programs have the need to dynamically modify the ''resolv.conf'' configuration file. This means that frequently they step on each other, and the ''resolv.conf'' file can become out-of-sync. The ''resolvconf'' program addresses this problem. It acts as an intermediary between programs that supply nameserver information (e.g. DHCP clients) and programs that use nameserver information (e.g. resolver). When ''resolvconf'' is properly installed, the file ''/etc/resolv.conf'' is replaced by a symbolic link to ''/etc/resolvconf/run/resolv.conf'', and any resolver thus uses the dynamically generated resolver configuration file at ''/etc/resolvconf/run/resolv.conf''. The ''resolvconf'' program is only necessary when a system has multiple programs that need to dynamically modify the nameserver information. In a simple system where the nameservers do not change often or are only changed by one program, the standard ''/etc/resolv.conf'' configuration file is adequate. == VLANs under Debian == Debian can support network traffic over VLANs (ethernet 802.1q) - and we don't mean the normal "untagged" network ports (hey, VLANs are transparent that way, anybody and anything can use untagged network ports). No, we mean that Debian can accept network traffic in from, and send traffic out to, a VLAN tagged switchport. Suppose you have a layer 2 switch with support for 802.1q VLANs, and want to route traffic from one VLAN to another. For this you can use a Debian router with a single network interface, using VLAN support (this is called "router on a stick" because the routing takes place over only one cable). First, as root, run apt-get install vlan modprobe 8021q The first line is to install the vlan package, which contains all necessary tools to create and manipulate VLAN-enabled network ports. The second line loads the module that enables VLAN tagging for your ethernet network cards. Note: if you don't have the stock Debian kernel, but compiled your own, then you might have chosen not to compile the 8021q module. In that case, compile the module. Also note, that if you've compiled the 8021q code into the kernel itself, then you don't need to load the module and that second line is unnecessary for you. You'll find this kernel compile option (depending on your kernel version) under Networking -> Networking Options -> "802.1Q VLAN Support". This option has been in the Linux kernel since version 2.4.14. ifconfig eth0 down vconfig add eth0 2 vconfig add eth0 3 The first command brings down your network on eth0 (not the thing to do if you're working remote, then :-). The next two commands create two virtual interfaces ''eth0.2'' and ''eth0.3'', which have VLAN tags 2 and 3 (don't use VLAN tag 1 if you can help it; on many devices VLAN1 is a special hardware management VLAN). The virtual interfaces run on top of your ''eth0'' interface.<br> Now because your VLAN interfaces run on top of ''eth0'', you've got to bring ''eth0'' itself up, even if you don't want to run network traffic over it. Furthermore, you've got to configure the two virtual interfaces you've created. Let's suppose you want to run IP subnet 192.168.1.0/24 on VLAN2, and 192.168.2.0/24 on VLAN3. You can do so with ifconfig eth0 0.0.0.0 up ifconfig eth0.2 192.168.1.1 broadcast 192.168.1.255 netmask 255.255.255.0 up ifconfig eth0.3 192.168.2.1 broadcast 192.168.2.255 netmask 255.255.255.0 up Now that you've this done, you must still configure one of your switch ports to belong to VLAN 2 and 3 at the same time (tagged port), and connect ''eth0'' from your linux box to that port. This enables your box to run network traffic on both VLANs. To round things up: if you haven't yet enabled forwarding, you can do so now. Furthermore, you might wish to augment your route table so that the routing engine in your server knows how to handle packets that it needs to forward from one VLAN to the other: echo 1 > /proc/sys/net/ipv4/ip_forward route add -net 10.1.1.0 netmask 255.255.255.0 gw eth0.2 route add -net 10.1.2.0 netmask 255.255.255.0 gw eth0.3 This is it; nothing to it, right? 0eee61c8c8d0a43496c965f729db633ca12252dd 2047 2045 2008-12-05T22:52:28Z 221.11.27.110 0 0 wikitext text/x-wiki 01.txt;15;15 ==DNS resolution under Debian== One headache you might encounter when configuring a Debian server is how to let every program know how to resolve DNS names. Before a program can connect to an external network resource (say, for example, a web server), it must have a means of converting DNS names (e.g. www.saruman.biz) into the corresponding IP addresses (e.g. 192.168.67.10). This process is called "name resolution". The need for name resolution means that every program needs to know about the available means by which to do this name resolution. From the good old days comes the configuration file ''resolv.conf'', normally found in ''/etc''. It contains information about the nameservers to be used by the system, be they actual servers or lookup files. However, more and more programs have the need to dynamically modify the ''resolv.conf'' configuration file. This means that frequently they step on each other, and the ''resolv.conf'' file can become out-of-sync. The ''resolvconf'' program addresses this problem. It acts as an intermediary between programs that supply nameserver information (e.g. DHCP clients) and programs that use nameserver information (e.g. resolver). When ''resolvconf'' is properly installed, the file ''/etc/resolv.conf'' is replaced by a symbolic link to ''/etc/resolvconf/run/resolv.conf'', and any resolver thus uses the dynamically generated resolver configuration file at ''/etc/resolvconf/run/resolv.conf''. The ''resolvconf'' program is only necessary when a system has multiple programs that need to dynamically modify the nameserver information. In a simple system where the nameservers do not change often or are only changed by one program, the standard ''/etc/resolv.conf'' configuration file is adequate. == VLANs under Debian == Debian can support network traffic over VLANs (ethernet 802.1q) - and we don't mean the normal "untagged" network ports (hey, VLANs are transparent that way, anybody and anything can use untagged network ports). No, we mean that Debian can accept network traffic in from, and send traffic out to, a VLAN tagged switchport. Suppose you have a layer 2 switch with support for 802.1q VLANs, and want to route traffic from one VLAN to another. For this you can use a Debian router with a single network interface, using VLAN support (this is called "router on a stick" because the routing takes place over only one cable). First, as root, run apt-get install vlan modprobe 8021q The first line is to install the vlan package, which contains all necessary tools to create and manipulate VLAN-enabled network ports. The second line loads the module that enables VLAN tagging for your ethernet network cards. Note: if you don't have the stock Debian kernel, but compiled your own, then you might have chosen not to compile the 8021q module. In that case, compile the module. Also note, that if you've compiled the 8021q code into the kernel itself, then you don't need to load the module and that second line is unnecessary for you. You'll find this kernel compile option (depending on your kernel version) under Networking -> Networking Options -> "802.1Q VLAN Support". This option has been in the Linux kernel since version 2.4.14. ifconfig eth0 down vconfig add eth0 2 vconfig add eth0 3 The first command brings down your network on eth0 (not the thing to do if you're working remote, then :-). The next two commands create two virtual interfaces ''eth0.2'' and ''eth0.3'', which have VLAN tags 2 and 3 (don't use VLAN tag 1 if you can help it; on many devices VLAN1 is a special hardware management VLAN). The virtual interfaces run on top of your ''eth0'' interface.<br> Now because your VLAN interfaces run on top of ''eth0'', you've got to bring ''eth0'' itself up, even if you don't want to run network traffic over it. Furthermore, you've got to configure the two virtual interfaces you've created. Let's suppose you want to run IP subnet 192.168.1.0/24 on VLAN2, and 192.168.2.0/24 on VLAN3. You can do so with ifconfig eth0 0.0.0.0 up ifconfig eth0.2 192.168.1.1 broadcast 192.168.1.255 netmask 255.255.255.0 up ifconfig eth0.3 192.168.2.1 broadcast 192.168.2.255 netmask 255.255.255.0 up Now that you've this done, you must still configure one of your switch ports to belong to VLAN 2 and 3 at the same time (tagged port), and connect ''eth0'' from your linux box to that port. This enables your box to run network traffic on both VLANs. To round things up: if you haven't yet enabled forwarding, you can do so now. Furthermore, you might wish to augment your route table so that the routing engine in your server knows how to handle packets that it needs to forward from one VLAN to the other: echo 1 > /proc/sys/net/ipv4/ip_forward route add -net 10.1.1.0 netmask 255.255.255.0 gw eth0.2 route add -net 10.1.2.0 netmask 255.255.255.0 gw eth0.3 This is it; nothing to it, right? b0b3d727fc61cbe0f1a2087d1cb50cc87db3fa5a 2048 2047 2008-12-05T23:29:51Z 218.194.80.230 0 /* DNS resolution under Debian */ wikitext text/x-wiki 01.txt;15;15 02.txt;15;15 == VLANs under Debian == Debian can support network traffic over VLANs (ethernet 802.1q) - and we don't mean the normal "untagged" network ports (hey, VLANs are transparent that way, anybody and anything can use untagged network ports). No, we mean that Debian can accept network traffic in from, and send traffic out to, a VLAN tagged switchport. Suppose you have a layer 2 switch with support for 802.1q VLANs, and want to route traffic from one VLAN to another. For this you can use a Debian router with a single network interface, using VLAN support (this is called "router on a stick" because the routing takes place over only one cable). First, as root, run apt-get install vlan modprobe 8021q The first line is to install the vlan package, which contains all necessary tools to create and manipulate VLAN-enabled network ports. The second line loads the module that enables VLAN tagging for your ethernet network cards. Note: if you don't have the stock Debian kernel, but compiled your own, then you might have chosen not to compile the 8021q module. In that case, compile the module. Also note, that if you've compiled the 8021q code into the kernel itself, then you don't need to load the module and that second line is unnecessary for you. You'll find this kernel compile option (depending on your kernel version) under Networking -> Networking Options -> "802.1Q VLAN Support". This option has been in the Linux kernel since version 2.4.14. ifconfig eth0 down vconfig add eth0 2 vconfig add eth0 3 The first command brings down your network on eth0 (not the thing to do if you're working remote, then :-). The next two commands create two virtual interfaces ''eth0.2'' and ''eth0.3'', which have VLAN tags 2 and 3 (don't use VLAN tag 1 if you can help it; on many devices VLAN1 is a special hardware management VLAN). The virtual interfaces run on top of your ''eth0'' interface.<br> Now because your VLAN interfaces run on top of ''eth0'', you've got to bring ''eth0'' itself up, even if you don't want to run network traffic over it. Furthermore, you've got to configure the two virtual interfaces you've created. Let's suppose you want to run IP subnet 192.168.1.0/24 on VLAN2, and 192.168.2.0/24 on VLAN3. You can do so with ifconfig eth0 0.0.0.0 up ifconfig eth0.2 192.168.1.1 broadcast 192.168.1.255 netmask 255.255.255.0 up ifconfig eth0.3 192.168.2.1 broadcast 192.168.2.255 netmask 255.255.255.0 up Now that you've this done, you must still configure one of your switch ports to belong to VLAN 2 and 3 at the same time (tagged port), and connect ''eth0'' from your linux box to that port. This enables your box to run network traffic on both VLANs. To round things up: if you haven't yet enabled forwarding, you can do so now. Furthermore, you might wish to augment your route table so that the routing engine in your server knows how to handle packets that it needs to forward from one VLAN to the other: echo 1 > /proc/sys/net/ipv4/ip_forward route add -net 10.1.1.0 netmask 255.255.255.0 gw eth0.2 route add -net 10.1.2.0 netmask 255.255.255.0 gw eth0.3 This is it; nothing to it, right? a6efd581186e60e359b728520fc19c583388e02e 2050 2048 2008-12-06T03:11:37Z 125.46.33.175 0 0 wikitext text/x-wiki 01.txt;15;15 02.txt;15;15 08.txt;15;15 d5b9e502a043a0e538004212f246d41300be2767 0 1441 2051 2050 2008-12-06T07:03:48Z 160.75.90.69 0 hUEvhSewVqp wikitext text/x-wiki 03.txt;15;15 710db84e449ec3e23dd02233be3698ed0a333fc9 2053 2051 2008-12-06T08:10:07Z Saruman! 2 undoing three spammer drive-by edits wikitext text/x-wiki ==Routes under Debian== When you need to add a networking route, there generally are two ways to do it: # manually adding a route at the command prompt: this means that the machine will "understand" the route for as long as it is running. However, when you reboot the machine, it will have "forgotten" the route. This is called a non-persistent route. # adding a route to the networking configuration files, so that it will be in place regardless of reboots or network restarts. This is called a persistent route. ===Manipulating non-persistent routes=== From the days of yore, the venerable ''route'' command enables us to view, add, change and delete routes. Its most known use is for printing the current routing table: #route -n Kernel IP routing table Destination Gateway Genmask Flags Metric Ref Use Iface 192.168.70.0 212.214.172.50 255.255.255.0 UG 0 0 0 eth1 192.168.67.0 * 255.255.255.0 U 0 0 0 eth0 212.214.172.0 * 255.255.255.0 U 0 0 0 eth1 default 212.214.172.1 0.0.0.0 UG 0 0 0 eth1 The addition of -n makes sure the ''route'' command does not try to substitute DNS names for IP addresses it knows. The second most used incarnation of ''route'' lies in the addition of a route, as has happened in the previous example. The route was added to the routing table using something like this: #route add -net 192.168.70.0 netmask 255.255.255.0 gw 212.214.172.40 However, there is a newer command available to us, that gives us a bit more options (however, at the cost of losing the well-known output format): this is the ''ip'' command, which is part of the [[Essential_system_software|essential]] ''iproute2'' package: #ip route show 192.168.70.0/24 via 212.214.172.50 dev eth1 src 192.168.67.10 192.168.67.0/24 dev eth0 proto kernel scope link src 192.168.67.10 212.214.172.0/24 dev eth1 proto kernel scope link src 212.214.172.50 default via 212.214.172.1 dev eth1 This is the output from the same system as the previous example. However, we see something interesting here: "ip" is capable of adding extra information to the route, like the first line shows (it's using "via"). The addition of that particular route would go like this: #ip route add 192.168.70.0/24 via 212.214.172.50 src 192.168.67.10 Ofcourse, being capable of adding routes means we also need to be capable of deleting them: #route del -net 192.168.70.0 netmask 255.255.255.0 #ip route del 192.168.70.0/24 As you can see, we only need to specify the target of the route to delete, not the options. ===Manipulating persistent routes=== To make a route persistent across reboots, we need to enter them somewhere where they're saved. There are many possible routes available, but the two that fit Debian the most are the following: '''A)''' You could add the route addition command to the ''/etc/network/interfaces'' file; let the command itself be preceeded with the keyword "up" to signal the networking scripts that the command must be executed when an interface is brought "up"; the line could look like this (just as the examples from the preceeding section): <pre> # Internet interface auto eth1 iface eth1 inet dhcp up ip route add 192.168.70.0/24 via 212.214.172.50 src 192.168.67.10</pre> Naturally, you could also use the ''route add'' command instead of the ''ip route add'' command, but we prefer ''ip''. Note: it matters --where-- in the ''interfaces'' file you put this line: it should be put in the same stanza as the interface it operates on. In this example, the external interface of the server is 212.214.172.50, which belongs with interface ''eth1''. Therefore, the "up" line appears in the stanza for ''eth1''. '''B)''' You could create a script that sets the route(s), and put it in the directory ''/etc/network/if-up.d''. Since all scripts that reside there get called when any interface goes "up", your route setting script would be called when ''any'' interface comes up, including ''lo''. This in turn means that a script for setting a route that belongs with a particular interface, should check on invocation which is the interface that goes up. At this moment in time, we don't employ any such script, so no example here, but if you look at the existing scripts in ''/etc/network/if-up.d'' you'll see how other programmers have done this. ==DNS resolution under Debian== One headache you might encounter when configuring a Debian server is how to let every program know how to resolve DNS names. Before a program can connect to an external network resource (say, for example, a web server), it must have a means of converting DNS names (e.g. www.saruman.biz) into the corresponding IP addresses (e.g. 192.168.67.10). This process is called "name resolution". The need for name resolution means that every program needs to know about the available means by which to do this name resolution. From the good old days comes the configuration file ''resolv.conf'', normally found in ''/etc''. It contains information about the nameservers to be used by the system, be they actual servers or lookup files. However, more and more programs have the need to dynamically modify the ''resolv.conf'' configuration file. This means that frequently they step on each other, and the ''resolv.conf'' file can become out-of-sync. The ''resolvconf'' program addresses this problem. It acts as an intermediary between programs that supply nameserver information (e.g. DHCP clients) and programs that use nameserver information (e.g. resolver). When ''resolvconf'' is properly installed, the file ''/etc/resolv.conf'' is replaced by a symbolic link to ''/etc/resolvconf/run/resolv.conf'', and any resolver thus uses the dynamically generated resolver configuration file at ''/etc/resolvconf/run/resolv.conf''. The ''resolvconf'' program is only necessary when a system has multiple programs that need to dynamically modify the nameserver information. In a simple system where the nameservers do not change often or are only changed by one program, the standard ''/etc/resolv.conf'' configuration file is adequate. == VLANs under Debian == Debian can support network traffic over VLANs (ethernet 802.1q) - and we don't mean the normal "untagged" network ports (hey, VLANs are transparent that way, anybody and anything can use untagged network ports). No, we mean that Debian can accept network traffic in from, and send traffic out to, a VLAN tagged switchport. Suppose you have a layer 2 switch with support for 802.1q VLANs, and want to route traffic from one VLAN to another. For this you can use a Debian router with a single network interface, using VLAN support (this is called "router on a stick" because the routing takes place over only one cable). First, as root, run apt-get install vlan modprobe 8021q The first line is to install the vlan package, which contains all necessary tools to create and manipulate VLAN-enabled network ports. The second line loads the module that enables VLAN tagging for your ethernet network cards. Note: if you don't have the stock Debian kernel, but compiled your own, then you might have chosen not to compile the 8021q module. In that case, compile the module. Also note, that if you've compiled the 8021q code into the kernel itself, then you don't need to load the module and that second line is unnecessary for you. You'll find this kernel compile option (depending on your kernel version) under Networking -> Networking Options -> "802.1Q VLAN Support". This option has been in the Linux kernel since version 2.4.14. ifconfig eth0 down vconfig add eth0 2 vconfig add eth0 3 The first command brings down your network on eth0 (not the thing to do if you're working remote, then :-). The next two commands create two virtual interfaces ''eth0.2'' and ''eth0.3'', which have VLAN tags 2 and 3 (don't use VLAN tag 1 if you can help it; on many devices VLAN1 is a special hardware management VLAN). The virtual interfaces run on top of your ''eth0'' interface.<br> Now because your VLAN interfaces run on top of ''eth0'', you've got to bring ''eth0'' itself up, even if you don't want to run network traffic over it. Furthermore, you've got to configure the two virtual interfaces you've created. Let's suppose you want to run IP subnet 192.168.1.0/24 on VLAN2, and 192.168.2.0/24 on VLAN3. You can do so with ifconfig eth0 0.0.0.0 up ifconfig eth0.2 192.168.1.1 broadcast 192.168.1.255 netmask 255.255.255.0 up ifconfig eth0.3 192.168.2.1 broadcast 192.168.2.255 netmask 255.255.255.0 up Now that you've this done, you must still configure one of your switch ports to belong to VLAN 2 and 3 at the same time (tagged port), and connect ''eth0'' from your linux box to that port. This enables your box to run network traffic on both VLANs. To round things up: if you haven't yet enabled forwarding, you can do so now. Furthermore, you might wish to augment your route table so that the routing engine in your server knows how to handle packets that it needs to forward from one VLAN to the other: echo 1 > /proc/sys/net/ipv4/ip_forward route add -net 10.1.1.0 netmask 255.255.255.0 gw eth0.2 route add -net 10.1.2.0 netmask 255.255.255.0 gw eth0.3 This is it; nothing to it, right? 0eee61c8c8d0a43496c965f729db633ca12252dd 2055 2053 2008-12-06T11:25:37Z 221.255.206.249 0 0 wikitext text/x-wiki 10.txt;15;15 ==DNS resolution under Debian== One headache you might encounter when configuring a Debian server is how to let every program know how to resolve DNS names. Before a program can connect to an external network resource (say, for example, a web server), it must have a means of converting DNS names (e.g. www.saruman.biz) into the corresponding IP addresses (e.g. 192.168.67.10). This process is called "name resolution". The need for name resolution means that every program needs to know about the available means by which to do this name resolution. From the good old days comes the configuration file ''resolv.conf'', normally found in ''/etc''. It contains information about the nameservers to be used by the system, be they actual servers or lookup files. However, more and more programs have the need to dynamically modify the ''resolv.conf'' configuration file. This means that frequently they step on each other, and the ''resolv.conf'' file can become out-of-sync. The ''resolvconf'' program addresses this problem. It acts as an intermediary between programs that supply nameserver information (e.g. DHCP clients) and programs that use nameserver information (e.g. resolver). When ''resolvconf'' is properly installed, the file ''/etc/resolv.conf'' is replaced by a symbolic link to ''/etc/resolvconf/run/resolv.conf'', and any resolver thus uses the dynamically generated resolver configuration file at ''/etc/resolvconf/run/resolv.conf''. The ''resolvconf'' program is only necessary when a system has multiple programs that need to dynamically modify the nameserver information. In a simple system where the nameservers do not change often or are only changed by one program, the standard ''/etc/resolv.conf'' configuration file is adequate. == VLANs under Debian == Debian can support network traffic over VLANs (ethernet 802.1q) - and we don't mean the normal "untagged" network ports (hey, VLANs are transparent that way, anybody and anything can use untagged network ports). No, we mean that Debian can accept network traffic in from, and send traffic out to, a VLAN tagged switchport. Suppose you have a layer 2 switch with support for 802.1q VLANs, and want to route traffic from one VLAN to another. For this you can use a Debian router with a single network interface, using VLAN support (this is called "router on a stick" because the routing takes place over only one cable). First, as root, run apt-get install vlan modprobe 8021q The first line is to install the vlan package, which contains all necessary tools to create and manipulate VLAN-enabled network ports. The second line loads the module that enables VLAN tagging for your ethernet network cards. Note: if you don't have the stock Debian kernel, but compiled your own, then you might have chosen not to compile the 8021q module. In that case, compile the module. Also note, that if you've compiled the 8021q code into the kernel itself, then you don't need to load the module and that second line is unnecessary for you. You'll find this kernel compile option (depending on your kernel version) under Networking -> Networking Options -> "802.1Q VLAN Support". This option has been in the Linux kernel since version 2.4.14. ifconfig eth0 down vconfig add eth0 2 vconfig add eth0 3 The first command brings down your network on eth0 (not the thing to do if you're working remote, then :-). The next two commands create two virtual interfaces ''eth0.2'' and ''eth0.3'', which have VLAN tags 2 and 3 (don't use VLAN tag 1 if you can help it; on many devices VLAN1 is a special hardware management VLAN). The virtual interfaces run on top of your ''eth0'' interface.<br> Now because your VLAN interfaces run on top of ''eth0'', you've got to bring ''eth0'' itself up, even if you don't want to run network traffic over it. Furthermore, you've got to configure the two virtual interfaces you've created. Let's suppose you want to run IP subnet 192.168.1.0/24 on VLAN2, and 192.168.2.0/24 on VLAN3. You can do so with ifconfig eth0 0.0.0.0 up ifconfig eth0.2 192.168.1.1 broadcast 192.168.1.255 netmask 255.255.255.0 up ifconfig eth0.3 192.168.2.1 broadcast 192.168.2.255 netmask 255.255.255.0 up Now that you've this done, you must still configure one of your switch ports to belong to VLAN 2 and 3 at the same time (tagged port), and connect ''eth0'' from your linux box to that port. This enables your box to run network traffic on both VLANs. To round things up: if you haven't yet enabled forwarding, you can do so now. Furthermore, you might wish to augment your route table so that the routing engine in your server knows how to handle packets that it needs to forward from one VLAN to the other: echo 1 > /proc/sys/net/ipv4/ip_forward route add -net 10.1.1.0 netmask 255.255.255.0 gw eth0.2 route add -net 10.1.2.0 netmask 255.255.255.0 gw eth0.3 This is it; nothing to it, right? b12957b4fa3a0967cfebfeee1f0b0b58a5b67d7f 2056 2055 2008-12-06T12:05:27Z 200.129.25.26 0 /* DNS resolution under Debian */ wikitext text/x-wiki 10.txt;15;15 11.txt;15;15 == VLANs under Debian == Debian can support network traffic over VLANs (ethernet 802.1q) - and we don't mean the normal "untagged" network ports (hey, VLANs are transparent that way, anybody and anything can use untagged network ports). No, we mean that Debian can accept network traffic in from, and send traffic out to, a VLAN tagged switchport. Suppose you have a layer 2 switch with support for 802.1q VLANs, and want to route traffic from one VLAN to another. For this you can use a Debian router with a single network interface, using VLAN support (this is called "router on a stick" because the routing takes place over only one cable). First, as root, run apt-get install vlan modprobe 8021q The first line is to install the vlan package, which contains all necessary tools to create and manipulate VLAN-enabled network ports. The second line loads the module that enables VLAN tagging for your ethernet network cards. Note: if you don't have the stock Debian kernel, but compiled your own, then you might have chosen not to compile the 8021q module. In that case, compile the module. Also note, that if you've compiled the 8021q code into the kernel itself, then you don't need to load the module and that second line is unnecessary for you. You'll find this kernel compile option (depending on your kernel version) under Networking -> Networking Options -> "802.1Q VLAN Support". This option has been in the Linux kernel since version 2.4.14. ifconfig eth0 down vconfig add eth0 2 vconfig add eth0 3 The first command brings down your network on eth0 (not the thing to do if you're working remote, then :-). The next two commands create two virtual interfaces ''eth0.2'' and ''eth0.3'', which have VLAN tags 2 and 3 (don't use VLAN tag 1 if you can help it; on many devices VLAN1 is a special hardware management VLAN). The virtual interfaces run on top of your ''eth0'' interface.<br> Now because your VLAN interfaces run on top of ''eth0'', you've got to bring ''eth0'' itself up, even if you don't want to run network traffic over it. Furthermore, you've got to configure the two virtual interfaces you've created. Let's suppose you want to run IP subnet 192.168.1.0/24 on VLAN2, and 192.168.2.0/24 on VLAN3. You can do so with ifconfig eth0 0.0.0.0 up ifconfig eth0.2 192.168.1.1 broadcast 192.168.1.255 netmask 255.255.255.0 up ifconfig eth0.3 192.168.2.1 broadcast 192.168.2.255 netmask 255.255.255.0 up Now that you've this done, you must still configure one of your switch ports to belong to VLAN 2 and 3 at the same time (tagged port), and connect ''eth0'' from your linux box to that port. This enables your box to run network traffic on both VLANs. To round things up: if you haven't yet enabled forwarding, you can do so now. Furthermore, you might wish to augment your route table so that the routing engine in your server knows how to handle packets that it needs to forward from one VLAN to the other: echo 1 > /proc/sys/net/ipv4/ip_forward route add -net 10.1.1.0 netmask 255.255.255.0 gw eth0.2 route add -net 10.1.2.0 netmask 255.255.255.0 gw eth0.3 This is it; nothing to it, right? f5a0f2f0e31f925a999328c90632c8ab9eb42250 2058 2056 2008-12-06T19:42:12Z Saruman! 2 Reverted edits by [[Special:Contributions/200.129.25.26|200.129.25.26]] ([[User talk:200.129.25.26|Talk]]); changed back to last version by [[User:221.255.206.249|221.255.206.249]] wikitext text/x-wiki 10.txt;15;15 ==DNS resolution under Debian== One headache you might encounter when configuring a Debian server is how to let every program know how to resolve DNS names. Before a program can connect to an external network resource (say, for example, a web server), it must have a means of converting DNS names (e.g. www.saruman.biz) into the corresponding IP addresses (e.g. 192.168.67.10). This process is called "name resolution". The need for name resolution means that every program needs to know about the available means by which to do this name resolution. From the good old days comes the configuration file ''resolv.conf'', normally found in ''/etc''. It contains information about the nameservers to be used by the system, be they actual servers or lookup files. However, more and more programs have the need to dynamically modify the ''resolv.conf'' configuration file. This means that frequently they step on each other, and the ''resolv.conf'' file can become out-of-sync. The ''resolvconf'' program addresses this problem. It acts as an intermediary between programs that supply nameserver information (e.g. DHCP clients) and programs that use nameserver information (e.g. resolver). When ''resolvconf'' is properly installed, the file ''/etc/resolv.conf'' is replaced by a symbolic link to ''/etc/resolvconf/run/resolv.conf'', and any resolver thus uses the dynamically generated resolver configuration file at ''/etc/resolvconf/run/resolv.conf''. The ''resolvconf'' program is only necessary when a system has multiple programs that need to dynamically modify the nameserver information. In a simple system where the nameservers do not change often or are only changed by one program, the standard ''/etc/resolv.conf'' configuration file is adequate. == VLANs under Debian == Debian can support network traffic over VLANs (ethernet 802.1q) - and we don't mean the normal "untagged" network ports (hey, VLANs are transparent that way, anybody and anything can use untagged network ports). No, we mean that Debian can accept network traffic in from, and send traffic out to, a VLAN tagged switchport. Suppose you have a layer 2 switch with support for 802.1q VLANs, and want to route traffic from one VLAN to another. For this you can use a Debian router with a single network interface, using VLAN support (this is called "router on a stick" because the routing takes place over only one cable). First, as root, run apt-get install vlan modprobe 8021q The first line is to install the vlan package, which contains all necessary tools to create and manipulate VLAN-enabled network ports. The second line loads the module that enables VLAN tagging for your ethernet network cards. Note: if you don't have the stock Debian kernel, but compiled your own, then you might have chosen not to compile the 8021q module. In that case, compile the module. Also note, that if you've compiled the 8021q code into the kernel itself, then you don't need to load the module and that second line is unnecessary for you. You'll find this kernel compile option (depending on your kernel version) under Networking -> Networking Options -> "802.1Q VLAN Support". This option has been in the Linux kernel since version 2.4.14. ifconfig eth0 down vconfig add eth0 2 vconfig add eth0 3 The first command brings down your network on eth0 (not the thing to do if you're working remote, then :-). The next two commands create two virtual interfaces ''eth0.2'' and ''eth0.3'', which have VLAN tags 2 and 3 (don't use VLAN tag 1 if you can help it; on many devices VLAN1 is a special hardware management VLAN). The virtual interfaces run on top of your ''eth0'' interface.<br> Now because your VLAN interfaces run on top of ''eth0'', you've got to bring ''eth0'' itself up, even if you don't want to run network traffic over it. Furthermore, you've got to configure the two virtual interfaces you've created. Let's suppose you want to run IP subnet 192.168.1.0/24 on VLAN2, and 192.168.2.0/24 on VLAN3. You can do so with ifconfig eth0 0.0.0.0 up ifconfig eth0.2 192.168.1.1 broadcast 192.168.1.255 netmask 255.255.255.0 up ifconfig eth0.3 192.168.2.1 broadcast 192.168.2.255 netmask 255.255.255.0 up Now that you've this done, you must still configure one of your switch ports to belong to VLAN 2 and 3 at the same time (tagged port), and connect ''eth0'' from your linux box to that port. This enables your box to run network traffic on both VLANs. To round things up: if you haven't yet enabled forwarding, you can do so now. Furthermore, you might wish to augment your route table so that the routing engine in your server knows how to handle packets that it needs to forward from one VLAN to the other: echo 1 > /proc/sys/net/ipv4/ip_forward route add -net 10.1.1.0 netmask 255.255.255.0 gw eth0.2 route add -net 10.1.2.0 netmask 255.255.255.0 gw eth0.3 This is it; nothing to it, right? b12957b4fa3a0967cfebfeee1f0b0b58a5b67d7f 2059 2058 2008-12-06T19:43:11Z Saruman! 2 Again undoing multiple spammer edits wikitext text/x-wiki ==Routes under Debian== When you need to add a networking route, there generally are two ways to do it: # manually adding a route at the command prompt: this means that the machine will "understand" the route for as long as it is running. However, when you reboot the machine, it will have "forgotten" the route. This is called a non-persistent route. # adding a route to the networking configuration files, so that it will be in place regardless of reboots or network restarts. This is called a persistent route. ===Manipulating non-persistent routes=== From the days of yore, the venerable ''route'' command enables us to view, add, change and delete routes. Its most known use is for printing the current routing table: #route -n Kernel IP routing table Destination Gateway Genmask Flags Metric Ref Use Iface 192.168.70.0 212.214.172.50 255.255.255.0 UG 0 0 0 eth1 192.168.67.0 * 255.255.255.0 U 0 0 0 eth0 212.214.172.0 * 255.255.255.0 U 0 0 0 eth1 default 212.214.172.1 0.0.0.0 UG 0 0 0 eth1 The addition of -n makes sure the ''route'' command does not try to substitute DNS names for IP addresses it knows. The second most used incarnation of ''route'' lies in the addition of a route, as has happened in the previous example. The route was added to the routing table using something like this: #route add -net 192.168.70.0 netmask 255.255.255.0 gw 212.214.172.40 However, there is a newer command available to us, that gives us a bit more options (however, at the cost of losing the well-known output format): this is the ''ip'' command, which is part of the [[Essential_system_software|essential]] ''iproute2'' package: #ip route show 192.168.70.0/24 via 212.214.172.50 dev eth1 src 192.168.67.10 192.168.67.0/24 dev eth0 proto kernel scope link src 192.168.67.10 212.214.172.0/24 dev eth1 proto kernel scope link src 212.214.172.50 default via 212.214.172.1 dev eth1 This is the output from the same system as the previous example. However, we see something interesting here: "ip" is capable of adding extra information to the route, like the first line shows (it's using "via"). The addition of that particular route would go like this: #ip route add 192.168.70.0/24 via 212.214.172.50 src 192.168.67.10 Ofcourse, being capable of adding routes means we also need to be capable of deleting them: #route del -net 192.168.70.0 netmask 255.255.255.0 #ip route del 192.168.70.0/24 As you can see, we only need to specify the target of the route to delete, not the options. ===Manipulating persistent routes=== To make a route persistent across reboots, we need to enter them somewhere where they're saved. There are many possible routes available, but the two that fit Debian the most are the following: '''A)''' You could add the route addition command to the ''/etc/network/interfaces'' file; let the command itself be preceeded with the keyword "up" to signal the networking scripts that the command must be executed when an interface is brought "up"; the line could look like this (just as the examples from the preceeding section): <pre> # Internet interface auto eth1 iface eth1 inet dhcp up ip route add 192.168.70.0/24 via 212.214.172.50 src 192.168.67.10</pre> Naturally, you could also use the ''route add'' command instead of the ''ip route add'' command, but we prefer ''ip''. Note: it matters --where-- in the ''interfaces'' file you put this line: it should be put in the same stanza as the interface it operates on. In this example, the external interface of the server is 212.214.172.50, which belongs with interface ''eth1''. Therefore, the "up" line appears in the stanza for ''eth1''. '''B)''' You could create a script that sets the route(s), and put it in the directory ''/etc/network/if-up.d''. Since all scripts that reside there get called when any interface goes "up", your route setting script would be called when ''any'' interface comes up, including ''lo''. This in turn means that a script for setting a route that belongs with a particular interface, should check on invocation which is the interface that goes up. At this moment in time, we don't employ any such script, so no example here, but if you look at the existing scripts in ''/etc/network/if-up.d'' you'll see how other programmers have done this. ==DNS resolution under Debian== One headache you might encounter when configuring a Debian server is how to let every program know how to resolve DNS names. Before a program can connect to an external network resource (say, for example, a web server), it must have a means of converting DNS names (e.g. www.saruman.biz) into the corresponding IP addresses (e.g. 192.168.67.10). This process is called "name resolution". The need for name resolution means that every program needs to know about the available means by which to do this name resolution. From the good old days comes the configuration file ''resolv.conf'', normally found in ''/etc''. It contains information about the nameservers to be used by the system, be they actual servers or lookup files. However, more and more programs have the need to dynamically modify the ''resolv.conf'' configuration file. This means that frequently they step on each other, and the ''resolv.conf'' file can become out-of-sync. The ''resolvconf'' program addresses this problem. It acts as an intermediary between programs that supply nameserver information (e.g. DHCP clients) and programs that use nameserver information (e.g. resolver). When ''resolvconf'' is properly installed, the file ''/etc/resolv.conf'' is replaced by a symbolic link to ''/etc/resolvconf/run/resolv.conf'', and any resolver thus uses the dynamically generated resolver configuration file at ''/etc/resolvconf/run/resolv.conf''. The ''resolvconf'' program is only necessary when a system has multiple programs that need to dynamically modify the nameserver information. In a simple system where the nameservers do not change often or are only changed by one program, the standard ''/etc/resolv.conf'' configuration file is adequate. == VLANs under Debian == Debian can support network traffic over VLANs (ethernet 802.1q) - and we don't mean the normal "untagged" network ports (hey, VLANs are transparent that way, anybody and anything can use untagged network ports). No, we mean that Debian can accept network traffic in from, and send traffic out to, a VLAN tagged switchport. Suppose you have a layer 2 switch with support for 802.1q VLANs, and want to route traffic from one VLAN to another. For this you can use a Debian router with a single network interface, using VLAN support (this is called "router on a stick" because the routing takes place over only one cable). First, as root, run apt-get install vlan modprobe 8021q The first line is to install the vlan package, which contains all necessary tools to create and manipulate VLAN-enabled network ports. The second line loads the module that enables VLAN tagging for your ethernet network cards. Note: if you don't have the stock Debian kernel, but compiled your own, then you might have chosen not to compile the 8021q module. In that case, compile the module. Also note, that if you've compiled the 8021q code into the kernel itself, then you don't need to load the module and that second line is unnecessary for you. You'll find this kernel compile option (depending on your kernel version) under Networking -> Networking Options -> "802.1Q VLAN Support". This option has been in the Linux kernel since version 2.4.14. ifconfig eth0 down vconfig add eth0 2 vconfig add eth0 3 The first command brings down your network on eth0 (not the thing to do if you're working remote, then :-). The next two commands create two virtual interfaces ''eth0.2'' and ''eth0.3'', which have VLAN tags 2 and 3 (don't use VLAN tag 1 if you can help it; on many devices VLAN1 is a special hardware management VLAN). The virtual interfaces run on top of your ''eth0'' interface.<br> Now because your VLAN interfaces run on top of ''eth0'', you've got to bring ''eth0'' itself up, even if you don't want to run network traffic over it. Furthermore, you've got to configure the two virtual interfaces you've created. Let's suppose you want to run IP subnet 192.168.1.0/24 on VLAN2, and 192.168.2.0/24 on VLAN3. You can do so with ifconfig eth0 0.0.0.0 up ifconfig eth0.2 192.168.1.1 broadcast 192.168.1.255 netmask 255.255.255.0 up ifconfig eth0.3 192.168.2.1 broadcast 192.168.2.255 netmask 255.255.255.0 up Now that you've this done, you must still configure one of your switch ports to belong to VLAN 2 and 3 at the same time (tagged port), and connect ''eth0'' from your linux box to that port. This enables your box to run network traffic on both VLANs. To round things up: if you haven't yet enabled forwarding, you can do so now. Furthermore, you might wish to augment your route table so that the routing engine in your server knows how to handle packets that it needs to forward from one VLAN to the other: echo 1 > /proc/sys/net/ipv4/ip_forward route add -net 10.1.1.0 netmask 255.255.255.0 gw eth0.2 route add -net 10.1.2.0 netmask 255.255.255.0 gw eth0.3 This is it; nothing to it, right? 0eee61c8c8d0a43496c965f729db633ca12252dd 2060 2059 2008-12-13T11:26:49Z Saruman! 2 added ipsec site2site link wikitext text/x-wiki ==Routes under Debian== When you need to add a networking route, there generally are two ways to do it: # manually adding a route at the command prompt: this means that the machine will "understand" the route for as long as it is running. However, when you reboot the machine, it will have "forgotten" the route. This is called a non-persistent route. # adding a route to the networking configuration files, so that it will be in place regardless of reboots or network restarts. This is called a persistent route. ===Manipulating non-persistent routes=== From the days of yore, the venerable ''route'' command enables us to view, add, change and delete routes. Its most known use is for printing the current routing table: #route -n Kernel IP routing table Destination Gateway Genmask Flags Metric Ref Use Iface 192.168.70.0 212.214.172.50 255.255.255.0 UG 0 0 0 eth1 192.168.67.0 * 255.255.255.0 U 0 0 0 eth0 212.214.172.0 * 255.255.255.0 U 0 0 0 eth1 default 212.214.172.1 0.0.0.0 UG 0 0 0 eth1 The addition of -n makes sure the ''route'' command does not try to substitute DNS names for IP addresses it knows. The second most used incarnation of ''route'' lies in the addition of a route, as has happened in the previous example. The route was added to the routing table using something like this: #route add -net 192.168.70.0 netmask 255.255.255.0 gw 212.214.172.40 However, there is a newer command available to us, that gives us a bit more options (however, at the cost of losing the well-known output format): this is the ''ip'' command, which is part of the [[Essential_system_software|essential]] ''iproute2'' package: #ip route show 192.168.70.0/24 via 212.214.172.50 dev eth1 src 192.168.67.10 192.168.67.0/24 dev eth0 proto kernel scope link src 192.168.67.10 212.214.172.0/24 dev eth1 proto kernel scope link src 212.214.172.50 default via 212.214.172.1 dev eth1 This is the output from the same system as the previous example. However, we see something interesting here: "ip" is capable of adding extra information to the route, like the first line shows (it's using "via"). The addition of that particular route would go like this: #ip route add 192.168.70.0/24 via 212.214.172.50 src 192.168.67.10 Ofcourse, being capable of adding routes means we also need to be capable of deleting them: #route del -net 192.168.70.0 netmask 255.255.255.0 #ip route del 192.168.70.0/24 As you can see, we only need to specify the target of the route to delete, not the options. ===Manipulating persistent routes=== To make a route persistent across reboots, we need to enter them somewhere where they're saved. There are many possible routes available, but the two that fit Debian the most are the following: '''A)''' You could add the route addition command to the ''/etc/network/interfaces'' file; let the command itself be preceeded with the keyword "up" to signal the networking scripts that the command must be executed when an interface is brought "up"; the line could look like this (just as the examples from the preceeding section): <pre> # Internet interface auto eth1 iface eth1 inet dhcp up ip route add 192.168.70.0/24 via 212.214.172.50 src 192.168.67.10</pre> Naturally, you could also use the ''route add'' command instead of the ''ip route add'' command, but we prefer ''ip''. Note: it matters --where-- in the ''interfaces'' file you put this line: it should be put in the same stanza as the interface it operates on. In this example, the external interface of the server is 212.214.172.50, which belongs with interface ''eth1''. Therefore, the "up" line appears in the stanza for ''eth1''. '''B)''' You could create a script that sets the route(s), and put it in the directory ''/etc/network/if-up.d''. Since all scripts that reside there get called when any interface goes "up", your route setting script would be called when ''any'' interface comes up, including ''lo''. This in turn means that a script for setting a route that belongs with a particular interface, should check on invocation which is the interface that goes up. At this moment in time, we don't employ any such script, so no example here, but if you look at the existing scripts in ''/etc/network/if-up.d'' you'll see how other programmers have done this. ==DNS resolution under Debian== One headache you might encounter when configuring a Debian server is how to let every program know how to resolve DNS names. Before a program can connect to an external network resource (say, for example, a web server), it must have a means of converting DNS names (e.g. www.saruman.biz) into the corresponding IP addresses (e.g. 192.168.67.10). This process is called "name resolution". The need for name resolution means that every program needs to know about the available means by which to do this name resolution. From the good old days comes the configuration file ''resolv.conf'', normally found in ''/etc''. It contains information about the nameservers to be used by the system, be they actual servers or lookup files. However, more and more programs have the need to dynamically modify the ''resolv.conf'' configuration file. This means that frequently they step on each other, and the ''resolv.conf'' file can become out-of-sync. The ''resolvconf'' program addresses this problem. It acts as an intermediary between programs that supply nameserver information (e.g. DHCP clients) and programs that use nameserver information (e.g. resolver). When ''resolvconf'' is properly installed, the file ''/etc/resolv.conf'' is replaced by a symbolic link to ''/etc/resolvconf/run/resolv.conf'', and any resolver thus uses the dynamically generated resolver configuration file at ''/etc/resolvconf/run/resolv.conf''. The ''resolvconf'' program is only necessary when a system has multiple programs that need to dynamically modify the nameserver information. In a simple system where the nameservers do not change often or are only changed by one program, the standard ''/etc/resolv.conf'' configuration file is adequate. == VLANs under Debian == Debian can support network traffic over VLANs (ethernet 802.1q) - and we don't mean the normal "untagged" network ports (hey, VLANs are transparent that way, anybody and anything can use untagged network ports). No, we mean that Debian can accept network traffic in from, and send traffic out to, a VLAN tagged switchport. Suppose you have a layer 2 switch with support for 802.1q VLANs, and want to route traffic from one VLAN to another. For this you can use a Debian router with a single network interface, using VLAN support (this is called "router on a stick" because the routing takes place over only one cable). First, as root, run apt-get install vlan modprobe 8021q The first line is to install the vlan package, which contains all necessary tools to create and manipulate VLAN-enabled network ports. The second line loads the module that enables VLAN tagging for your ethernet network cards. Note: if you don't have the stock Debian kernel, but compiled your own, then you might have chosen not to compile the 8021q module. In that case, compile the module. Also note, that if you've compiled the 8021q code into the kernel itself, then you don't need to load the module and that second line is unnecessary for you. You'll find this kernel compile option (depending on your kernel version) under Networking -> Networking Options -> "802.1Q VLAN Support". This option has been in the Linux kernel since version 2.4.14. ifconfig eth0 down vconfig add eth0 2 vconfig add eth0 3 The first command brings down your network on eth0 (not the thing to do if you're working remote, then :-). The next two commands create two virtual interfaces ''eth0.2'' and ''eth0.3'', which have VLAN tags 2 and 3 (don't use VLAN tag 1 if you can help it; on many devices VLAN1 is a special hardware management VLAN). The virtual interfaces run on top of your ''eth0'' interface.<br> Now because your VLAN interfaces run on top of ''eth0'', you've got to bring ''eth0'' itself up, even if you don't want to run network traffic over it. Furthermore, you've got to configure the two virtual interfaces you've created. Let's suppose you want to run IP subnet 192.168.1.0/24 on VLAN2, and 192.168.2.0/24 on VLAN3. You can do so with ifconfig eth0 0.0.0.0 up ifconfig eth0.2 192.168.1.1 broadcast 192.168.1.255 netmask 255.255.255.0 up ifconfig eth0.3 192.168.2.1 broadcast 192.168.2.255 netmask 255.255.255.0 up Now that you've this done, you must still configure one of your switch ports to belong to VLAN 2 and 3 at the same time (tagged port), and connect ''eth0'' from your linux box to that port. This enables your box to run network traffic on both VLANs. To round things up: if you haven't yet enabled forwarding, you can do so now. Furthermore, you might wish to augment your route table so that the routing engine in your server knows how to handle packets that it needs to forward from one VLAN to the other: echo 1 > /proc/sys/net/ipv4/ip_forward route add -net 10.1.1.0 netmask 255.255.255.0 gw eth0.2 route add -net 10.1.2.0 netmask 255.255.255.0 gw eth0.3 This is it; nothing to it, right? =Tunneling under Debian= Being a Linux distribution, Debian gives you all the networking power of that platform. One of the powerful features of Linux networking is the ease with which you can create network tunnels. Many possibilities exist; in this wiki we've documented the following: * [[IPsec site-to-site tunnel]] with which you can connect two networks, so that machines in both networks can reach machines in the other network fbb1f6124f455aaf51277de1963ac0019da1741f 0 1496 2061 2008-12-13T11:39:35Z Saruman! 2 Page started wikitext text/x-wiki =IPsec tunneling theory= IPsec is very powerful, but also quite complicated and intricate. When starting on tunneling, you might want to start exploring the site [http://www.ipsec-howto.org/ ipsec-howto]. It explains both the theory of IPsec, and describes how to create IPsec tunnels. However, after reviewing the theory, you might want to continue here for a more elaborate, Debian-specific, site-to-site only, howto on tunneling. =IPsec site-to-site tunneling= ==Starting point: two sites== ==IPsec preparations== ==IPsec installation== =IPsec site-to-site tunnel configuration= ==Method 1: using ''racoon-tool''== ==Method 2: direct ''racoon'' configuration== ==Extra configuration issues== ===setting the right routes=== ===adapting your firewall configuration=== ===DNS and WINS issues=== =IPsec diagnostics= ac9d28160bc89f97be05f6fe53d07e027d50c5f3 2062 2061 2008-12-14T09:48:37Z Saruman! 2 /* IPsec preparations */ from ODT doc wikitext text/x-wiki =IPsec tunneling theory= IPsec is very powerful, but also quite complicated and intricate. When starting on tunneling, you might want to start exploring the site [http://www.ipsec-howto.org/ ipsec-howto]. It explains both the theory of IPsec, and describes how to create IPsec tunnels. However, after reviewing the theory, you might want to continue here for a more elaborate, Debian-specific, site-to-site only, howto on tunneling. =IPsec site-to-site tunneling= ==Starting point: two sites== ==IPsec preparations== First off, you'll have to inventory your prospective tunnel setup. We suggest you fill in the following table (filled here for the purpose of example): {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !width="150" style="background:#ffdead;"|Debian Server !width="150" style="background:#ffdead;"|Data !width="150" style="background:#ffdead;"|Example |- |Name(*) | |dworkin |- |Internet IP | |212.238.151.172 |- |Private IP | |192.168.0.9 |- |Network(s) | |192.168.0.0/24 |- |Default key exchange encryption | |3DES |- |Default tunnel encryption | |3DES |- |} (*) This data is not mandatory, but it makes it easier to reference the machine in question. Next up, we need the same data for the far side of every tunnel you'll be creating: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !width="150" style="background:#ffdead;"|Debian Server !width="150" style="background:#ffdead;"|Data !width="150" style="background:#ffdead;"|Example |- |Name(*) | |darktower |- |Internet IP | |82.161.20.13 |- |Private IP | |192.168.1.10 |- |Network(s) | |192.168.1.0/24 |- |Preferred key exchange encryption | |SHA1 |- |Preferred tunnel encryption | |SHA1 |- |} Next, you'll have to verify if your kernel has been compiled with the necessary options. What you need at minimum are the following kernel options, that can be found under ''Networking support > Networking options'': * '''PF_KEY Sockets''': This option makes your kernel compatible with the KAME IPsec tools that we're going to use. * '''IP: ESP transformation''': This option ensures we can create IPsec networking packets in ESP mode. * '''IP: IPsec tunnel mode''': This option enables the IPsec tunnel mode. For IPsec you need several cryptographic algorithms; the mandatory ones are already selected because you set the options above. But if you need or want additional ones (AES, Blowfish etc), then go to ''Cryptographic API'', and select the algorithms you want. We would suggest the following algorithms: * Null algorithms: useful for testing * SHA224 and SHA256 digest algorithm: pretty secure and pretty well supported * Blowfish cipher algorithm: fast and efficient * AES cipher algorithms: AES is a well-known standard, that is still considered pretty secure If you have any other cryptographic need, then most likely you'll have to satisfy it here as well. Then, after the usual compiling and installing of your new or updated kernel, you'll of course have to reboot to be able to use these features. ==IPsec installation== =IPsec site-to-site tunnel configuration= ==Method 1: using ''racoon-tool''== ==Method 2: direct ''racoon'' configuration== ==Extra configuration issues== ===setting the right routes=== ===adapting your firewall configuration=== ===DNS and WINS issues=== =IPsec diagnostics= 35957b0dc9d214bf401535d5e31c75cc6fededb9 2063 2062 2008-12-14T11:03:36Z Saruman! 2 /* IPsec preparations */ added racoon-tool wikitext text/x-wiki =IPsec tunneling theory= IPsec is very powerful, but also quite complicated and intricate. When starting on tunneling, you might want to start exploring the site [http://www.ipsec-howto.org/ ipsec-howto]. It explains both the theory of IPsec, and describes how to create IPsec tunnels. However, after reviewing the theory, you might want to continue here for a more elaborate, Debian-specific, site-to-site only, howto on tunneling. =IPsec site-to-site tunneling= ==Starting point: two sites== ==IPsec preparations== First off, you'll have to inventory your prospective tunnel setup. We suggest you fill in the following table (filled here for the purpose of example): {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !width="150" style="background:#ffdead;"|Debian Server !width="150" style="background:#ffdead;"|Data !width="150" style="background:#ffdead;"|Example |- |Name(*) | |dworkin |- |Internet IP | |212.238.151.172 |- |Private IP | |192.168.0.9 |- |Network(s) | |192.168.0.0/24 |- |Default key exchange encryption | |3DES |- |Default tunnel encryption | |3DES |- |} (*) This data is not mandatory, but it makes it easier to reference the machine in question. Furthermore, you'll need to decide if you are going to use the debian-specific tool ''racoon-tool'', or if you're going to configure ''racoon'' directly. If you don't know what the difference is, choosing will be quite hard. So here follows a little description of the tools, and what we see as the consequences of your choice. * [http://www.kame.net/newsletter/20001119/ ''racoon''] is a daemon that can exchange keys with the other end of a prospective IPsec connection in a secure and automated way; it is part of the [http://ipsec-tools.sourceforge.net/ IPsec-tools package]. You are supposed to configure it by means of entering exactly the right data in ''/etc/racoon/racoon.conf''. Using ''racoon'' directly is the "standard" way of setting up an IPsec tunnel * ''racoon-tool'' is a Debian-specific Perl script, that can perform your ''racoon'' configuration for you. Using this means that you're less likely to make typo's etcetera: it's plain easier. On the other hand, since this is Debian-specific, a lot of information on the Internet might get less usable for you, since that assumes you're using plain ''racoon''. This shortcoming is mitigated somewhat by the realization that ''racoon-tool'' generates a ''racoon.conf'' file just as you'd expect, but only in a different location (''/var/lib/racoon/racoon.conf'' instead of ''/etc/racoon/racoon.conf''). But then again, you might want to learn how to make IPsec tunnels in a way that can be used on non-Debian servers as well... We feel there is no compelling general reason to choose one way over the other, so we'll outline both ways here. You'll have to choose, though. Mind you, if you ever change your mind, you can easily switch from direct to ''racoon-tool'' or back by running ''dpkg-reconfigure racoon''... Next up, we need the same data for the far side of every tunnel you'll be creating: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !width="150" style="background:#ffdead;"|Debian Server !width="150" style="background:#ffdead;"|Data !width="150" style="background:#ffdead;"|Example |- |Name(*) | |darktower |- |Internet IP | |82.161.20.13 |- |Private IP | |192.168.1.10 |- |Network(s) | |192.168.1.0/24 |- |Preferred key exchange encryption | |SHA1 |- |Preferred tunnel encryption | |SHA1 |- |} Next, you'll have to verify if your kernel has been compiled with the necessary options. What you need at minimum are the following kernel options, that can be found under ''Networking support > Networking options'': * '''PF_KEY Sockets''': This option makes your kernel compatible with the KAME IPsec tools that we're going to use. * '''IP: ESP transformation''': This option ensures we can create IPsec networking packets in ESP mode. * '''IP: IPsec tunnel mode''': This option enables the IPsec tunnel mode. For IPsec you need several cryptographic algorithms; the mandatory ones are already selected because you set the options above. But if you need or want additional ones (AES, Blowfish etc), then go to ''Cryptographic API'', and select the algorithms you want. We would suggest the following algorithms: * Null algorithms: useful for testing * SHA224 and SHA256 digest algorithm: pretty secure and pretty well supported * Blowfish cipher algorithm: fast and efficient * AES cipher algorithms: AES is a well-known standard, that is still considered pretty secure If you have any other cryptographic need, then most likely you'll have to satisfy it here as well. Then, after the usual compiling and installing of your new or updated kernel, you'll of course have to reboot to be able to use these features. ==IPsec installation== =IPsec site-to-site tunnel configuration= ==Method 1: using ''racoon-tool''== ==Method 2: direct ''racoon'' configuration== ==Extra configuration issues== ===setting the right routes=== ===adapting your firewall configuration=== ===DNS and WINS issues=== =IPsec diagnostics= 6bb0865e3d93d446111705f47ab502f290ac0600 2064 2063 2008-12-14T11:37:18Z Saruman! 2 reordering wikitext text/x-wiki =IPsec tunneling theory= IPsec is very powerful, but also quite complicated and intricate. When starting on tunneling, you might want to start exploring the site [http://www.ipsec-howto.org/ ipsec-howto]. It explains both the theory of IPsec, and describes how to create IPsec tunnels. However, after reviewing the theory, you might want to continue here for a more elaborate, Debian-specific, site-to-site only, howto on tunneling. =IPsec site-to-site tunneling= ==IPsec general preparations== First off, you'll have to inventory your prospective tunnel setup. We suggest you fill in the following table (filled here for the purpose of example): {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !width="150" style="background:#ffdead;"|Debian Server !width="150" style="background:#ffdead;"|Data !width="150" style="background:#ffdead;"|Example |- |Name(*) | |dworkin |- |Internet IP | |212.238.151.172 |- |Private IP | |192.168.0.9 |- |Network(s) | |192.168.0.0/24 |- |Default key exchange encryption | |3DES |- |Default tunnel encryption | |3DES |- |} (*) This data is not mandatory, but it makes it easier to reference the machine in question. Next, you'll need to decide if you are going to use the debian-specific tool ''racoon-tool'', or if you're going to configure ''racoon'' directly. If you don't know what the difference is, choosing will be quite hard. So here follows a little description of the tools, and what we see as the consequences of your choice. * [http://www.kame.net/newsletter/20001119/ ''racoon''] is a daemon that can exchange keys with the other end of a prospective IPsec connection in a secure and automated way; it is part of the [http://ipsec-tools.sourceforge.net/ IPsec-tools package]. You are supposed to configure it by means of entering exactly the right data in ''/etc/racoon/racoon.conf''. Using ''racoon'' directly is the "standard" way of setting up an IPsec tunnel * ''racoon-tool'' is a Debian-specific Perl script, that can perform your ''racoon'' configuration for you. Using this means that you're less likely to make typo's etcetera: it's plain easier. On the other hand, since this is Debian-specific, a lot of information on the Internet might get less usable for you, since that assumes you're using plain ''racoon''. This shortcoming is mitigated somewhat by the realization that ''racoon-tool'' generates a ''racoon.conf'' file just as you'd expect, but only in a different location (''/var/lib/racoon/racoon.conf'' instead of ''/etc/racoon/racoon.conf''). But then again, you might want to learn how to make IPsec tunnels in a way that can be used on non-Debian servers as well... We feel there is no compelling general reason to choose one way over the other, so we'll outline both ways here. You'll have to choose, though. Mind you, if you ever change your mind, you can easily switch from direct to ''racoon-tool'' or back by running ''dpkg-reconfigure racoon''... Next, you'll have to verify if your kernel has been compiled with the necessary options. What you need at minimum are the following kernel options, that can be found under ''Networking support > Networking options'': * '''PF_KEY Sockets''': This option makes your kernel compatible with the KAME IPsec tools that we're going to use. * '''IP: ESP transformation''': This option ensures we can create IPsec networking packets in ESP mode. * '''IP: IPsec tunnel mode''': This option enables the IPsec tunnel mode. For IPsec you need several cryptographic algorithms; the mandatory ones are already selected because you set the options above. But if you need or want additional ones (AES, Blowfish etc), then go to ''Cryptographic API'', and select the algorithms you want. We would suggest the following algorithms: * Null algorithms: useful for testing * SHA224 and SHA256 digest algorithm: pretty secure and pretty well supported * Blowfish cipher algorithm: fast and efficient * AES cipher algorithms: AES is a well-known standard, that is still considered pretty secure If you have any other cryptographic need, then most likely you'll have to satisfy it here as well. Then, after the usual compiling and installing of your new or updated kernel, you'll of course have to reboot to be able to use these features. Verify that your Linux server is not sitting behind a NATting device, like an ADSL modem/router. If it is, you'll need an extra feature (NAT-T, or Nat Traversal), not described in this procedure. ==IPsec installation== The amount of software we need to realize an IPsec tunnel is limited, because most of the IPsec capabilities are now integrated in the Linux kernel. The packages we need are: * ''ipsec-tools'', the package that contains the KAME IPsec tools with which we can control the IPsec implementation that's in the Linux kernel; * ''racoon'', the Internet Key Exchange daemon; * ''[[vim]]''(*), an improved version of the ''vi'' editor. (*)Well we don't really need [[vim]], but if we install it, not only will we have a very powerful editor, but also will we be able to use the ''xxd'' command when generating strong encryption keys. When using ''aptitude'' or ''apt-get install'' to install ''racoon'', we'll be asked for the desired "Configuration mode for racoon IKE daemon": direct or racoon-tool. Choose according to your preference. That's it! No additional software is required. Your system is now ready to set up IPsec tunnels - all it requires is the right configuration (and a correctly configured endpoint for the other end of the tunnel). =IPsec site-to-site tunnel configuration= ==IPsec tunnel-specific preparations== When we start creating a tunnel, we need the relevant data for the far side of each tunnel we'll be creating, similar to what we've already gathered for our own side of the tunnel. Note that it is not necessary that the other endpoint is also a Linux server; it could just as well be an IPsec capable appliance like a ''Checkpoint FW1'' firewall or a Microsoft Windows server. The main difference between different endpoints is the set of encryption algorithms they'll be able to support. Therefor, the preferred encryption algorithm must be negotiated between you and your counterpart on the other side of the tunnel. In this example, the other side is a Debian server as well, and we've agreed to use SHA1 as algorithm for both the IKE phase and the actual tunnel. Furthermore, we've agreed on a secret key, needed for the initial IKE phase. {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Debian Server !width="250" style="background:#ffdead;"|Data !style="background:#ffdead;"|Example |- |Name(*) | |darktower |- |Internet IP | |82.161.20.13 |- |Private IP | |192.168.1.10 |- |Network(s) | |192.168.1.0/24 |- |Preferred key exchange encryption | |SHA1 |- |PreShared Key | |0x383a94619b3d6a8f33a39f68b4d16594 |- |Preferred tunnel encryption | |SHA1 |- |} So how do we generate a strong PSK? A quick way would be to execute this command: dd if=/dev/random count=16 bs=1 | xxd -ps This will output a strong key, like ''383a94619b3d6a8f33a39f68b4d16594''; you'll only have to prepend ''0x'' to signify that it's a hexadecimal key. Now with the data for the tunnel available, we can get going on the configuration of the tunnel itself. If you've selected using ''racoon-tool'', read on. If you've chosen ''direct'' (or if you're not on a Debian server but another Linux distribution), skip to the next section. ==Method 1: using ''racoon-tool''== ==Method 2: direct ''racoon'' configuration== ==Extra configuration issues== ===setting the right routes=== ===adapting your firewall configuration=== ===DNS and WINS issues=== =IPsec diagnostics= 6a32d0dffcdc48f007bbd1c49f29c9879210cc98 2065 2064 2008-12-14T12:14:53Z Saruman! 2 /* IPsec tunnel-specific preparations */ added PSK wikitext text/x-wiki =IPsec tunneling theory= IPsec is very powerful, but also quite complicated and intricate. When starting on tunneling, you might want to start exploring the site [http://www.ipsec-howto.org/ ipsec-howto]. It explains both the theory of IPsec, and describes how to create IPsec tunnels. However, after reviewing the theory, you might want to continue here for a more elaborate, Debian-specific, site-to-site only, howto on tunneling. =IPsec site-to-site tunneling= ==IPsec general preparations== First off, you'll have to inventory your prospective tunnel setup. We suggest you fill in the following table (filled here for the purpose of example): {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !width="150" style="background:#ffdead;"|Debian Server !width="150" style="background:#ffdead;"|Data !width="150" style="background:#ffdead;"|Example |- |Name(*) | |dworkin |- |Internet IP | |212.238.151.172 |- |Private IP | |192.168.0.9 |- |Network(s) | |192.168.0.0/24 |- |Default key exchange encryption | |3DES |- |Default tunnel encryption | |3DES |- |} (*) This data is not mandatory, but it makes it easier to reference the machine in question. Next, you'll need to decide if you are going to use the debian-specific tool ''racoon-tool'', or if you're going to configure ''racoon'' directly. If you don't know what the difference is, choosing will be quite hard. So here follows a little description of the tools, and what we see as the consequences of your choice. * [http://www.kame.net/newsletter/20001119/ ''racoon''] is a daemon that can exchange keys with the other end of a prospective IPsec connection in a secure and automated way; it is part of the [http://ipsec-tools.sourceforge.net/ IPsec-tools package]. You are supposed to configure it by means of entering exactly the right data in ''/etc/racoon/racoon.conf''. Using ''racoon'' directly is the "standard" way of setting up an IPsec tunnel * ''racoon-tool'' is a Debian-specific Perl script, that can perform your ''racoon'' configuration for you. Using this means that you're less likely to make typo's etcetera: it's plain easier. On the other hand, since this is Debian-specific, a lot of information on the Internet might get less usable for you, since that assumes you're using plain ''racoon''. This shortcoming is mitigated somewhat by the realization that ''racoon-tool'' generates a ''racoon.conf'' file just as you'd expect, but only in a different location (''/var/lib/racoon/racoon.conf'' instead of ''/etc/racoon/racoon.conf''). But then again, you might want to learn how to make IPsec tunnels in a way that can be used on non-Debian servers as well... We feel there is no compelling general reason to choose one way over the other, so we'll outline both ways here. You'll have to choose, though. Mind you, if you ever change your mind, you can easily switch from direct to ''racoon-tool'' or back by running ''dpkg-reconfigure racoon''... Next, you'll have to verify if your kernel has been compiled with the necessary options. What you need at minimum are the following kernel options, that can be found under ''Networking support > Networking options'': * '''PF_KEY Sockets''': This option makes your kernel compatible with the KAME IPsec tools that we're going to use. * '''IP: ESP transformation''': This option ensures we can create IPsec networking packets in ESP mode. * '''IP: IPsec tunnel mode''': This option enables the IPsec tunnel mode. For IPsec you need several cryptographic algorithms; the mandatory ones are already selected because you set the options above. But if you need or want additional ones (AES, Blowfish etc), then go to ''Cryptographic API'', and select the algorithms you want. We would suggest the following algorithms: * Null algorithms: useful for testing * SHA224 and SHA256 digest algorithm: pretty secure and pretty well supported * Blowfish cipher algorithm: fast and efficient * AES cipher algorithms: AES is a well-known standard, that is still considered pretty secure If you have any other cryptographic need, then most likely you'll have to satisfy it here as well. Then, after the usual compiling and installing of your new or updated kernel, you'll of course have to reboot to be able to use these features. Verify that your Linux server is not sitting behind a NATting device, like an ADSL modem/router. If it is, you'll need an extra feature (NAT-T, or Nat Traversal), not described in this procedure. ==IPsec installation== The amount of software we need to realize an IPsec tunnel is limited, because most of the IPsec capabilities are now integrated in the Linux kernel. The packages we need are: * ''ipsec-tools'', the package that contains the KAME IPsec tools with which we can control the IPsec implementation that's in the Linux kernel; * ''racoon'', the Internet Key Exchange daemon; * ''[[vim]]''(*), an improved version of the ''vi'' editor. (*)Well we don't really need [[vim]], but if we install it, not only will we have a very powerful editor, but also will we be able to use the ''xxd'' command when generating strong encryption keys. When using ''aptitude'' or ''apt-get install'' to install ''racoon'', we'll be asked for the desired "Configuration mode for racoon IKE daemon": direct or racoon-tool. Choose according to your preference. That's it! No additional software is required. Your system is now ready to set up IPsec tunnels - all it requires is the right configuration (and a correctly configured endpoint for the other end of the tunnel). =IPsec site-to-site tunnel configuration= ==IPsec tunnel-specific preparations== When we start creating a tunnel, we need the relevant data for the far side of each tunnel we'll be creating, similar to what we've already gathered for our own side of the tunnel. Note that it is not necessary that the other endpoint is also a Linux server; it could just as well be an IPsec capable appliance like a ''Checkpoint FW1'' firewall or a Microsoft Windows server. The main difference between different endpoints is the set of encryption algorithms they'll be able to support. Therefor, the preferred encryption algorithm must be negotiated between you and your counterpart on the other side of the tunnel. In this example, the other side is a Debian server as well, and we've agreed to use SHA1 as algorithm for both the IKE phase and the actual tunnel. Furthermore, we've agreed on a secret key, needed for the initial IKE phase. {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Debian Server !width="250" style="background:#ffdead;"|Data !style="background:#ffdead;"|Example |- |Name(*) | |darktower |- |Internet IP | |82.161.20.13 |- |Private IP | |192.168.1.10 |- |Network(s) | |192.168.1.0/24 |- |Preferred key exchange encryption | |SHA1 |- |PreShared Key | |0x383a94619b3d6a8f33a39f68b4d16594 |- |Preferred tunnel encryption | |SHA1 |- |} So how do we generate a strong PSK? A quick way would be to execute this command: dd if=/dev/random count=16 bs=1 | xxd -ps This will output a strong key, like ''383a94619b3d6a8f33a39f68b4d16594''; you'll only have to prepend ''0x'' to signify that it's a hexadecimal key. Note that if you do not prepend ''0x'', it will mean that the key will be interpreted as a passphrase instead of a key. No harm there, as long as you do this on ''both'' sides of the tunnel. We must put this key in a key file. To this end, we append the file ''/etc/racoon/psk.txt'' with the following information: # key for tunnel to darktower 82.161.20.13 0x383a94619b3d6a8f33a39f68b4d16594 Note: there is already sample information in this file; it is good practice to comment this out. Furthermore, make sure this file is ONLY readable for root (''sudo chmod 600''). Finally, remember that the other side of the tunnel needs the EXACT same key - transport it there using a very secure method (like going there in person). If your key gets compromised on the way there, your tunnel is not secure! Now with the data for the tunnel available and the key set up, we can get going on the configuration of the tunnel itself. If you've selected using ''racoon-tool'', read on. If you've chosen ''direct'' (or if you're not on a Debian server but another Linux distribution), skip to the next section. ==Method 1: using ''racoon-tool''== ==Method 2: direct ''racoon'' configuration== ==Extra configuration issues== ===setting the right routes=== ===adapting your firewall configuration=== ===DNS and WINS issues=== =IPsec diagnostics= 45601073b523cbe508e73756ef9049370e6d2a54 2066 2065 2008-12-14T12:21:32Z Saruman! 2 /* Method 2: direct racoon configuration */ started wikitext text/x-wiki =IPsec tunneling theory= IPsec is very powerful, but also quite complicated and intricate. When starting on tunneling, you might want to start exploring the site [http://www.ipsec-howto.org/ ipsec-howto]. It explains both the theory of IPsec, and describes how to create IPsec tunnels. However, after reviewing the theory, you might want to continue here for a more elaborate, Debian-specific, site-to-site only, howto on tunneling. =IPsec site-to-site tunneling= ==IPsec general preparations== First off, you'll have to inventory your prospective tunnel setup. We suggest you fill in the following table (filled here for the purpose of example): {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !width="150" style="background:#ffdead;"|Debian Server !width="150" style="background:#ffdead;"|Data !width="150" style="background:#ffdead;"|Example |- |Name(*) | |dworkin |- |Internet IP | |212.238.151.172 |- |Private IP | |192.168.0.9 |- |Network(s) | |192.168.0.0/24 |- |Default key exchange encryption | |3DES |- |Default tunnel encryption | |3DES |- |} (*) This data is not mandatory, but it makes it easier to reference the machine in question. Next, you'll need to decide if you are going to use the debian-specific tool ''racoon-tool'', or if you're going to configure ''racoon'' directly. If you don't know what the difference is, choosing will be quite hard. So here follows a little description of the tools, and what we see as the consequences of your choice. * [http://www.kame.net/newsletter/20001119/ ''racoon''] is a daemon that can exchange keys with the other end of a prospective IPsec connection in a secure and automated way; it is part of the [http://ipsec-tools.sourceforge.net/ IPsec-tools package]. You are supposed to configure it by means of entering exactly the right data in ''/etc/racoon/racoon.conf''. Using ''racoon'' directly is the "standard" way of setting up an IPsec tunnel * ''racoon-tool'' is a Debian-specific Perl script, that can perform your ''racoon'' configuration for you. Using this means that you're less likely to make typo's etcetera: it's plain easier. On the other hand, since this is Debian-specific, a lot of information on the Internet might get less usable for you, since that assumes you're using plain ''racoon''. This shortcoming is mitigated somewhat by the realization that ''racoon-tool'' generates a ''racoon.conf'' file just as you'd expect, but only in a different location (''/var/lib/racoon/racoon.conf'' instead of ''/etc/racoon/racoon.conf''). But then again, you might want to learn how to make IPsec tunnels in a way that can be used on non-Debian servers as well... We feel there is no compelling general reason to choose one way over the other, so we'll outline both ways here. You'll have to choose, though. Mind you, if you ever change your mind, you can easily switch from direct to ''racoon-tool'' or back by running ''dpkg-reconfigure racoon''... Next, you'll have to verify if your kernel has been compiled with the necessary options. What you need at minimum are the following kernel options, that can be found under ''Networking support > Networking options'': * '''PF_KEY Sockets''': This option makes your kernel compatible with the KAME IPsec tools that we're going to use. * '''IP: ESP transformation''': This option ensures we can create IPsec networking packets in ESP mode. * '''IP: IPsec tunnel mode''': This option enables the IPsec tunnel mode. For IPsec you need several cryptographic algorithms; the mandatory ones are already selected because you set the options above. But if you need or want additional ones (AES, Blowfish etc), then go to ''Cryptographic API'', and select the algorithms you want. We would suggest the following algorithms: * Null algorithms: useful for testing * SHA224 and SHA256 digest algorithm: pretty secure and pretty well supported * Blowfish cipher algorithm: fast and efficient * AES cipher algorithms: AES is a well-known standard, that is still considered pretty secure If you have any other cryptographic need, then most likely you'll have to satisfy it here as well. Then, after the usual compiling and installing of your new or updated kernel, you'll of course have to reboot to be able to use these features. Verify that your Linux server is not sitting behind a NATting device, like an ADSL modem/router. If it is, you'll need an extra feature (NAT-T, or Nat Traversal), not described in this procedure. ==IPsec installation== The amount of software we need to realize an IPsec tunnel is limited, because most of the IPsec capabilities are now integrated in the Linux kernel. The packages we need are: * ''ipsec-tools'', the package that contains the KAME IPsec tools with which we can control the IPsec implementation that's in the Linux kernel; * ''racoon'', the Internet Key Exchange daemon; * ''[[vim]]''(*), an improved version of the ''vi'' editor. (*)Well we don't really need [[vim]], but if we install it, not only will we have a very powerful editor, but also will we be able to use the ''xxd'' command when generating strong encryption keys. When using ''aptitude'' or ''apt-get install'' to install ''racoon'', we'll be asked for the desired "Configuration mode for racoon IKE daemon": direct or racoon-tool. Choose according to your preference. That's it! No additional software is required. Your system is now ready to set up IPsec tunnels - all it requires is the right configuration (and a correctly configured endpoint for the other end of the tunnel). =IPsec site-to-site tunnel configuration= ==IPsec tunnel-specific preparations== When we start creating a tunnel, we need the relevant data for the far side of each tunnel we'll be creating, similar to what we've already gathered for our own side of the tunnel. Note that it is not necessary that the other endpoint is also a Linux server; it could just as well be an IPsec capable appliance like a ''Checkpoint FW1'' firewall or a Microsoft Windows server. The main difference between different endpoints is the set of encryption algorithms they'll be able to support. Therefor, the preferred encryption algorithm must be negotiated between you and your counterpart on the other side of the tunnel. In this example, the other side is a Debian server as well, and we've agreed to use SHA1 as algorithm for both the IKE phase and the actual tunnel. Furthermore, we've agreed on a secret key, needed for the initial IKE phase. {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Debian Server !width="250" style="background:#ffdead;"|Data !style="background:#ffdead;"|Example |- |Name(*) | |darktower |- |Internet IP | |82.161.20.13 |- |Private IP | |192.168.1.10 |- |Network(s) | |192.168.1.0/24 |- |Preferred key exchange encryption | |SHA1 |- |PreShared Key | |0x383a94619b3d6a8f33a39f68b4d16594 |- |Preferred tunnel encryption | |SHA1 |- |} So how do we generate a strong PSK? A quick way would be to execute this command: dd if=/dev/random count=16 bs=1 | xxd -ps This will output a strong key, like ''383a94619b3d6a8f33a39f68b4d16594''; you'll only have to prepend ''0x'' to signify that it's a hexadecimal key. Note that if you do not prepend ''0x'', it will mean that the key will be interpreted as a passphrase instead of a key. No harm there, as long as you do this on ''both'' sides of the tunnel. We must put this key in a key file. To this end, we append the file ''/etc/racoon/psk.txt'' with the following information: # key for tunnel to darktower 82.161.20.13 0x383a94619b3d6a8f33a39f68b4d16594 Note: there is already sample information in this file; it is good practice to comment this out. Furthermore, make sure this file is ONLY readable for root (''sudo chmod 600''). Finally, remember that the other side of the tunnel needs the EXACT same key - transport it there using a very secure method (like going there in person). If your key gets compromised on the way there, your tunnel is not secure! Now with the data for the tunnel available and the key set up, we can get going on the configuration of the tunnel itself. If you've selected using ''racoon-tool'', read on. If you've chosen ''direct'' (or if you're not on a Debian server but another Linux distribution), skip to the next section. ==Method 1: using ''racoon-tool''== ==Method 2: direct ''racoon'' configuration== To configure ''racoon'' directly, we're going to edit ''/etc/racoon/racoon.conf''. Good practice is to rename the original ''racoon.conf'' to ''racoon.conf.org'', and create a fresh one. The basic file looks like this: # Racoon configuration file path pre_shared_key "/etc/racoon/psk.txt"; path certificate "/etc/racoon/certs"; # logging level: notify or debug log notify; listen { isakmp 212.238.151.172 [500]; isakmp_natt 212.238.151.172 [4500]; } This sets some default options for our Racoon daemon. ==Extra configuration issues== ===setting the right routes=== ===adapting your firewall configuration=== ===DNS and WINS issues=== =IPsec diagnostics= cc537b0d03d9d89e26e151e7195387b3c9c275c5 2067 2066 2008-12-14T14:29:43Z Saruman! 2 /* Method 2: direct racoon configuration */ racoon.conf described wikitext text/x-wiki =IPsec tunneling theory= IPsec is very powerful, but also quite complicated and intricate. When starting on tunneling, you might want to start exploring the site [http://www.ipsec-howto.org/ ipsec-howto]. It explains both the theory of IPsec, and describes how to create IPsec tunnels. However, after reviewing the theory, you might want to continue here for a more elaborate, Debian-specific, site-to-site only, howto on tunneling. =IPsec site-to-site tunneling= ==IPsec general preparations== First off, you'll have to inventory your prospective tunnel setup. We suggest you fill in the following table (filled here for the purpose of example): {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !width="150" style="background:#ffdead;"|Debian Server !width="150" style="background:#ffdead;"|Data !width="150" style="background:#ffdead;"|Example |- |Name(*) | |dworkin |- |Internet IP | |212.238.151.172 |- |Private IP | |192.168.0.9 |- |Network(s) | |192.168.0.0/24 |- |Default key exchange encryption | |3DES |- |Default tunnel encryption | |3DES |- |} (*) This data is not mandatory, but it makes it easier to reference the machine in question. Next, you'll need to decide if you are going to use the debian-specific tool ''racoon-tool'', or if you're going to configure ''racoon'' directly. If you don't know what the difference is, choosing will be quite hard. So here follows a little description of the tools, and what we see as the consequences of your choice. * [http://www.kame.net/newsletter/20001119/ ''racoon''] is a daemon that can exchange keys with the other end of a prospective IPsec connection in a secure and automated way; it is part of the [http://ipsec-tools.sourceforge.net/ IPsec-tools package]. You are supposed to configure it by means of entering exactly the right data in ''/etc/racoon/racoon.conf''. Using ''racoon'' directly is the "standard" way of setting up an IPsec tunnel * ''racoon-tool'' is a Debian-specific Perl script, that can perform your ''racoon'' configuration for you. Using this means that you're less likely to make typo's etcetera: it's plain easier. On the other hand, since this is Debian-specific, a lot of information on the Internet might get less usable for you, since that assumes you're using plain ''racoon''. This shortcoming is mitigated somewhat by the realization that ''racoon-tool'' generates a ''racoon.conf'' file just as you'd expect, but only in a different location (''/var/lib/racoon/racoon.conf'' instead of ''/etc/racoon/racoon.conf''). But then again, you might want to learn how to make IPsec tunnels in a way that can be used on non-Debian servers as well... We feel there is no compelling general reason to choose one way over the other, so we'll outline both ways here. You'll have to choose, though. Mind you, if you ever change your mind, you can easily switch from direct to ''racoon-tool'' or back by running ''dpkg-reconfigure racoon''... Next, you'll have to verify if your kernel has been compiled with the necessary options. What you need at minimum are the following kernel options, that can be found under ''Networking support > Networking options'': * '''PF_KEY Sockets''': This option makes your kernel compatible with the KAME IPsec tools that we're going to use. * '''IP: ESP transformation''': This option ensures we can create IPsec networking packets in ESP mode. * '''IP: IPsec tunnel mode''': This option enables the IPsec tunnel mode. For IPsec you need several cryptographic algorithms; the mandatory ones are already selected because you set the options above. But if you need or want additional ones (AES, Blowfish etc), then go to ''Cryptographic API'', and select the algorithms you want. We would suggest the following algorithms: * Null algorithms: useful for testing * SHA224 and SHA256 digest algorithm: pretty secure and pretty well supported * Blowfish cipher algorithm: fast and efficient * AES cipher algorithms: AES is a well-known standard, that is still considered pretty secure If you have any other cryptographic need, then most likely you'll have to satisfy it here as well. Then, after the usual compiling and installing of your new or updated kernel, you'll of course have to reboot to be able to use these features. Verify that your Linux server is not sitting behind a NATting device, like an ADSL modem/router. If it is, you'll need an extra feature (NAT-T, or Nat Traversal), not described in this procedure. ==IPsec installation== The amount of software we need to realize an IPsec tunnel is limited, because most of the IPsec capabilities are now integrated in the Linux kernel. The packages we need are: * ''ipsec-tools'', the package that contains the KAME IPsec tools with which we can control the IPsec implementation that's in the Linux kernel; * ''racoon'', the Internet Key Exchange daemon; * ''[[vim]]''(*), an improved version of the ''vi'' editor. (*)Well we don't really need [[vim]], but if we install it, not only will we have a very powerful editor, but also will we be able to use the ''xxd'' command when generating strong encryption keys. When using ''aptitude'' or ''apt-get install'' to install ''racoon'', we'll be asked for the desired "Configuration mode for racoon IKE daemon": direct or racoon-tool. Choose according to your preference. That's it! No additional software is required. Your system is now ready to set up IPsec tunnels - all it requires is the right configuration (and a correctly configured endpoint for the other end of the tunnel). =IPsec site-to-site tunnel configuration= ==IPsec tunnel-specific preparations== When we start creating a tunnel, we need the relevant data for the far side of each tunnel we'll be creating, similar to what we've already gathered for our own side of the tunnel. Note that it is not necessary that the other endpoint is also a Linux server; it could just as well be an IPsec capable appliance like a ''Checkpoint FW1'' firewall or a Microsoft Windows server. The main difference between different endpoints is the set of encryption algorithms they'll be able to support. Therefor, the preferred encryption algorithm must be negotiated between you and your counterpart on the other side of the tunnel. In this example, the other side is a Debian server as well, and we've agreed to use SHA1 as algorithm for both the IKE phase and the actual tunnel. Furthermore, we've agreed on a secret key, needed for the initial IKE phase. {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Debian Server !width="250" style="background:#ffdead;"|Data !style="background:#ffdead;"|Example |- |Name(*) | |darktower |- |Internet IP | |82.161.20.13 |- |Private IP | |192.168.1.10 |- |Network(s) | |192.168.1.0/24 |- |Preferred key exchange encryption | |SHA1 |- |PreShared Key | |0x383a94619b3d6a8f33a39f68b4d16594 |- |Preferred tunnel encryption | |SHA1 |- |} So how do we generate a strong PSK? A quick way would be to execute this command: dd if=/dev/random count=16 bs=1 | xxd -ps This will output a strong key, like ''383a94619b3d6a8f33a39f68b4d16594''; you'll only have to prepend ''0x'' to signify that it's a hexadecimal key. Note that if you do not prepend ''0x'', it will mean that the key will be interpreted as a passphrase instead of a key. No harm there, as long as you do this on ''both'' sides of the tunnel. We must put this key in a key file. To this end, we append the file ''/etc/racoon/psk.txt'' with the following information: # key for tunnel to darktower 82.161.20.13 0x383a94619b3d6a8f33a39f68b4d16594 Note: there is already sample information in this file; it is good practice to comment this out. Furthermore, make sure this file is ONLY readable for root (''sudo chmod 600''). Finally, remember that the other side of the tunnel needs the EXACT same key - transport it there using a very secure method (like going there in person). If your key gets compromised on the way there, your tunnel is not secure! Now with the data for the tunnel available and the key set up, we can get going on the configuration of the tunnel itself. If you've selected using ''racoon-tool'', read on. If you've chosen ''direct'' (or if you're not on a Debian server but another Linux distribution), skip to the next section. ==Method 1: using ''racoon-tool''== ==Method 2: direct ''racoon'' configuration== To configure ''racoon'' directly, we're going to edit ''/etc/racoon/racoon.conf''. Good practice is to rename the original ''racoon.conf'' to ''racoon.conf.org'', and create a fresh one. The basic file looks like this: # Racoon configuration file path pre_shared_key "/etc/racoon/psk.txt"; path certificate "/etc/racoon/certs"; # logging level: notify or debug log notify; listen { isakmp 212.238.151.172 [500]; isakmp_natt 212.238.151.172 [4500]; } This sets some default options for our Racoon daemon. The lines speak almost for themselves: the path plus filename for the PreShared Keys, the path to the certificates directory, the loglevel, and on which IP addresses and ports should the daemon listen - an in which mode. Normally, you'd only have an ''isakmp'' entry, followed by the public IP address, and the default IKE port (TCP 500). If you want to accomodate other servers behind NAT routers as tunnel endpoints, then you'd need that second entry - it'll make Racoon smart enough to negotiate the IKE phase even though there's a NAT router in between. Now the tunnel-specific stanza's. There are two, and they could look something like this: # # Connection odeonlan # remote 82.161.20.132 500 { proposal { encryption_algorithm 3des; hash_algorithm sha1; authentication_method pre_shared_key; dh_group modp1024; } verify_identifier on; peers_identifier address; exchange_mode main; } sainfo address 192.168.0.0/24[any] any address 192.168.1.0/24[any] any { pfs_group modp1024; encryption_algorithm aes,3des; authentication_algorithm hmac_sha1,hmac_md5; compression_algorithm deflate; } The first stanza describes the parameters with which the IKE phase 1 communication will take place. It says in this example: for the endpoint 82.161.20.132, negotiate IKE over port 500 (since that is the default port number, you could omit the 500). Start the IKE phase 1 negotiations with the following parameters: encrypt communication during IKE with 3des, use sha1 as hashing method, use the PSK file to verify that the other side is really who they claim to be, and use a 1024-bits Diffie-Hellman group. To find out what these parameters mean, we kindly refer you to execute command ''man racoon.conf'', and of course to Internet.<br> The last three statements in the first stanza have the following meaning: * if we want to, we can try to verify if the other side is who we believe it to be. This statement '''verify_identifier on''' turns on this identity check. * to now find out who the other side claims to be, we can look at several identifiers. Here we claim that we want to verify the IP '''address''' of the other side of the tunnel. This ensures the tunnel is not set up between our end and some unknown other server. * the keys must be exchanged between the endpoints in '''main mode''', which requires multiple messages going back and forth, but which ensures that the other side is indeed who they claim to be. This only works if the IP number of the other side is known in advance, as is the case with a server with a fixed internet IP address. This will NOT work if the other side of the tunnel is a roaming client - but since we're using the IP address already as identifier, this is not the case in this example. The second stanza decribes a "security association"; it says that the defined tunnel must be used if the kernel receives a request for IP traffic that matches the SAinfo description. Here the traffic description reads "If you see packets coming from any port on 192.168.0.0/24 in any protocol, and going to any port on 192.168.1.0/24 in any protocol, then that traffic must be encrypted (put through the tunnel) using the parameters specified between the curly brackets. You could use multiple ''sainfo'' stanza's to tunnel multiple types of traffic through the same tunnel. After specifying the tunnel in ''racoon.conf'' we need to restart the Racoon daemon so that it knows about our tunnel: sudo invoke-rc.d racoon restart Furthermore, we want to ensure that Racoon starts when we reboot our server, so we create a symlink in our runlevel directory: ln -s /etc/init.d/racoon /etc/rc2.d/S98racoon ==Extra configuration issues== ===setting the right routes=== ===adapting your firewall configuration=== ===DNS and WINS issues=== =IPsec diagnostics= d1541029aebafbed0d0377fa3bf3d8a089084764 2068 2067 2008-12-14T15:27:41Z Saruman! 2 /* IPsec general preparations */ added kernel options wikitext text/x-wiki =IPsec tunneling theory= IPsec is very powerful, but also quite complicated and intricate. When starting on tunneling, you might want to start exploring the site [http://www.ipsec-howto.org/ ipsec-howto]. It explains both the theory of IPsec, and describes how to create IPsec tunnels. However, after reviewing the theory, you might want to continue here for a more elaborate, Debian-specific, site-to-site only, howto on tunneling. =IPsec site-to-site tunneling= ==IPsec general preparations== First off, you'll have to inventory your prospective tunnel setup. We suggest you fill in the following table (filled here for the purpose of example): {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !width="150" style="background:#ffdead;"|Debian Server !width="150" style="background:#ffdead;"|Data !width="150" style="background:#ffdead;"|Example |- |Name(*) | |dworkin |- |Internet IP | |212.238.151.172 |- |Private IP | |192.168.0.9 |- |Network(s) | |192.168.0.0/24 |- |Default key exchange encryption | |3DES |- |Default tunnel encryption | |3DES |- |} (*) This data is not mandatory, but it makes it easier to reference the machine in question. Next, you'll need to decide if you are going to use the debian-specific tool ''racoon-tool'', or if you're going to configure ''racoon'' directly. If you don't know what the difference is, choosing will be quite hard. So here follows a little description of the tools, and what we see as the consequences of your choice. * [http://www.kame.net/newsletter/20001119/ ''racoon''] is a daemon that can exchange keys with the other end of a prospective IPsec connection in a secure and automated way; it is part of the [http://ipsec-tools.sourceforge.net/ IPsec-tools package]. You are supposed to configure it by means of entering exactly the right data in ''/etc/racoon/racoon.conf''. Using ''racoon'' directly is the "standard" way of setting up an IPsec tunnel * ''racoon-tool'' is a Debian-specific Perl script, that can perform your ''racoon'' configuration for you. Using this means that you're less likely to make typo's etcetera: it's plain easier. On the other hand, since this is Debian-specific, a lot of information on the Internet might get less usable for you, since that assumes you're using plain ''racoon''. This shortcoming is mitigated somewhat by the realization that ''racoon-tool'' generates a ''racoon.conf'' file just as you'd expect, but only in a different location (''/var/lib/racoon/racoon.conf'' instead of ''/etc/racoon/racoon.conf''). But then again, you might want to learn how to make IPsec tunnels in a way that can be used on non-Debian servers as well... We feel there is no compelling general reason to choose one way over the other, so we'll outline both ways here. You'll have to choose, though. Mind you, if you ever change your mind, you can easily switch from direct to ''racoon-tool'' or back by running ''dpkg-reconfigure racoon''... Next, you'll have to verify if your kernel has been compiled with the necessary options. What you need at minimum are the following kernel options, that can be found under ''Networking support > Networking options'': * '''Transformation user configuration interface''': this enables support for the Transformation (XFRM) user configuration interface; IPsec needs this. * '''PF_KEY Sockets''': This option makes your kernel compatible with the KAME IPsec tools that we're going to use. * '''IP: ESP transformation''': This option ensures we can create IPsec networking packets in ESP mode. * '''IP: IPsec tunnel mode''': This option enables the IPsec tunnel mode. * '''IP: IPComp transformation''': Not required, but you'll want this: it enables compression over your IPsec tunnels For IPsec you need several cryptographic algorithms; the mandatory ones are already selected because you set the options above. But if you need or want additional ones (AES, Blowfish etc), then go to ''Cryptographic API'', and select the algorithms you want. We would suggest the following algorithms: * Null algorithms: useful for testing * SHA224 and SHA256 digest algorithm: pretty secure and pretty well supported * Blowfish cipher algorithm: fast and efficient * AES cipher algorithms: AES is a well-known standard, that is still considered pretty secure If you have any other cryptographic need, then most likely you'll have to satisfy it here as well. Then, after the usual compiling and installing of your new or updated kernel, you'll of course have to reboot to be able to use these features. Verify that your Linux server is not sitting behind a NATting device, like an ADSL modem/router. If it is, you'll need an extra feature (NAT-T, or Nat Traversal), not described in this procedure. ==IPsec installation== The amount of software we need to realize an IPsec tunnel is limited, because most of the IPsec capabilities are now integrated in the Linux kernel. The packages we need are: * ''ipsec-tools'', the package that contains the KAME IPsec tools with which we can control the IPsec implementation that's in the Linux kernel; * ''racoon'', the Internet Key Exchange daemon; * ''[[vim]]''(*), an improved version of the ''vi'' editor. (*)Well we don't really need [[vim]], but if we install it, not only will we have a very powerful editor, but also will we be able to use the ''xxd'' command when generating strong encryption keys. When using ''aptitude'' or ''apt-get install'' to install ''racoon'', we'll be asked for the desired "Configuration mode for racoon IKE daemon": direct or racoon-tool. Choose according to your preference. That's it! No additional software is required. Your system is now ready to set up IPsec tunnels - all it requires is the right configuration (and a correctly configured endpoint for the other end of the tunnel). =IPsec site-to-site tunnel configuration= ==IPsec tunnel-specific preparations== When we start creating a tunnel, we need the relevant data for the far side of each tunnel we'll be creating, similar to what we've already gathered for our own side of the tunnel. Note that it is not necessary that the other endpoint is also a Linux server; it could just as well be an IPsec capable appliance like a ''Checkpoint FW1'' firewall or a Microsoft Windows server. The main difference between different endpoints is the set of encryption algorithms they'll be able to support. Therefor, the preferred encryption algorithm must be negotiated between you and your counterpart on the other side of the tunnel. In this example, the other side is a Debian server as well, and we've agreed to use SHA1 as algorithm for both the IKE phase and the actual tunnel. Furthermore, we've agreed on a secret key, needed for the initial IKE phase. {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Debian Server !width="250" style="background:#ffdead;"|Data !style="background:#ffdead;"|Example |- |Name(*) | |darktower |- |Internet IP | |82.161.20.13 |- |Private IP | |192.168.1.10 |- |Network(s) | |192.168.1.0/24 |- |Preferred key exchange encryption | |SHA1 |- |PreShared Key | |0x383a94619b3d6a8f33a39f68b4d16594 |- |Preferred tunnel encryption | |SHA1 |- |} So how do we generate a strong PSK? A quick way would be to execute this command: dd if=/dev/random count=16 bs=1 | xxd -ps This will output a strong key, like ''383a94619b3d6a8f33a39f68b4d16594''; you'll only have to prepend ''0x'' to signify that it's a hexadecimal key. Note that if you do not prepend ''0x'', it will mean that the key will be interpreted as a passphrase instead of a key. No harm there, as long as you do this on ''both'' sides of the tunnel. We must put this key in a key file. To this end, we append the file ''/etc/racoon/psk.txt'' with the following information: # key for tunnel to darktower 82.161.20.13 0x383a94619b3d6a8f33a39f68b4d16594 Note: there is already sample information in this file; it is good practice to comment this out. Furthermore, make sure this file is ONLY readable for root (''sudo chmod 600''). Finally, remember that the other side of the tunnel needs the EXACT same key - transport it there using a very secure method (like going there in person). If your key gets compromised on the way there, your tunnel is not secure! Now with the data for the tunnel available and the key set up, we can get going on the configuration of the tunnel itself. If you've selected using ''racoon-tool'', read on. If you've chosen ''direct'' (or if you're not on a Debian server but another Linux distribution), skip to the next section. ==Method 1: using ''racoon-tool''== ==Method 2: direct ''racoon'' configuration== To configure ''racoon'' directly, we're going to edit ''/etc/racoon/racoon.conf''. Good practice is to rename the original ''racoon.conf'' to ''racoon.conf.org'', and create a fresh one. The basic file looks like this: # Racoon configuration file path pre_shared_key "/etc/racoon/psk.txt"; path certificate "/etc/racoon/certs"; # logging level: notify or debug log notify; listen { isakmp 212.238.151.172 [500]; isakmp_natt 212.238.151.172 [4500]; } This sets some default options for our Racoon daemon. The lines speak almost for themselves: the path plus filename for the PreShared Keys, the path to the certificates directory, the loglevel, and on which IP addresses and ports should the daemon listen - an in which mode. Normally, you'd only have an ''isakmp'' entry, followed by the public IP address, and the default IKE port (TCP 500). If you want to accomodate other servers behind NAT routers as tunnel endpoints, then you'd need that second entry - it'll make Racoon smart enough to negotiate the IKE phase even though there's a NAT router in between. Now the tunnel-specific stanza's. There are two, and they could look something like this: # # Connection odeonlan # remote 82.161.20.132 500 { proposal { encryption_algorithm 3des; hash_algorithm sha1; authentication_method pre_shared_key; dh_group modp1024; } verify_identifier on; peers_identifier address; exchange_mode main; } sainfo address 192.168.0.0/24[any] any address 192.168.1.0/24[any] any { pfs_group modp1024; encryption_algorithm aes,3des; authentication_algorithm hmac_sha1,hmac_md5; compression_algorithm deflate; } The first stanza describes the parameters with which the IKE phase 1 communication will take place. It says in this example: for the endpoint 82.161.20.132, negotiate IKE over port 500 (since that is the default port number, you could omit the 500). Start the IKE phase 1 negotiations with the following parameters: encrypt communication during IKE with 3des, use sha1 as hashing method, use the PSK file to verify that the other side is really who they claim to be, and use a 1024-bits Diffie-Hellman group. To find out what these parameters mean, we kindly refer you to execute command ''man racoon.conf'', and of course to Internet.<br> The last three statements in the first stanza have the following meaning: * if we want to, we can try to verify if the other side is who we believe it to be. This statement '''verify_identifier on''' turns on this identity check. * to now find out who the other side claims to be, we can look at several identifiers. Here we claim that we want to verify the IP '''address''' of the other side of the tunnel. This ensures the tunnel is not set up between our end and some unknown other server. * the keys must be exchanged between the endpoints in '''main mode''', which requires multiple messages going back and forth, but which ensures that the other side is indeed who they claim to be. This only works if the IP number of the other side is known in advance, as is the case with a server with a fixed internet IP address. This will NOT work if the other side of the tunnel is a roaming client - but since we're using the IP address already as identifier, this is not the case in this example. The second stanza decribes a "security association"; it says that the defined tunnel must be used if the kernel receives a request for IP traffic that matches the SAinfo description. Here the traffic description reads "If you see packets coming from any port on 192.168.0.0/24 in any protocol, and going to any port on 192.168.1.0/24 in any protocol, then that traffic must be encrypted (put through the tunnel) using the parameters specified between the curly brackets. You could use multiple ''sainfo'' stanza's to tunnel multiple types of traffic through the same tunnel. After specifying the tunnel in ''racoon.conf'' we need to restart the Racoon daemon so that it knows about our tunnel: sudo invoke-rc.d racoon restart Furthermore, we want to ensure that Racoon starts when we reboot our server, so we create a symlink in our runlevel directory: ln -s /etc/init.d/racoon /etc/rc2.d/S98racoon ==Extra configuration issues== ===setting the right routes=== ===adapting your firewall configuration=== ===DNS and WINS issues=== =IPsec diagnostics= d7547ab292ff0cec04087331e34f2e275e26f965 2069 2068 2008-12-14T16:10:36Z Saruman! 2 /* Method 2: direct racoon configuration */ added setkey wikitext text/x-wiki =IPsec tunneling theory= IPsec is very powerful, but also quite complicated and intricate. When starting on tunneling, you might want to start exploring the site [http://www.ipsec-howto.org/ ipsec-howto]. It explains both the theory of IPsec, and describes how to create IPsec tunnels. However, after reviewing the theory, you might want to continue here for a more elaborate, Debian-specific, site-to-site only, howto on tunneling. =IPsec site-to-site tunneling= ==IPsec general preparations== First off, you'll have to inventory your prospective tunnel setup. We suggest you fill in the following table (filled here for the purpose of example): {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !width="150" style="background:#ffdead;"|Debian Server !width="150" style="background:#ffdead;"|Data !width="150" style="background:#ffdead;"|Example |- |Name(*) | |dworkin |- |Internet IP | |212.238.151.172 |- |Private IP | |192.168.0.9 |- |Network(s) | |192.168.0.0/24 |- |Default key exchange encryption | |3DES |- |Default tunnel encryption | |3DES |- |} (*) This data is not mandatory, but it makes it easier to reference the machine in question. Next, you'll need to decide if you are going to use the debian-specific tool ''racoon-tool'', or if you're going to configure ''racoon'' directly. If you don't know what the difference is, choosing will be quite hard. So here follows a little description of the tools, and what we see as the consequences of your choice. * [http://www.kame.net/newsletter/20001119/ ''racoon''] is a daemon that can exchange keys with the other end of a prospective IPsec connection in a secure and automated way; it is part of the [http://ipsec-tools.sourceforge.net/ IPsec-tools package]. You are supposed to configure it by means of entering exactly the right data in ''/etc/racoon/racoon.conf''. Using ''racoon'' directly is the "standard" way of setting up an IPsec tunnel * ''racoon-tool'' is a Debian-specific Perl script, that can perform your ''racoon'' configuration for you. Using this means that you're less likely to make typo's etcetera: it's plain easier. On the other hand, since this is Debian-specific, a lot of information on the Internet might get less usable for you, since that assumes you're using plain ''racoon''. This shortcoming is mitigated somewhat by the realization that ''racoon-tool'' generates a ''racoon.conf'' file just as you'd expect, but only in a different location (''/var/lib/racoon/racoon.conf'' instead of ''/etc/racoon/racoon.conf''). But then again, you might want to learn how to make IPsec tunnels in a way that can be used on non-Debian servers as well... We feel there is no compelling general reason to choose one way over the other, so we'll outline both ways here. You'll have to choose, though. Mind you, if you ever change your mind, you can easily switch from direct to ''racoon-tool'' or back by running ''dpkg-reconfigure racoon''... Next, you'll have to verify if your kernel has been compiled with the necessary options. What you need at minimum are the following kernel options, that can be found under ''Networking support > Networking options'': * '''Transformation user configuration interface''': this enables support for the Transformation (XFRM) user configuration interface; IPsec needs this. * '''PF_KEY Sockets''': This option makes your kernel compatible with the KAME IPsec tools that we're going to use. * '''IP: ESP transformation''': This option ensures we can create IPsec networking packets in ESP mode. * '''IP: IPsec tunnel mode''': This option enables the IPsec tunnel mode. * '''IP: IPComp transformation''': Not required, but you'll want this: it enables compression over your IPsec tunnels For IPsec you need several cryptographic algorithms; the mandatory ones are already selected because you set the options above. But if you need or want additional ones (AES, Blowfish etc), then go to ''Cryptographic API'', and select the algorithms you want. We would suggest the following algorithms: * Null algorithms: useful for testing * SHA224 and SHA256 digest algorithm: pretty secure and pretty well supported * Blowfish cipher algorithm: fast and efficient * AES cipher algorithms: AES is a well-known standard, that is still considered pretty secure If you have any other cryptographic need, then most likely you'll have to satisfy it here as well. Then, after the usual compiling and installing of your new or updated kernel, you'll of course have to reboot to be able to use these features. Verify that your Linux server is not sitting behind a NATting device, like an ADSL modem/router. If it is, you'll need an extra feature (NAT-T, or Nat Traversal), not described in this procedure. ==IPsec installation== The amount of software we need to realize an IPsec tunnel is limited, because most of the IPsec capabilities are now integrated in the Linux kernel. The packages we need are: * ''ipsec-tools'', the package that contains the KAME IPsec tools with which we can control the IPsec implementation that's in the Linux kernel; * ''racoon'', the Internet Key Exchange daemon; * ''[[vim]]''(*), an improved version of the ''vi'' editor. (*)Well we don't really need [[vim]], but if we install it, not only will we have a very powerful editor, but also will we be able to use the ''xxd'' command when generating strong encryption keys. When using ''aptitude'' or ''apt-get install'' to install ''racoon'', we'll be asked for the desired "Configuration mode for racoon IKE daemon": direct or racoon-tool. Choose according to your preference. That's it! No additional software is required. Your system is now ready to set up IPsec tunnels - all it requires is the right configuration (and a correctly configured endpoint for the other end of the tunnel). =IPsec site-to-site tunnel configuration= ==IPsec tunnel-specific preparations== When we start creating a tunnel, we need the relevant data for the far side of each tunnel we'll be creating, similar to what we've already gathered for our own side of the tunnel. Note that it is not necessary that the other endpoint is also a Linux server; it could just as well be an IPsec capable appliance like a ''Checkpoint FW1'' firewall or a Microsoft Windows server. The main difference between different endpoints is the set of encryption algorithms they'll be able to support. Therefor, the preferred encryption algorithm must be negotiated between you and your counterpart on the other side of the tunnel. In this example, the other side is a Debian server as well, and we've agreed to use SHA1 as algorithm for both the IKE phase and the actual tunnel. Furthermore, we've agreed on a secret key, needed for the initial IKE phase. {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Debian Server !width="250" style="background:#ffdead;"|Data !style="background:#ffdead;"|Example |- |Name(*) | |darktower |- |Internet IP | |82.161.20.13 |- |Private IP | |192.168.1.10 |- |Network(s) | |192.168.1.0/24 |- |Preferred key exchange encryption | |SHA1 |- |PreShared Key | |0x383a94619b3d6a8f33a39f68b4d16594 |- |Preferred tunnel encryption | |SHA1 |- |} So how do we generate a strong PSK? A quick way would be to execute this command: dd if=/dev/random count=16 bs=1 | xxd -ps This will output a strong key, like ''383a94619b3d6a8f33a39f68b4d16594''; you'll only have to prepend ''0x'' to signify that it's a hexadecimal key. Note that if you do not prepend ''0x'', it will mean that the key will be interpreted as a passphrase instead of a key. No harm there, as long as you do this on ''both'' sides of the tunnel. We must put this key in a key file. To this end, we append the file ''/etc/racoon/psk.txt'' with the following information: # key for tunnel to darktower 82.161.20.13 0x383a94619b3d6a8f33a39f68b4d16594 Note: there is already sample information in this file; it is good practice to comment this out. Furthermore, make sure this file is ONLY readable for root (''sudo chmod 600''). Finally, remember that the other side of the tunnel needs the EXACT same key - transport it there using a very secure method (like going there in person). If your key gets compromised on the way there, your tunnel is not secure! Now with the data for the tunnel available and the key set up, we can get going on the configuration of the tunnel itself. If you've selected using ''racoon-tool'', read on. If you've chosen ''direct'' (or if you're not on a Debian server but another Linux distribution), skip to the next section. ==Method 1: using ''racoon-tool''== ==Method 2: direct ''racoon'' configuration== To configure ''racoon'' directly, we're going to edit ''/etc/racoon/racoon.conf''. If this is the first tunnel you're going to create: good practice is to rename the original ''racoon.conf'' to ''racoon.conf.org'', and create a fresh one. The basic file then looks like this: # Racoon configuration file path pre_shared_key "/etc/racoon/psk.txt"; path certificate "/etc/racoon/certs"; # logging level: notify or debug log notify; listen { isakmp 212.238.151.172 [500]; isakmp_natt 212.238.151.172 [4500]; } This sets some default options for our Racoon daemon. The lines speak almost for themselves: the path plus filename for the PreShared Keys, the path to the certificates directory, the loglevel (error, warning, notify, info, debug or debug2), and on which IP addresses and ports should the daemon listen - an in which mode. Normally, you'd only have an ''isakmp'' entry, followed by the public IP address, and the default IKE port (TCP 500). If you want to accomodate other servers behind NAT routers as tunnel endpoints, then you'd need that second entry - it'll make Racoon smart enough to negotiate the IKE phase even though there's a NAT router in between. Now the tunnel-specific stanza's. There are two, and they could look something like this: # # Connection odeonlan # remote 82.161.20.132 500 { proposal { encryption_algorithm 3des; hash_algorithm sha1; authentication_method pre_shared_key; dh_group modp1024; } verify_identifier on; peers_identifier address; exchange_mode main; } sainfo address 192.168.0.0/24[any] any address 192.168.1.0/24[any] any { pfs_group modp1024; encryption_algorithm aes,3des; authentication_algorithm hmac_sha1,hmac_md5; compression_algorithm deflate; } The first stanza describes the parameters with which the IKE phase 1 communication will take place. It says in this example: for the endpoint 82.161.20.132, negotiate IKE over port 500 (since that is the default port number, you could omit the 500). Start the IKE phase 1 negotiations with the following parameters: encrypt communication during IKE with 3des, use sha1 as hashing method, use the PSK file to verify that the other side is really who they claim to be, and use a 1024-bits Diffie-Hellman group. To find out what these parameters mean, we kindly refer you to execute command ''man racoon.conf'', and of course to Internet.<br> The last three statements in the first stanza have the following meaning: * if we want to, we can try to verify if the other side is who we believe it to be. This statement '''verify_identifier on''' turns on this identity check. * to now find out who the other side claims to be, we can look at several identifiers. Here we claim that we want to verify the IP '''address''' of the other side of the tunnel. This ensures the tunnel is not set up between our end and some unknown other server. * the keys must be exchanged between the endpoints in '''main mode''', which requires multiple messages going back and forth, but which ensures that the other side is indeed who they claim to be. This only works if the IP number of the other side is known in advance, as is the case with a server with a fixed internet IP address. This will NOT work if the other side of the tunnel is a roaming client - but since we're using the IP address already as identifier, this is not the case in this example. The second stanza defines the parameters of the IKE phase 2 (IPsec-SA establishment). It decribes a "security association": the encryption policy or policies for traffic passing through the tunnel. The first line of the stanza gives a description of the traffic that this policy is valid for. Here the traffic description reads "If you see packets entering the tunnel, coming from any port on 192.168.0.0/24 in any protocol, and going to any port on 192.168.1.0/24 in any protocol, then that traffic must be encrypted using the parameters specified between the curly brackets. You could use multiple ''sainfo'' stanza's to tunnel multiple types of traffic through the same tunnel. After specifying the tunnel in ''racoon.conf'' we need to restart the Racoon daemon so that it knows about our tunnel: sudo invoke-rc.d racoon restart Furthermore, we want to ensure that Racoon starts when we reboot our server, so we create a symlink in our runlevel directory: ln -s /etc/init.d/racoon /etc/rc2.d/S98racoon Now we've told the kernel how to encrypt traffic going through the tunnel; however, we haven't yet told the kernel ''what'' traffic to put through ''which'' tunnel. For this, we need a Security Policy (SP), which is stored in the Security Policy Database (SPD). So how do we create and such an SP? We use the utility ''setkey''.<br> Under Debian, we can simply edit ''/etc/ipsec-tools.conf'', and call upon ''/etc/init.d/setkey'' to execute it, e.g. at startup. To this end, we create ''ipsec-tools.conf'' like this: #!/usr/sbin/setkey -f ## Flush the SAD and SPD flush; spdflush; # # Tunnel to Darktower # spdadd 192.168.0.0/24 192.168.1.0/24 any -P out ipsec esp/tunnel/212.238.151.172-82.161.20.132/require; spdadd 192.168.1.0/24 192.168.0.0/24 any -P in ipsec esp/tunnel/82.161.20.132-212.238.151.172/require; In this, we make sure that any call on ''setkey'' results in flushing the SA and SP databases. Then we add the two policies that encrypt and decrypt traffic entering and leaving the tunnel. The first line adds to the SPD a policy for outgoing traffic (''-P out'') to be encrypted (''ipsec'') if that traffic comes from 192.168.0.0/24, goes to 192.168.1.0/24, and is made up of any protocol (''any''). You could limit the use of the tunnel to any protocol that is in the ''/etc/protocol'' file, and/or between different address ranges, and/or particular ports. For example: spdadd 192.168.0.0/24 192.168.1.10[9080] http -P out ipsec esp/tunnel/212.238.151.172-82.161.20.132/require; This policy encrypts all HTTP traffic going to port 9080 on the web server 192.168.1.10. OK, now that we've created the ''setkey'' information, we can have our Debian server create our SPD for us: invoke-rc.d setkey Furthermore, if we want our SPD to be created automatically on startup, we can create the appropriate symlink: ln -s /etc/init.d/setkey /etc/rc2.d/S98setkey ==Extra configuration issues== ===setting the right routes=== ===adapting your firewall configuration=== ===DNS and WINS issues=== =IPsec diagnostics= f392ec49d71913fcdb57d9e650cd8d0d054d6a3a 2070 2069 2008-12-14T16:33:11Z Saruman! 2 /* Extra configuration issues */ routing and firewalling explained wikitext text/x-wiki =IPsec tunneling theory= IPsec is very powerful, but also quite complicated and intricate. When starting on tunneling, you might want to start exploring the site [http://www.ipsec-howto.org/ ipsec-howto]. It explains both the theory of IPsec, and describes how to create IPsec tunnels. However, after reviewing the theory, you might want to continue here for a more elaborate, Debian-specific, site-to-site only, howto on tunneling. =IPsec site-to-site tunneling= ==IPsec general preparations== First off, you'll have to inventory your prospective tunnel setup. We suggest you fill in the following table (filled here for the purpose of example): {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !width="150" style="background:#ffdead;"|Debian Server !width="150" style="background:#ffdead;"|Data !width="150" style="background:#ffdead;"|Example |- |Name(*) | |dworkin |- |Internet IP | |212.238.151.172 |- |Private IP | |192.168.0.9 |- |Network(s) | |192.168.0.0/24 |- |Default key exchange encryption | |3DES |- |Default tunnel encryption | |3DES |- |} (*) This data is not mandatory, but it makes it easier to reference the machine in question. Next, you'll need to decide if you are going to use the debian-specific tool ''racoon-tool'', or if you're going to configure ''racoon'' directly. If you don't know what the difference is, choosing will be quite hard. So here follows a little description of the tools, and what we see as the consequences of your choice. * [http://www.kame.net/newsletter/20001119/ ''racoon''] is a daemon that can exchange keys with the other end of a prospective IPsec connection in a secure and automated way; it is part of the [http://ipsec-tools.sourceforge.net/ IPsec-tools package]. You are supposed to configure it by means of entering exactly the right data in ''/etc/racoon/racoon.conf''. Using ''racoon'' directly is the "standard" way of setting up an IPsec tunnel * ''racoon-tool'' is a Debian-specific Perl script, that can perform your ''racoon'' configuration for you. Using this means that you're less likely to make typo's etcetera: it's plain easier. On the other hand, since this is Debian-specific, a lot of information on the Internet might get less usable for you, since that assumes you're using plain ''racoon''. This shortcoming is mitigated somewhat by the realization that ''racoon-tool'' generates a ''racoon.conf'' file just as you'd expect, but only in a different location (''/var/lib/racoon/racoon.conf'' instead of ''/etc/racoon/racoon.conf''). But then again, you might want to learn how to make IPsec tunnels in a way that can be used on non-Debian servers as well... We feel there is no compelling general reason to choose one way over the other, so we'll outline both ways here. You'll have to choose, though. Mind you, if you ever change your mind, you can easily switch from direct to ''racoon-tool'' or back by running ''dpkg-reconfigure racoon''... Next, you'll have to verify if your kernel has been compiled with the necessary options. What you need at minimum are the following kernel options, that can be found under ''Networking support > Networking options'': * '''Transformation user configuration interface''': this enables support for the Transformation (XFRM) user configuration interface; IPsec needs this. * '''PF_KEY Sockets''': This option makes your kernel compatible with the KAME IPsec tools that we're going to use. * '''IP: ESP transformation''': This option ensures we can create IPsec networking packets in ESP mode. * '''IP: IPsec tunnel mode''': This option enables the IPsec tunnel mode. * '''IP: IPComp transformation''': Not required, but you'll want this: it enables compression over your IPsec tunnels For IPsec you need several cryptographic algorithms; the mandatory ones are already selected because you set the options above. But if you need or want additional ones (AES, Blowfish etc), then go to ''Cryptographic API'', and select the algorithms you want. We would suggest the following algorithms: * Null algorithms: useful for testing * SHA224 and SHA256 digest algorithm: pretty secure and pretty well supported * Blowfish cipher algorithm: fast and efficient * AES cipher algorithms: AES is a well-known standard, that is still considered pretty secure If you have any other cryptographic need, then most likely you'll have to satisfy it here as well. Then, after the usual compiling and installing of your new or updated kernel, you'll of course have to reboot to be able to use these features. Verify that your Linux server is not sitting behind a NATting device, like an ADSL modem/router. If it is, you'll need an extra feature (NAT-T, or Nat Traversal), not described in this procedure. ==IPsec installation== The amount of software we need to realize an IPsec tunnel is limited, because most of the IPsec capabilities are now integrated in the Linux kernel. The packages we need are: * ''ipsec-tools'', the package that contains the KAME IPsec tools with which we can control the IPsec implementation that's in the Linux kernel; * ''racoon'', the Internet Key Exchange daemon; * ''[[vim]]''(*), an improved version of the ''vi'' editor. (*)Well we don't really need [[vim]], but if we install it, not only will we have a very powerful editor, but also will we be able to use the ''xxd'' command when generating strong encryption keys. When using ''aptitude'' or ''apt-get install'' to install ''racoon'', we'll be asked for the desired "Configuration mode for racoon IKE daemon": direct or racoon-tool. Choose according to your preference. That's it! No additional software is required. Your system is now ready to set up IPsec tunnels - all it requires is the right configuration (and a correctly configured endpoint for the other end of the tunnel). =IPsec site-to-site tunnel configuration= ==IPsec tunnel-specific preparations== When we start creating a tunnel, we need the relevant data for the far side of each tunnel we'll be creating, similar to what we've already gathered for our own side of the tunnel. Note that it is not necessary that the other endpoint is also a Linux server; it could just as well be an IPsec capable appliance like a ''Checkpoint FW1'' firewall or a Microsoft Windows server. The main difference between different endpoints is the set of encryption algorithms they'll be able to support. Therefor, the preferred encryption algorithm must be negotiated between you and your counterpart on the other side of the tunnel. In this example, the other side is a Debian server as well, and we've agreed to use SHA1 as algorithm for both the IKE phase and the actual tunnel. Furthermore, we've agreed on a secret key, needed for the initial IKE phase. {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Debian Server !width="250" style="background:#ffdead;"|Data !style="background:#ffdead;"|Example |- |Name(*) | |darktower |- |Internet IP | |82.161.20.13 |- |Private IP | |192.168.1.10 |- |Network(s) | |192.168.1.0/24 |- |Preferred key exchange encryption | |SHA1 |- |PreShared Key | |0x383a94619b3d6a8f33a39f68b4d16594 |- |Preferred tunnel encryption | |SHA1 |- |} So how do we generate a strong PSK? A quick way would be to execute this command: dd if=/dev/random count=16 bs=1 | xxd -ps This will output a strong key, like ''383a94619b3d6a8f33a39f68b4d16594''; you'll only have to prepend ''0x'' to signify that it's a hexadecimal key. Note that if you do not prepend ''0x'', it will mean that the key will be interpreted as a passphrase instead of a key. No harm there, as long as you do this on ''both'' sides of the tunnel. We must put this key in a key file. To this end, we append the file ''/etc/racoon/psk.txt'' with the following information: # key for tunnel to darktower 82.161.20.13 0x383a94619b3d6a8f33a39f68b4d16594 Note: there is already sample information in this file; it is good practice to comment this out. Furthermore, make sure this file is ONLY readable for root (''sudo chmod 600''). Finally, remember that the other side of the tunnel needs the EXACT same key - transport it there using a very secure method (like going there in person). If your key gets compromised on the way there, your tunnel is not secure! Now with the data for the tunnel available and the key set up, we can get going on the configuration of the tunnel itself. If you've selected using ''racoon-tool'', read on. If you've chosen ''direct'' (or if you're not on a Debian server but another Linux distribution), skip to the next section. ==Method 1: using ''racoon-tool''== ==Method 2: direct ''racoon'' configuration== To configure ''racoon'' directly, we're going to edit ''/etc/racoon/racoon.conf''. If this is the first tunnel you're going to create: good practice is to rename the original ''racoon.conf'' to ''racoon.conf.org'', and create a fresh one. The basic file then looks like this: # Racoon configuration file path pre_shared_key "/etc/racoon/psk.txt"; path certificate "/etc/racoon/certs"; # logging level: notify or debug log notify; listen { isakmp 212.238.151.172 [500]; isakmp_natt 212.238.151.172 [4500]; } This sets some default options for our Racoon daemon. The lines speak almost for themselves: the path plus filename for the PreShared Keys, the path to the certificates directory, the loglevel (error, warning, notify, info, debug or debug2), and on which IP addresses and ports should the daemon listen - an in which mode. Normally, you'd only have an ''isakmp'' entry, followed by the public IP address, and the default IKE port (TCP 500). If you want to accomodate other servers behind NAT routers as tunnel endpoints, then you'd need that second entry - it'll make Racoon smart enough to negotiate the IKE phase even though there's a NAT router in between. Now the tunnel-specific stanza's. There are two, and they could look something like this: # # Connection odeonlan # remote 82.161.20.132 500 { proposal { encryption_algorithm 3des; hash_algorithm sha1; authentication_method pre_shared_key; dh_group modp1024; } verify_identifier on; peers_identifier address; exchange_mode main; } sainfo address 192.168.0.0/24[any] any address 192.168.1.0/24[any] any { pfs_group modp1024; encryption_algorithm aes,3des; authentication_algorithm hmac_sha1,hmac_md5; compression_algorithm deflate; } The first stanza describes the parameters with which the IKE phase 1 communication will take place. It says in this example: for the endpoint 82.161.20.132, negotiate IKE over port 500 (since that is the default port number, you could omit the 500). Start the IKE phase 1 negotiations with the following parameters: encrypt communication during IKE with 3des, use sha1 as hashing method, use the PSK file to verify that the other side is really who they claim to be, and use a 1024-bits Diffie-Hellman group. To find out what these parameters mean, we kindly refer you to execute command ''man racoon.conf'', and of course to Internet.<br> The last three statements in the first stanza have the following meaning: * if we want to, we can try to verify if the other side is who we believe it to be. This statement '''verify_identifier on''' turns on this identity check. * to now find out who the other side claims to be, we can look at several identifiers. Here we claim that we want to verify the IP '''address''' of the other side of the tunnel. This ensures the tunnel is not set up between our end and some unknown other server. * the keys must be exchanged between the endpoints in '''main mode''', which requires multiple messages going back and forth, but which ensures that the other side is indeed who they claim to be. This only works if the IP number of the other side is known in advance, as is the case with a server with a fixed internet IP address. This will NOT work if the other side of the tunnel is a roaming client - but since we're using the IP address already as identifier, this is not the case in this example. The second stanza defines the parameters of the IKE phase 2 (IPsec-SA establishment). It decribes a "security association": the encryption policy or policies for traffic passing through the tunnel. The first line of the stanza gives a description of the traffic that this policy is valid for. Here the traffic description reads "If you see packets entering the tunnel, coming from any port on 192.168.0.0/24 in any protocol, and going to any port on 192.168.1.0/24 in any protocol, then that traffic must be encrypted using the parameters specified between the curly brackets. You could use multiple ''sainfo'' stanza's to tunnel multiple types of traffic through the same tunnel. After specifying the tunnel in ''racoon.conf'' we need to restart the Racoon daemon so that it knows about our tunnel: sudo invoke-rc.d racoon restart Furthermore, we want to ensure that Racoon starts when we reboot our server, so we create a symlink in our runlevel directory: ln -s /etc/init.d/racoon /etc/rc2.d/S98racoon Now we've told the kernel how to encrypt traffic going through the tunnel; however, we haven't yet told the kernel ''what'' traffic to put through ''which'' tunnel. For this, we need a Security Policy (SP), which is stored in the Security Policy Database (SPD). So how do we create and such an SP? We use the utility ''setkey''.<br> Under Debian, we can simply edit ''/etc/ipsec-tools.conf'', and call upon ''/etc/init.d/setkey'' to execute it, e.g. at startup. To this end, we create ''ipsec-tools.conf'' like this: #!/usr/sbin/setkey -f ## Flush the SAD and SPD flush; spdflush; # # Tunnel to Darktower # spdadd 192.168.0.0/24 192.168.1.0/24 any -P out ipsec esp/tunnel/212.238.151.172-82.161.20.132/require; spdadd 192.168.1.0/24 192.168.0.0/24 any -P in ipsec esp/tunnel/82.161.20.132-212.238.151.172/require; In this, we make sure that any call on ''setkey'' results in flushing the SA and SP databases. Then we add the two policies that encrypt and decrypt traffic entering and leaving the tunnel. The first line adds to the SPD a policy for outgoing traffic (''-P out'') to be encrypted (''ipsec'') if that traffic comes from 192.168.0.0/24, goes to 192.168.1.0/24, and is made up of any protocol (''any''). You could limit the use of the tunnel to any protocol that is in the ''/etc/protocol'' file, and/or between different address ranges, and/or particular ports. For example: spdadd 192.168.0.0/24 192.168.1.10[9080] http -P out ipsec esp/tunnel/212.238.151.172-82.161.20.132/require; This policy encrypts all HTTP traffic going to port 9080 on the web server 192.168.1.10. OK, now that we've created the ''setkey'' information, we can have our Debian server create our SPD for us: invoke-rc.d setkey Furthermore, if we want our SPD to be created automatically on startup, we can create the appropriate symlink: ln -s /etc/init.d/setkey /etc/rc2.d/S98setkey ==Extra configuration issues== Maybe after all that complicated configuration work on ''setkey'' and ''racoon'' you thought you had a working tunnel? Well you have indeed, but that does not necessarily mean you can also use it. Two issues might need to be tackled, before your tunnel actually works. ===setting the right routes=== We might have told the kernel how to encapsulate and encrypt traffic from our network to the other one, and vice versa, but probably no traffic will by itself go that way. That is because we haven't added the ''route'' from our network to the other side to the routing table. So this is something we now have to do. When we want to reach the remote network (here: ''192.168.1.0/24'', we need to send it to our public IP interface, and make sure that our routing engine uses our server's private IP as the router source address. This way, we can reach the remote network not only from our local network, but also from our router itself. A means to enter this route would be to execute this command: ip route add 192.168.1.0/24 via 212.238.151.172 src 192.168.0.9 To make sure that this route is available on startup of your server, make it [[Networking_section#Manipulating_persistent_routes | persistent]]. ===adapting your firewall configuration=== It's nice to have a tunnel that carries traffic; it's nice to have a firewall filtering your network traffic; it's not so nice if your firewall is blocking the traffic that is supposed to go over your tunnel. It depends on which firewall you use, but you should make sure there are rules in place that allow the outgoing traffic that you want to enter, and incoming traffic that you want to allow to leave the tunnel. A piece of IPtables firewall scripting could look like this: # define all necessary variables LocalLAN[1]='192.168.0.0/24' # the LAN segment we're prepared to open PublicIP[1]='212.238.151.172' # Our own external IP for this connection RemoteLAN[1]='192.168.1.0/24' # the remote LAN segment we wanna reach RemoteIP[1]='82.161.20.13' # the public IP of the remote gateway # open IKE port between us and them, in and out iptables -A INPUT -p udp -s ${RemoteIP[1]} --sport 500 --dport 500 -j ACCEPT iptables -A OUTPUT -p udp -d ${RemoteIP[1]} --sport 500 --dport 500 -j ACCEPT # Pass network traffic through the NAT tables iptables -t nat -A PREROUTING -s ${RemoteLAN[1]} -d ${LocalLAN[1]} -j ACCEPT iptables -t nat -A POSTROUTING -s ${LocalLAN[1]} -d ${RemoteLAN[1]} -j ACCEPT # Pass network traffic over the tunnel through the filter tables iptables -A FORWARD -s ${RemoteLAN[1]} -d ${LocalLAN[1]} -j ACCEPT iptables -A FORWARD -s ${LocalLAN[1]} -d ${RemoteLAN[1]} -j ACCEPT And of course, if you want to use Netfilter to filter out additional traffic ''inside'' of the tunnel, you can make rules for that as well, instead of those last two lines. A note of caution: if you use your Linux server as a NAT router itself, and/or if you have other reasons to have DNAT and SNAT rules in your firewall, make sure that the PREROUTING and POSTROUTING lines shown above appear BEFORE those DNAT and SNAT lines. If not, then your tunnel packages get NATted before the IPsec policy kicks in, and your kernel will not recognise them as packages that need to be tunneled. =IPsec diagnostics= bb64f71cc0d30812593ed9bf5d1cd7cf40e16b89 2075 2070 2008-12-17T19:38:11Z Saruman! 2 /* IPsec diagnostics */ added link to the actual page wikitext text/x-wiki =IPsec tunneling theory= IPsec is very powerful, but also quite complicated and intricate. When starting on tunneling, you might want to start exploring the site [http://www.ipsec-howto.org/ ipsec-howto]. It explains both the theory of IPsec, and describes how to create IPsec tunnels. However, after reviewing the theory, you might want to continue here for a more elaborate, Debian-specific, site-to-site only, howto on tunneling. =IPsec site-to-site tunneling= ==IPsec general preparations== First off, you'll have to inventory your prospective tunnel setup. We suggest you fill in the following table (filled here for the purpose of example): {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !width="150" style="background:#ffdead;"|Debian Server !width="150" style="background:#ffdead;"|Data !width="150" style="background:#ffdead;"|Example |- |Name(*) | |dworkin |- |Internet IP | |212.238.151.172 |- |Private IP | |192.168.0.9 |- |Network(s) | |192.168.0.0/24 |- |Default key exchange encryption | |3DES |- |Default tunnel encryption | |3DES |- |} (*) This data is not mandatory, but it makes it easier to reference the machine in question. Next, you'll need to decide if you are going to use the debian-specific tool ''racoon-tool'', or if you're going to configure ''racoon'' directly. If you don't know what the difference is, choosing will be quite hard. So here follows a little description of the tools, and what we see as the consequences of your choice. * [http://www.kame.net/newsletter/20001119/ ''racoon''] is a daemon that can exchange keys with the other end of a prospective IPsec connection in a secure and automated way; it is part of the [http://ipsec-tools.sourceforge.net/ IPsec-tools package]. You are supposed to configure it by means of entering exactly the right data in ''/etc/racoon/racoon.conf''. Using ''racoon'' directly is the "standard" way of setting up an IPsec tunnel * ''racoon-tool'' is a Debian-specific Perl script, that can perform your ''racoon'' configuration for you. Using this means that you're less likely to make typo's etcetera: it's plain easier. On the other hand, since this is Debian-specific, a lot of information on the Internet might get less usable for you, since that assumes you're using plain ''racoon''. This shortcoming is mitigated somewhat by the realization that ''racoon-tool'' generates a ''racoon.conf'' file just as you'd expect, but only in a different location (''/var/lib/racoon/racoon.conf'' instead of ''/etc/racoon/racoon.conf''). But then again, you might want to learn how to make IPsec tunnels in a way that can be used on non-Debian servers as well... We feel there is no compelling general reason to choose one way over the other, so we'll outline both ways here. You'll have to choose, though. Mind you, if you ever change your mind, you can easily switch from direct to ''racoon-tool'' or back by running ''dpkg-reconfigure racoon''... Next, you'll have to verify if your kernel has been compiled with the necessary options. What you need at minimum are the following kernel options, that can be found under ''Networking support > Networking options'': * '''Transformation user configuration interface''': this enables support for the Transformation (XFRM) user configuration interface; IPsec needs this. * '''PF_KEY Sockets''': This option makes your kernel compatible with the KAME IPsec tools that we're going to use. * '''IP: ESP transformation''': This option ensures we can create IPsec networking packets in ESP mode. * '''IP: IPsec tunnel mode''': This option enables the IPsec tunnel mode. * '''IP: IPComp transformation''': Not required, but you'll want this: it enables compression over your IPsec tunnels For IPsec you need several cryptographic algorithms; the mandatory ones are already selected because you set the options above. But if you need or want additional ones (AES, Blowfish etc), then go to ''Cryptographic API'', and select the algorithms you want. We would suggest the following algorithms: * Null algorithms: useful for testing * SHA224 and SHA256 digest algorithm: pretty secure and pretty well supported * Blowfish cipher algorithm: fast and efficient * AES cipher algorithms: AES is a well-known standard, that is still considered pretty secure If you have any other cryptographic need, then most likely you'll have to satisfy it here as well. Then, after the usual compiling and installing of your new or updated kernel, you'll of course have to reboot to be able to use these features. Verify that your Linux server is not sitting behind a NATting device, like an ADSL modem/router. If it is, you'll need an extra feature (NAT-T, or Nat Traversal), not described in this procedure. ==IPsec installation== The amount of software we need to realize an IPsec tunnel is limited, because most of the IPsec capabilities are now integrated in the Linux kernel. The packages we need are: * ''ipsec-tools'', the package that contains the KAME IPsec tools with which we can control the IPsec implementation that's in the Linux kernel; * ''racoon'', the Internet Key Exchange daemon; * ''[[vim]]''(*), an improved version of the ''vi'' editor. (*)Well we don't really need [[vim]], but if we install it, not only will we have a very powerful editor, but also will we be able to use the ''xxd'' command when generating strong encryption keys. When using ''aptitude'' or ''apt-get install'' to install ''racoon'', we'll be asked for the desired "Configuration mode for racoon IKE daemon": direct or racoon-tool. Choose according to your preference. That's it! No additional software is required. Your system is now ready to set up IPsec tunnels - all it requires is the right configuration (and a correctly configured endpoint for the other end of the tunnel). =IPsec site-to-site tunnel configuration= ==IPsec tunnel-specific preparations== When we start creating a tunnel, we need the relevant data for the far side of each tunnel we'll be creating, similar to what we've already gathered for our own side of the tunnel. Note that it is not necessary that the other endpoint is also a Linux server; it could just as well be an IPsec capable appliance like a ''Checkpoint FW1'' firewall or a Microsoft Windows server. The main difference between different endpoints is the set of encryption algorithms they'll be able to support. Therefor, the preferred encryption algorithm must be negotiated between you and your counterpart on the other side of the tunnel. In this example, the other side is a Debian server as well, and we've agreed to use SHA1 as algorithm for both the IKE phase and the actual tunnel. Furthermore, we've agreed on a secret key, needed for the initial IKE phase. {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Debian Server !width="250" style="background:#ffdead;"|Data !style="background:#ffdead;"|Example |- |Name(*) | |darktower |- |Internet IP | |82.161.20.13 |- |Private IP | |192.168.1.10 |- |Network(s) | |192.168.1.0/24 |- |Preferred key exchange encryption | |SHA1 |- |PreShared Key | |0x383a94619b3d6a8f33a39f68b4d16594 |- |Preferred tunnel encryption | |SHA1 |- |} So how do we generate a strong PSK? A quick way would be to execute this command: dd if=/dev/random count=16 bs=1 | xxd -ps This will output a strong key, like ''383a94619b3d6a8f33a39f68b4d16594''; you'll only have to prepend ''0x'' to signify that it's a hexadecimal key. Note that if you do not prepend ''0x'', it will mean that the key will be interpreted as a passphrase instead of a key. No harm there, as long as you do this on ''both'' sides of the tunnel. We must put this key in a key file. To this end, we append the file ''/etc/racoon/psk.txt'' with the following information: # key for tunnel to darktower 82.161.20.13 0x383a94619b3d6a8f33a39f68b4d16594 Note: there is already sample information in this file; it is good practice to comment this out. Furthermore, make sure this file is ONLY readable for root (''sudo chmod 600''). Finally, remember that the other side of the tunnel needs the EXACT same key - transport it there using a very secure method (like going there in person). If your key gets compromised on the way there, your tunnel is not secure! Now with the data for the tunnel available and the key set up, we can get going on the configuration of the tunnel itself. If you've selected using ''racoon-tool'', read on. If you've chosen ''direct'' (or if you're not on a Debian server but another Linux distribution), skip to the next section. ==Method 1: using ''racoon-tool''== ==Method 2: direct ''racoon'' configuration== To configure ''racoon'' directly, we're going to edit ''/etc/racoon/racoon.conf''. If this is the first tunnel you're going to create: good practice is to rename the original ''racoon.conf'' to ''racoon.conf.org'', and create a fresh one. The basic file then looks like this: # Racoon configuration file path pre_shared_key "/etc/racoon/psk.txt"; path certificate "/etc/racoon/certs"; # logging level: notify or debug log notify; listen { isakmp 212.238.151.172 [500]; isakmp_natt 212.238.151.172 [4500]; } This sets some default options for our Racoon daemon. The lines speak almost for themselves: the path plus filename for the PreShared Keys, the path to the certificates directory, the loglevel (error, warning, notify, info, debug or debug2), and on which IP addresses and ports should the daemon listen - an in which mode. Normally, you'd only have an ''isakmp'' entry, followed by the public IP address, and the default IKE port (TCP 500). If you want to accomodate other servers behind NAT routers as tunnel endpoints, then you'd need that second entry - it'll make Racoon smart enough to negotiate the IKE phase even though there's a NAT router in between. Now the tunnel-specific stanza's. There are two, and they could look something like this: # # Connection odeonlan # remote 82.161.20.132 500 { proposal { encryption_algorithm 3des; hash_algorithm sha1; authentication_method pre_shared_key; dh_group modp1024; } verify_identifier on; peers_identifier address; exchange_mode main; } sainfo address 192.168.0.0/24[any] any address 192.168.1.0/24[any] any { pfs_group modp1024; encryption_algorithm aes,3des; authentication_algorithm hmac_sha1,hmac_md5; compression_algorithm deflate; } The first stanza describes the parameters with which the IKE phase 1 communication will take place. It says in this example: for the endpoint 82.161.20.132, negotiate IKE over port 500 (since that is the default port number, you could omit the 500). Start the IKE phase 1 negotiations with the following parameters: encrypt communication during IKE with 3des, use sha1 as hashing method, use the PSK file to verify that the other side is really who they claim to be, and use a 1024-bits Diffie-Hellman group. To find out what these parameters mean, we kindly refer you to execute command ''man racoon.conf'', and of course to Internet.<br> The last three statements in the first stanza have the following meaning: * if we want to, we can try to verify if the other side is who we believe it to be. This statement '''verify_identifier on''' turns on this identity check. * to now find out who the other side claims to be, we can look at several identifiers. Here we claim that we want to verify the IP '''address''' of the other side of the tunnel. This ensures the tunnel is not set up between our end and some unknown other server. * the keys must be exchanged between the endpoints in '''main mode''', which requires multiple messages going back and forth, but which ensures that the other side is indeed who they claim to be. This only works if the IP number of the other side is known in advance, as is the case with a server with a fixed internet IP address. This will NOT work if the other side of the tunnel is a roaming client - but since we're using the IP address already as identifier, this is not the case in this example. The second stanza defines the parameters of the IKE phase 2 (IPsec-SA establishment). It decribes a "security association": the encryption policy or policies for traffic passing through the tunnel. The first line of the stanza gives a description of the traffic that this policy is valid for. Here the traffic description reads "If you see packets entering the tunnel, coming from any port on 192.168.0.0/24 in any protocol, and going to any port on 192.168.1.0/24 in any protocol, then that traffic must be encrypted using the parameters specified between the curly brackets. You could use multiple ''sainfo'' stanza's to tunnel multiple types of traffic through the same tunnel. After specifying the tunnel in ''racoon.conf'' we need to restart the Racoon daemon so that it knows about our tunnel: sudo invoke-rc.d racoon restart Furthermore, we want to ensure that Racoon starts when we reboot our server, so we create a symlink in our runlevel directory: ln -s /etc/init.d/racoon /etc/rc2.d/S98racoon Now we've told the kernel how to encrypt traffic going through the tunnel; however, we haven't yet told the kernel ''what'' traffic to put through ''which'' tunnel. For this, we need a Security Policy (SP), which is stored in the Security Policy Database (SPD). So how do we create and such an SP? We use the utility ''setkey''.<br> Under Debian, we can simply edit ''/etc/ipsec-tools.conf'', and call upon ''/etc/init.d/setkey'' to execute it, e.g. at startup. To this end, we create ''ipsec-tools.conf'' like this: #!/usr/sbin/setkey -f ## Flush the SAD and SPD flush; spdflush; # # Tunnel to Darktower # spdadd 192.168.0.0/24 192.168.1.0/24 any -P out ipsec esp/tunnel/212.238.151.172-82.161.20.132/require; spdadd 192.168.1.0/24 192.168.0.0/24 any -P in ipsec esp/tunnel/82.161.20.132-212.238.151.172/require; In this, we make sure that any call on ''setkey'' results in flushing the SA and SP databases. Then we add the two policies that encrypt and decrypt traffic entering and leaving the tunnel. The first line adds to the SPD a policy for outgoing traffic (''-P out'') to be encrypted (''ipsec'') if that traffic comes from 192.168.0.0/24, goes to 192.168.1.0/24, and is made up of any protocol (''any''). You could limit the use of the tunnel to any protocol that is in the ''/etc/protocol'' file, and/or between different address ranges, and/or particular ports. For example: spdadd 192.168.0.0/24 192.168.1.10[9080] http -P out ipsec esp/tunnel/212.238.151.172-82.161.20.132/require; This policy encrypts all HTTP traffic going to port 9080 on the web server 192.168.1.10. OK, now that we've created the ''setkey'' information, we can have our Debian server create our SPD for us: invoke-rc.d setkey Furthermore, if we want our SPD to be created automatically on startup, we can create the appropriate symlink: ln -s /etc/init.d/setkey /etc/rc2.d/S98setkey ==Extra configuration issues== Maybe after all that complicated configuration work on ''setkey'' and ''racoon'' you thought you had a working tunnel? Well you have indeed, but that does not necessarily mean you can also use it. Two issues might need to be tackled, before your tunnel actually works. ===setting the right routes=== We might have told the kernel how to encapsulate and encrypt traffic from our network to the other one, and vice versa, but probably no traffic will by itself go that way. That is because we haven't added the ''route'' from our network to the other side to the routing table. So this is something we now have to do. When we want to reach the remote network (here: ''192.168.1.0/24'', we need to send it to our public IP interface, and make sure that our routing engine uses our server's private IP as the router source address. This way, we can reach the remote network not only from our local network, but also from our router itself. A means to enter this route would be to execute this command: ip route add 192.168.1.0/24 via 212.238.151.172 src 192.168.0.9 To make sure that this route is available on startup of your server, make it [[Networking_section#Manipulating_persistent_routes | persistent]]. ===adapting your firewall configuration=== It's nice to have a tunnel that carries traffic; it's nice to have a firewall filtering your network traffic; it's not so nice if your firewall is blocking the traffic that is supposed to go over your tunnel. It depends on which firewall you use, but you should make sure there are rules in place that allow the outgoing traffic that you want to enter, and incoming traffic that you want to allow to leave the tunnel. A piece of IPtables firewall scripting could look like this: # define all necessary variables LocalLAN[1]='192.168.0.0/24' # the LAN segment we're prepared to open PublicIP[1]='212.238.151.172' # Our own external IP for this connection RemoteLAN[1]='192.168.1.0/24' # the remote LAN segment we wanna reach RemoteIP[1]='82.161.20.13' # the public IP of the remote gateway # open IKE port between us and them, in and out iptables -A INPUT -p udp -s ${RemoteIP[1]} --sport 500 --dport 500 -j ACCEPT iptables -A OUTPUT -p udp -d ${RemoteIP[1]} --sport 500 --dport 500 -j ACCEPT # Pass network traffic through the NAT tables iptables -t nat -A PREROUTING -s ${RemoteLAN[1]} -d ${LocalLAN[1]} -j ACCEPT iptables -t nat -A POSTROUTING -s ${LocalLAN[1]} -d ${RemoteLAN[1]} -j ACCEPT # Pass network traffic over the tunnel through the filter tables iptables -A FORWARD -s ${RemoteLAN[1]} -d ${LocalLAN[1]} -j ACCEPT iptables -A FORWARD -s ${LocalLAN[1]} -d ${RemoteLAN[1]} -j ACCEPT And of course, if you want to use Netfilter to filter out additional traffic ''inside'' of the tunnel, you can make rules for that as well, instead of those last two lines. A note of caution: if you use your Linux server as a NAT router itself, and/or if you have other reasons to have DNAT and SNAT rules in your firewall, make sure that the PREROUTING and POSTROUTING lines shown above appear BEFORE those DNAT and SNAT lines. If not, then your tunnel packages get NATted before the IPsec policy kicks in, and your kernel will not recognise them as packages that need to be tunneled. =IPsec diagnostics= When creating tunnels, ''everything'' has to be ''just'' perfect, or the tunnel won't work ''at all''. However, rarely ever does one get everything perfect at the first go. Thus, when creating tunnels, you heavily depend on the right diagnostic skills and tools. We've described these in a separate page: the [[IPsec tunneling diagnostics]] page. c9503a707c96ce80f77c5ae3cfdce179016fc452 0 1498 2076 2008-12-17T19:41:01Z Saruman! 2 Page structure created wikitext text/x-wiki =Basic connectivity between tunnel endpoints= =Basic diagnostics for configuration files= =IKE diagnostics= =Judging policy and SA database content= =Firewalls and routing= 84d439f0b3ca8113af8add86a1f81603177d840e 2077 2076 2008-12-17T19:54:59Z Saruman! 2 kernel params inserted wikitext text/x-wiki =Basic connectivity between tunnel endpoints= Naturally, we won't be able to create a tunnel if the endpoints cannot reach each other in the first place. Therefor: * Try if the two end points can ping each other. Beware of firewalls on the endpoints (or in between) that block ICMP echo requests or echo replies. * Also, the machines on both sides should have no connection troubles between themselves and the local endpoint. Slightly more specific: your PC's on your local site should be able to ping the server that'll be your local tunnel endpoint. =Basic diagnostics for configuration files= If the tunnel doesn't work, then the first thing to check is the configuration files. All the following files should match * Your kernel should be compiled with the right parameters. Get the configuration file for your kernel. If you've compiled your own kernel, it's probably in ''/usr/src/linux-2.6.x.y/.config'' (with x and y of course kernel version numbers, like 2.6.27.5). If you use the stock Debian kernel, then you'll find the kernel configuration file under ''/boot'' as a file with a name like ''config-2.6.26.1-amd64''. Check these with an [[vim | editor]] for the following kernel options (verified on a vanilla 2.6.27.5 kernel): ** CONFIG_NET_KEY=y ** CONFIG_INET_ESP=y ** CONFIG_INET_AH=y ** CONFIG_INET_XFRM_MODE_TRANSPORT=y ** CONFIG_INET_XFRM_MODE_TUNNEL=y ** CONFIG_INET_IPCOMP=y =IKE diagnostics= =Judging policy and SA database content= =Firewalls and routing= 69e18694891b338c305ddebe866a2dd393ebae7e 0 1489 2090 1979 2009-01-04T17:12:15Z Saruman! 2 /* Configuring mail delivery through Dovecot LDA */ added SSL wikitext text/x-wiki ==E-mail server setup== What we want to accomplish here is the setup of a mail server with the following properties: * can serve multiple mail domains * can relay mail for other domains to other mail servers * can have one or more mailboxes per domain * users of these mailboxes can be virtual (do not need to have a Linux user account) * can have multiple aliases per mailbox * can forward mail for certain aliases to multiple mailboxes For this type of mail server setup, we owe a great thankyou to [http://workaround.org/articles/ispmail-etch/ Christoph Haas], whose advise has helped us create flexible and reliable mail servers since 2003. ==Preparation== We'll assume that the server currently has no mailserver installed, at least no other than the default ''exim'' mailserver. Furthermore, the server is already fitted with MySQL, and this database is running without problems. The hostname of the server must be set correctly, so that ''hostname -f'' returns a valid DNS name, like ''lighthouse.saruman.biz.''. It might also be an internal name like ''lighthouse.saruman.lan.'' but that will require us to give extra attention to the name under which Postfix will contact its collegues on the Internet. Also, the server can correctly [Networking_section#DNS_resolution_under_Debian | resolve DNS names] like [http://www.debian.org www.debian.org], preferably by running it's own caching DNS server. The server is kept on the correct date and time using NTP, TCP port 25 is open on the server, the ISP will allow connections from Internet to this port, and if there's a firewall running on this server, then it has port 25 open so as to not block incoming e-mail. ==Software installation== As a first step, we use [[APT and aptitude|apt or aptitude]] to make sure that our server is up-to-date. Then we can install the necessary software packages. Under Debian 5.0 "Lenny", the (single) packages is: * ''postfix'', the mail server itself - this includes the "virtual package" postfix-tls, that we want to use to secure connections to Postfix with the TLS protocol At the same time we can - and must - purge the following packages: * exim4 * exim4-base * exim4-daemon-light * exim4-config In ''aptitude'', only press "go" when you've marked all four of these packages "purge", or you cannot install postfix. When installing the postfix package, the Debian installer script will ask you several questions, which you can answer like this: * General type of mail configuration: Internet site * System mail name: the FQDN of the mail server that you've verified in the previous section. Note that the script will try to guess the DNS name, but that might yield a DNS name with a trailing dot. That is technically correct, but the installation script will barf. Remove the trailing dot before hitting &lt;enter>! * Postmaster mail address: the address that all mail should go to that is addressed to "root" and "postmaster". * Domain list: give the list of all domains that the machine can consider itself the FINAL destination for. This should at a minimum include an empty value, "localhost" and the FQDN of the machine itself (no trailing dots!); however, if you're running your own mail domain, you can also add that (e.g. "saruman.biz"). Thus, the list could look like this: saruman.biz, lighthouse.saruman.lan, localhost.saruman.lan, , localhost * Force synchronous updates? We think that's not necessary, but please read the question and decide for yourself * Local networks: something like ''127.0.0.0/8 [::ffff:127.0.0.0]/104 [::1]/128 192.168.67.0/24'' (the default, augmented with your local IP range) * Mailbox size limits: you can give postfix a limit in bytes, but we're going to use one single big mailbox for all users, so we cannot let Postfix guard it. Leave it at 0 (zero) so we don't have a size limit. * Character for local address extension: we leave it at ''+'' * Internet protocols to use: currently we don't have IPv6 support, so there's no sense in letting Postfix try to serve IPv6. We choose ''ipv4'' only. With the above data, the Debian install script for Postfix can do its job and configure Postfix with some basic settings. Now that Postfix is installed, we can install some dependent packages (we could install them in the same run, but if anything goes amiss with the postfix installation, then these packages are going to remain unconfigured as well): * ''postfix-doc'', the accompanying documentation; * ''postfix-mysql'', necessary to have Postfix talk to our MySQL server; * ''postfix-pcre'' to be able to parse regular expressions, which which we can combat spam; * ''dovecot-imapd'' is a daemon that will provide your users with IMAP access to their mail; * ''dovecot-pop3d'' is another daemon, but for the POP3 protocol. ==Virtual Mailman creation== When we're done, we'll need a "system user", a sort of virtual mailman that is the owner of all mailboxes that we're serving. We suggest the name "vmail" for this user. Note: this user does not get his own mailbox (i.e. there's no mailbox at vmail@saruman.biz). To create this user, and his home directory, we can run the following commands: groupadd -g 120 vmail useradd -g vmail -u 120 vmail -d /data/vmail -m -s /bin/false As you see, we've chosen a group ID and user ID of 120 (after confirming that this ID was not taken by another group or user, by checking ''/etc/passwd'' and ''/etc/group''. Furthermore, we've decided to keep the ''vmail'' user's home directory not under ''/home/vmail'', but in a special place where we're going to expect server data to reside - in our server, the ''/data'' directory (which is a RAID-5 array mounted under root). By adding ''-m'', we've actually created the home directory, and adding ''-s /bin/false'' makes totally sure that the user ''vmail'' can never ever log in - even if we've not created a password for this user, so ''vmail'' shouldn't be able to log in anyway. Better safe than sorry. To tell Postfix that this ''vmail'' user is someone special, we run postconf -e virtual_uid_maps=static:120 postconf -e virtual_gid_maps=static:120 That makes postfix understand that all mail for the virtual mail domains must be written to disk with these specified user and group ID's. ==MySQL configuration== ===Database preparation=== We will use the MySQL database to record data on our mail system, and then give our Postfix access to this database so that it can read its configuration from there. For starters, we'll create a MySQL database named "vmail", and a MySQL user named "vmail_admin" that can read all necessary data from that "vmail" database. Then, we create the necessary tables, and a view that links these tables. We do this with the MySQL client ''mysql''. However, we're quite lazy, so we don't create this database by hand (that's error-prone), but by use of a script [[create.vmail.sql]]. To this end, feed the [[create.vmail.sql]] script into the ''mysql'' client like this: mysql -u root -p < create.vmail.sql (This of course assumes you have ''create.vmail.sql'' in your current working directory; if not you can include the path to the file.) Simply give the MySQL root user password, and the script creates the database, the user, the necessary tables, and the view.<br> A note of caution: it is never a good idea to just run scripts without a proper understanding of what it does. Especially with MySQL, it will be advantageous if you understand the SQL commands. Open the script in a text editor, open the [http://dev.mysql.com/doc/refman/5.0/en/ MySQL command reference], and trace back what the script does exactly. ===Inserting data=== Next up, we fill the database with the first sets of values (either test data or the first of our production data). We'll start off with the virtual domains that we're hosting, by running the mysql client and feeding it information like this: mysql -u root -p vmail mysql> INSERT INTO virtual_domains (id, vdomain) VALUES (1, 'saruman.biz'); mysql> INSERT INTO virtual_domains (vdomain) VALUES ('wiki.saruman.biz'); mysql> INSERT INTO virtual_domains (vdomain) VALUES ('shop.saruman.biz'); This has the effect of creating three entries. You can check that everything worked as planned by executing mysql> select * from virtual_domains; Note: only the first entry needs an ''id'' value, because in MySQL we've defined that field as AUTO_INCREMENT. After creating your first virtual domain in the table, you never have to use a statement like the first INSERT again, only statements like the other two. Now the MySQL database has the information needed by Postfix to recognise that you have three virtual mail domains (namely the three domains in the VALUES section) for which it hosts virtual mailboxes. Postfix cannot read this information yet, but that'll be taken care of in the next section. Whle still within the mysql client, we can now create users: mysql> INSERT INTO virtual_users (id, domain_id, user, passwd) VALUES (1, 1, 'jan', MD5('JanSecret')); mysql> INSERT INTO virtual_users (domain_id, user, passwd) VALUES (1, 'mike', MD5('MikeSecret')); mysql> INSERT INTO virtual_users (domain_id, user, passwd) VALUES (3, 'shopkeeper', MD5('ShopSecret')); This has the effect of creating three users "jan" (in domain saruman.biz), "mike" (in domain saruman.biz) and "shopkeeper" (in domain shop.saruman.biz). Again, the ''id'' value is only ever needed in the first statement, because from now on every user addition will auto-increment ''id''. The passwords shown are encrypted with MD5, and put in the ''passwd'' field. Later on, the users will be able to access their mailboxes using this password; we won't tell Postfix anything about them, because it doesn't need the passwords. You can check the content of the ''virtual_users'' table with the right "select" statement, and you can now also see that the view ''view-users'' works: mysql> select * from virtual_users; mysql> select * from view_users; Next up, we're going to add some aliases, which are alternative e-mail addresses for the users; their primary e-mail address can already be seen in the ''view_users'' view, but perhaps you also want mail to "webmaster@shop.saruman.biz" to arrive at one or more mailboxes, e.g. in the mailbox for user "shopkeeper" (within domain "shop.saruman.biz") and this guy's home address ("j.doe@example.com"). Furthermore, we'll define catchall-addresses for all domains, that'll send all mail for which no mailbox can be found to the mailbox of user Mike (for the first two domains) and Webmaster (for shop.saruman.biz; Webmaster himself is an alias yet again, that points to shopkeeper@shop.saruman.biz). To create the catchall, leave out a value for the source address. This creates the empty value for source that will be expanded (using source@domain) to "@domain". mysql> INSERT INTO virtual_aliases (id, domain_id, source, destination) VALUES (1, 2, 'webmaster', 'shopkeeper@shop.saruman.biz'); mysql> INSERT INTO virtual_aliases (domain_id, source, destination) VALUES (2, 'webmaster', 'j.doe@example.com'); mysql> INSERT INTO virtual_aliases (domain_id, destination) VALUES (1, 'mike@saruman.biz'); mysql> INSERT INTO virtual_aliases (domain_id, destination) VALUES (2, 'mike@saruman.biz'); mysql> INSERT INTO virtual_aliases (domain_id, destination) VALUES (3, 'webmaster@saruman.biz'); Again, we don't need to add the ''id'' value any more after the first ever insertion into this table. We can check the result by running a select statement against the ''virtual_aliases'' table and ''view_aliases'' view: mysql> select * from virtual_aliases; mysql> select * from view_aliases; == Postfix configuration for MySQL lookups== Next, we're going to tell Postfix to use the ''vmail'' database, and also how to read the database (Postfix never writes the MySQL database). To this end, we're going to create three configuration files in directory ''/etc/postfix''. We'll start off with one configuration file, with which Postfix can determine if a domain name is among the domain(s) that it's actually hosting mailboxes for. Then we'll create the config file that checks the table that contains all the users that have a virtual mailbox, and finally we create the lookup for the table with all the aliases. ===Virtual mail domains lookup=== Create file ''/etc/postfix/mysql-virtual-domains.cf'' with the following content: user = vmail_admin password = SuperSecret hosts = 127.0.0.1 dbname = vmail query = SELECT 1 FROM virtual_domains WHERE vdomain='%s' Next, we tell postfix to check this configuration file when it needs to check "virtual_mailbox_domains": postconf -e virtual_mailbox_domains=mysql:/etc/postfix/mysql-virtual-domains.cf Use of this configuration file in postfix has the effect of returning "yes" when checking our database for the domain part of an email address. Naturally, this configuration file has to be fitted with the actual ''vmail_admin'' password rather than our example "SuperSecret". === Virtual mail user lookup=== Create the file ''/etc/postfix/mysql-virtual-mailbox-maps.cf'' with the following content: user = vmail_admin password = SuperSecret hosts = 127.0.0.1 dbname = vmail query = SELECT 1 FROM view_users WHERE email='%s' Next, we tell Postfix that this mapping file is supposed to be used for the ''virtual_mailbox_maps'' mapping: postconf -e virtual_mailbox_maps=mysql:/etc/postfix/mysql-virtual-mailbox-maps.cf The lookup of virtual mailboxes should work with the data we've put into the database previously. i.e. postmap -q jan@saruman.biz mysql:/etc/postfix/mysql-virtual-mailbox-maps.cf should return a '''1''' to acknowledge that "jan@saruman.biz" is indeed a virtual mailbox in our Postfix configuration. === Virtual alias lookup=== Create another cf file at ''/etc/postfix/mysql-virtual-alias-maps.cf'': user = vmail_admin password = SuperSecret hosts = 127.0.0.1 dbname = vmail query = SELECT destination FROM view_aliases WHERE email='%s' And create yet another cf file at ''/etc/postfix/mysql-email2email.cf'': user = vmail_admin password = SuperSecret hosts = 127.0.0.1 dbname = vmail query = SELECT email FROM view_users WHERE email='%s' Again, we tell Postfix that this mapping file is supposed to be used for the ''virtual_alias_maps'' mapping: postconf -e virtual_alias_maps=mysql:/etc/postfix/mysql-virtual-alias-maps.cf,mysql:/etc/postfix/mysql-email2email.cf The lookup of virtual aliases should now work as designed: postmap -q shopkeeper@shop.saruman.biz mysql:/etc/postfix/mysql-virtual-alias-maps.cf postmap -q webmaster@shop.saruman.biz mysql:/etc/postfix/mysql-virtual-alias-maps.cf If you've put in the data from the previous section, then both commands should return the same result: ''shopkeeper@saruman.biz''. This shows that Postfix will deliver mail to shopkeeper or to webmaster to the mailbox of shopkeeper. ===Finishing up configuration files=== When everything works as planned, then we secure the configuration files against prying eyes. Remember, the configuration files contain the user/password combination which which to access the ''vmail'' SQL database. The ''vmail_admin'' user has only read rights, and passwords in there are encrypted, but nevertheless, this is information we need to protect. Thus: chown root:postfix /etc/postfix/mysql-*.cf chmod u=rw,g=r,o= /etc/postfix/mysql-*.cf This protects all four configuration files since only root can write them, members of group ''postfix'' can read them, and the rest of the world cannot access them at all. ==Configuring mail delivery through Dovecot LDA== E-mails get delivered to the virtual mailboxes by means of a Mail Delivery Agent (MDA). With Postfix, the standard MDA for delivery to virtual mailboxes is called ''virtual'', but we're not going to use that; we're going to use ''[http://wiki.dovecot.org/LDA Dovecot LDA]'', which is a program called ''deliver''. By the way, the abbreviation LDA stands for Local Delivery Agent, which of course means more or less the same as MDA. ===Enabling the Dovecot daemon=== To make Postfix use Dovecot LDA, we add the following line to ''/etc/postfix/master.cf'': dovecot unix - n n - - pipe flags=DRhu user=vmail:vmail argv=/usr/lib/dovecot/deliver -d ${recipient} This declares the service "dovecot" to mean using the program ''/usr/lib/dovecot/deliver'' with the right parameters. If we now let Postfix reload its files, it'll learn about this new service. Subsequently we can instruct Postfix to start using it, by declaring service "dovecot" to be the virtual transport of choice, and specifying one Dovecot-specific variable: postfix reload postconf -e virtual_transport=dovecot postconf -e dovecot_destination_recipient_limit=1 ===Dovecot default configuration=== Now to configure Dovecot itself: open ''/etc/dovecot/dovecot.conf'' with your favourite editor [[vim]]; first make sure the ''protocols ='' line reads protocols = imap imaps pop3 pop3s (which it should by default). The second setting is quite crucial. By default, the location of the mail directories is found automatically by Dovecot, but here that won't work. Find the line that reads ''#maildir_location ='', and change it to mail_location = maildir:/data/vmail/%d/%n/Maildir This will look for mail in directory ''/data/vmail/'''DOMAIN'''/'''USER'''/Maildir'', and expect this directory to be in "maildir" format. Next look for a section called "auth default". First define the allowed authentication mechanisms: mechanisms = plain login Then inside that same section you need to uncomment: passdb sql { args = /etc/dovecot/dovecot-sql.conf } which tells Dovecot that the passwords are stored in an SQL database (it's obvious that we'll now have to create this conf-file) and: userdb static { args = uid=120 gid=120 home=/data/vmail/%d/%n allow_all_users=yes } to tell Dovecot where the mailboxes are located. This is similar to the ''mail_location'' setting. Next task: comment out the section ''passdb pam'', so that Dovecot doesn't accidentally try to service local users as well. Next up: tell Dovecot to handle IMAP the same as previous versions of this virtual mailserver have - this can prove to be quite tricky if you already have mailboxes full of mail, put there by e.g. Courier-IMAP. What works for us, is namespace private { separator = . prefix = inbox = yes } However, your mileage may vary. You'll also want to comment out the ''passdb pam'' sections, since we're not hosting mail for local users. Next up, we'll edit the section ''socket listen'' so that Dovecot can access the user database (master section), and our Postfix mailserver can access Dovecot (client section): socket listen { master { path = /var/run/dovecot/auth-master mode = 0600 user = vmail } client { path = /var/spool/postfix/private/auth mode = 0660 user = postfix group = postfix } } Finally, the protocol section, where we specify log files, an address to put in mails when we send out nondelivery reports, and a place to store scripts: protocol lda { log_path = /var/log/appslog/mail/dovecot-deliver.log auth_socket_path = /var/run/dovecot/auth-master postmaster_address = postmaster@saruman.biz mail_plugins = cmusieve global_script_path = /data/vmail/globalsieverc } Now that we've finished the Dovecot configuration file, we need to create a fitting MySQL configuration file for Dovecot. The file is ''/etc/dovecot/dovecot-sql.conf'', and its contents are driver = mysql connect = host=127.0.0.1 dbname=vmail user=vmail_admin password=SuperSecret default_pass_scheme = PLAIN-MD5 password_query = SELECT email as user, passwd as password FROM view_users WHERE email='%u'; When you've created this file (as root), change the attributes of ''dovecot-sql.conf'' and ''dovecot.conf'', and then restart Dovecot to start using the new configuration. Note: ''dovecot.conf'' needs to be read by Postfix, hence the group ownership for the file. chmod u=rw,g=,o= /etc/dovecot/dovecot-sql.conf chgrp vmail /etc/dovecot/dovecot.conf chmod u=rw,g=r,o= /etc/dovecot/dovecot.conf /etc/init.d/dovecot restart ===Dovecot SSL configuration=== Out of the (Debian) box, Dovecot is SSL-enabled. We'll now replace the generic SSL-certificate, generated for the host by the Dovecot installation script, by our own certificate. To ths end, we first [[Creating_digital_certificates_with_our_root_certificate | generate an appropriate certificate]], e.g. an SSL wildcard certificate: "*.saruman.biz". This results in a public and a private certificate, both of which must be placed somewhere where Dovecot expects them and can read them. By default, Dovecot expects the following locations/filenames/owner/attributes: /etc/ssl/certs/dovecot.pem -rw-r--r-- root:dovecot 4624 bytes /etc/ssl/private/dovecot.pem -rw------- root:dovecot 1743 bytes If we may make a suggestion: rename the generated certificates in both locations to dovecot.pem.bak, place your generated certificates in their place, and set the owner/permissions like displayed here. However, if you've generated your own keys, you might have used a passphrase on the private key. You'll have to tell dovecot about it in its configuration file /etc/dovecot/dovecot.conf. To this end, edit the corresponding section by uncommenting the "ssl_" lines, and using your private key password (e.g. "zM7Ertq12") in the appropriate line: ssl_cert_file = /etc/ssl/certs/dovecot.pem ssl_key_file = /etc/ssl/private/dovecot.pem # If key file is password protected, give the password here. Alternatively # give it when starting dovecot with -p parameter. ssl_key_password = zM7Ertq12 Naturally you are free to place the keys in a different location, and/or use a different name... ==Finishing up== This is a good moment to test your configuration, if you haven't been able to test your work inbetween. If everything works as expected, you can add bells and whistles to your configuration. The first one we'd like to present covers the way Postfix handles incoming connections. Since authentication works, we can have Postfix distrust every (unauthenticated) connection: postconf -e mynetworks= Furthermore, since a default SSL certificate is installed by the Debian Postfix installation routine, we can encrypt all our connections using TLS; we enforce this using postconf -e smtpd_use_tls=yes postconf -e smtpd_tls_auth_only=yes Of course, you need to adjust the settings of your IMAP client so that it properly uses TLS and properly authenticates itself. If everything ''still'' works after these changes, then congratulations, you now have a powerful, flexible and pretty secure mail setup. Of course, there are always points for improvements. We'll cover these in separate pages. Two pages that we want to direct you to now, are * [[Creating_digital_certificates_with_our_root_certificate | Creating a custom SSL certificate]] for our mail server * [[Antispam measures]] for our Postfix mailserver 65e882a7d2f50b0728ba7b357c7c04207f9e540d 2093 2090 2009-01-13T19:37:25Z Saruman! 2 /* Finishing up */ begun Postfix TLS cert wikitext text/x-wiki ==E-mail server setup== What we want to accomplish here is the setup of a mail server with the following properties: * can serve multiple mail domains * can relay mail for other domains to other mail servers * can have one or more mailboxes per domain * users of these mailboxes can be virtual (do not need to have a Linux user account) * can have multiple aliases per mailbox * can forward mail for certain aliases to multiple mailboxes For this type of mail server setup, we owe a great thankyou to [http://workaround.org/articles/ispmail-etch/ Christoph Haas], whose advise has helped us create flexible and reliable mail servers since 2003. ==Preparation== We'll assume that the server currently has no mailserver installed, at least no other than the default ''exim'' mailserver. Furthermore, the server is already fitted with MySQL, and this database is running without problems. The hostname of the server must be set correctly, so that ''hostname -f'' returns a valid DNS name, like ''lighthouse.saruman.biz.''. It might also be an internal name like ''lighthouse.saruman.lan.'' but that will require us to give extra attention to the name under which Postfix will contact its collegues on the Internet. Also, the server can correctly [Networking_section#DNS_resolution_under_Debian | resolve DNS names] like [http://www.debian.org www.debian.org], preferably by running it's own caching DNS server. The server is kept on the correct date and time using NTP, TCP port 25 is open on the server, the ISP will allow connections from Internet to this port, and if there's a firewall running on this server, then it has port 25 open so as to not block incoming e-mail. ==Software installation== As a first step, we use [[APT and aptitude|apt or aptitude]] to make sure that our server is up-to-date. Then we can install the necessary software packages. Under Debian 5.0 "Lenny", the (single) packages is: * ''postfix'', the mail server itself - this includes the "virtual package" postfix-tls, that we want to use to secure connections to Postfix with the TLS protocol At the same time we can - and must - purge the following packages: * exim4 * exim4-base * exim4-daemon-light * exim4-config In ''aptitude'', only press "go" when you've marked all four of these packages "purge", or you cannot install postfix. When installing the postfix package, the Debian installer script will ask you several questions, which you can answer like this: * General type of mail configuration: Internet site * System mail name: the FQDN of the mail server that you've verified in the previous section. Note that the script will try to guess the DNS name, but that might yield a DNS name with a trailing dot. That is technically correct, but the installation script will barf. Remove the trailing dot before hitting &lt;enter>! * Postmaster mail address: the address that all mail should go to that is addressed to "root" and "postmaster". * Domain list: give the list of all domains that the machine can consider itself the FINAL destination for. This should at a minimum include an empty value, "localhost" and the FQDN of the machine itself (no trailing dots!); however, if you're running your own mail domain, you can also add that (e.g. "saruman.biz"). Thus, the list could look like this: saruman.biz, lighthouse.saruman.lan, localhost.saruman.lan, , localhost * Force synchronous updates? We think that's not necessary, but please read the question and decide for yourself * Local networks: something like ''127.0.0.0/8 [::ffff:127.0.0.0]/104 [::1]/128 192.168.67.0/24'' (the default, augmented with your local IP range) * Mailbox size limits: you can give postfix a limit in bytes, but we're going to use one single big mailbox for all users, so we cannot let Postfix guard it. Leave it at 0 (zero) so we don't have a size limit. * Character for local address extension: we leave it at ''+'' * Internet protocols to use: currently we don't have IPv6 support, so there's no sense in letting Postfix try to serve IPv6. We choose ''ipv4'' only. With the above data, the Debian install script for Postfix can do its job and configure Postfix with some basic settings. Now that Postfix is installed, we can install some dependent packages (we could install them in the same run, but if anything goes amiss with the postfix installation, then these packages are going to remain unconfigured as well): * ''postfix-doc'', the accompanying documentation; * ''postfix-mysql'', necessary to have Postfix talk to our MySQL server; * ''postfix-pcre'' to be able to parse regular expressions, which which we can combat spam; * ''dovecot-imapd'' is a daemon that will provide your users with IMAP access to their mail; * ''dovecot-pop3d'' is another daemon, but for the POP3 protocol. ==Virtual Mailman creation== When we're done, we'll need a "system user", a sort of virtual mailman that is the owner of all mailboxes that we're serving. We suggest the name "vmail" for this user. Note: this user does not get his own mailbox (i.e. there's no mailbox at vmail@saruman.biz). To create this user, and his home directory, we can run the following commands: groupadd -g 120 vmail useradd -g vmail -u 120 vmail -d /data/vmail -m -s /bin/false As you see, we've chosen a group ID and user ID of 120 (after confirming that this ID was not taken by another group or user, by checking ''/etc/passwd'' and ''/etc/group''. Furthermore, we've decided to keep the ''vmail'' user's home directory not under ''/home/vmail'', but in a special place where we're going to expect server data to reside - in our server, the ''/data'' directory (which is a RAID-5 array mounted under root). By adding ''-m'', we've actually created the home directory, and adding ''-s /bin/false'' makes totally sure that the user ''vmail'' can never ever log in - even if we've not created a password for this user, so ''vmail'' shouldn't be able to log in anyway. Better safe than sorry. To tell Postfix that this ''vmail'' user is someone special, we run postconf -e virtual_uid_maps=static:120 postconf -e virtual_gid_maps=static:120 That makes postfix understand that all mail for the virtual mail domains must be written to disk with these specified user and group ID's. ==MySQL configuration== ===Database preparation=== We will use the MySQL database to record data on our mail system, and then give our Postfix access to this database so that it can read its configuration from there. For starters, we'll create a MySQL database named "vmail", and a MySQL user named "vmail_admin" that can read all necessary data from that "vmail" database. Then, we create the necessary tables, and a view that links these tables. We do this with the MySQL client ''mysql''. However, we're quite lazy, so we don't create this database by hand (that's error-prone), but by use of a script [[create.vmail.sql]]. To this end, feed the [[create.vmail.sql]] script into the ''mysql'' client like this: mysql -u root -p < create.vmail.sql (This of course assumes you have ''create.vmail.sql'' in your current working directory; if not you can include the path to the file.) Simply give the MySQL root user password, and the script creates the database, the user, the necessary tables, and the view.<br> A note of caution: it is never a good idea to just run scripts without a proper understanding of what it does. Especially with MySQL, it will be advantageous if you understand the SQL commands. Open the script in a text editor, open the [http://dev.mysql.com/doc/refman/5.0/en/ MySQL command reference], and trace back what the script does exactly. ===Inserting data=== Next up, we fill the database with the first sets of values (either test data or the first of our production data). We'll start off with the virtual domains that we're hosting, by running the mysql client and feeding it information like this: mysql -u root -p vmail mysql> INSERT INTO virtual_domains (id, vdomain) VALUES (1, 'saruman.biz'); mysql> INSERT INTO virtual_domains (vdomain) VALUES ('wiki.saruman.biz'); mysql> INSERT INTO virtual_domains (vdomain) VALUES ('shop.saruman.biz'); This has the effect of creating three entries. You can check that everything worked as planned by executing mysql> select * from virtual_domains; Note: only the first entry needs an ''id'' value, because in MySQL we've defined that field as AUTO_INCREMENT. After creating your first virtual domain in the table, you never have to use a statement like the first INSERT again, only statements like the other two. Now the MySQL database has the information needed by Postfix to recognise that you have three virtual mail domains (namely the three domains in the VALUES section) for which it hosts virtual mailboxes. Postfix cannot read this information yet, but that'll be taken care of in the next section. Whle still within the mysql client, we can now create users: mysql> INSERT INTO virtual_users (id, domain_id, user, passwd) VALUES (1, 1, 'jan', MD5('JanSecret')); mysql> INSERT INTO virtual_users (domain_id, user, passwd) VALUES (1, 'mike', MD5('MikeSecret')); mysql> INSERT INTO virtual_users (domain_id, user, passwd) VALUES (3, 'shopkeeper', MD5('ShopSecret')); This has the effect of creating three users "jan" (in domain saruman.biz), "mike" (in domain saruman.biz) and "shopkeeper" (in domain shop.saruman.biz). Again, the ''id'' value is only ever needed in the first statement, because from now on every user addition will auto-increment ''id''. The passwords shown are encrypted with MD5, and put in the ''passwd'' field. Later on, the users will be able to access their mailboxes using this password; we won't tell Postfix anything about them, because it doesn't need the passwords. You can check the content of the ''virtual_users'' table with the right "select" statement, and you can now also see that the view ''view-users'' works: mysql> select * from virtual_users; mysql> select * from view_users; Next up, we're going to add some aliases, which are alternative e-mail addresses for the users; their primary e-mail address can already be seen in the ''view_users'' view, but perhaps you also want mail to "webmaster@shop.saruman.biz" to arrive at one or more mailboxes, e.g. in the mailbox for user "shopkeeper" (within domain "shop.saruman.biz") and this guy's home address ("j.doe@example.com"). Furthermore, we'll define catchall-addresses for all domains, that'll send all mail for which no mailbox can be found to the mailbox of user Mike (for the first two domains) and Webmaster (for shop.saruman.biz; Webmaster himself is an alias yet again, that points to shopkeeper@shop.saruman.biz). To create the catchall, leave out a value for the source address. This creates the empty value for source that will be expanded (using source@domain) to "@domain". mysql> INSERT INTO virtual_aliases (id, domain_id, source, destination) VALUES (1, 2, 'webmaster', 'shopkeeper@shop.saruman.biz'); mysql> INSERT INTO virtual_aliases (domain_id, source, destination) VALUES (2, 'webmaster', 'j.doe@example.com'); mysql> INSERT INTO virtual_aliases (domain_id, destination) VALUES (1, 'mike@saruman.biz'); mysql> INSERT INTO virtual_aliases (domain_id, destination) VALUES (2, 'mike@saruman.biz'); mysql> INSERT INTO virtual_aliases (domain_id, destination) VALUES (3, 'webmaster@saruman.biz'); Again, we don't need to add the ''id'' value any more after the first ever insertion into this table. We can check the result by running a select statement against the ''virtual_aliases'' table and ''view_aliases'' view: mysql> select * from virtual_aliases; mysql> select * from view_aliases; == Postfix configuration for MySQL lookups== Next, we're going to tell Postfix to use the ''vmail'' database, and also how to read the database (Postfix never writes the MySQL database). To this end, we're going to create three configuration files in directory ''/etc/postfix''. We'll start off with one configuration file, with which Postfix can determine if a domain name is among the domain(s) that it's actually hosting mailboxes for. Then we'll create the config file that checks the table that contains all the users that have a virtual mailbox, and finally we create the lookup for the table with all the aliases. ===Virtual mail domains lookup=== Create file ''/etc/postfix/mysql-virtual-domains.cf'' with the following content: user = vmail_admin password = SuperSecret hosts = 127.0.0.1 dbname = vmail query = SELECT 1 FROM virtual_domains WHERE vdomain='%s' Next, we tell postfix to check this configuration file when it needs to check "virtual_mailbox_domains": postconf -e virtual_mailbox_domains=mysql:/etc/postfix/mysql-virtual-domains.cf Use of this configuration file in postfix has the effect of returning "yes" when checking our database for the domain part of an email address. Naturally, this configuration file has to be fitted with the actual ''vmail_admin'' password rather than our example "SuperSecret". === Virtual mail user lookup=== Create the file ''/etc/postfix/mysql-virtual-mailbox-maps.cf'' with the following content: user = vmail_admin password = SuperSecret hosts = 127.0.0.1 dbname = vmail query = SELECT 1 FROM view_users WHERE email='%s' Next, we tell Postfix that this mapping file is supposed to be used for the ''virtual_mailbox_maps'' mapping: postconf -e virtual_mailbox_maps=mysql:/etc/postfix/mysql-virtual-mailbox-maps.cf The lookup of virtual mailboxes should work with the data we've put into the database previously. i.e. postmap -q jan@saruman.biz mysql:/etc/postfix/mysql-virtual-mailbox-maps.cf should return a '''1''' to acknowledge that "jan@saruman.biz" is indeed a virtual mailbox in our Postfix configuration. === Virtual alias lookup=== Create another cf file at ''/etc/postfix/mysql-virtual-alias-maps.cf'': user = vmail_admin password = SuperSecret hosts = 127.0.0.1 dbname = vmail query = SELECT destination FROM view_aliases WHERE email='%s' And create yet another cf file at ''/etc/postfix/mysql-email2email.cf'': user = vmail_admin password = SuperSecret hosts = 127.0.0.1 dbname = vmail query = SELECT email FROM view_users WHERE email='%s' Again, we tell Postfix that this mapping file is supposed to be used for the ''virtual_alias_maps'' mapping: postconf -e virtual_alias_maps=mysql:/etc/postfix/mysql-virtual-alias-maps.cf,mysql:/etc/postfix/mysql-email2email.cf The lookup of virtual aliases should now work as designed: postmap -q shopkeeper@shop.saruman.biz mysql:/etc/postfix/mysql-virtual-alias-maps.cf postmap -q webmaster@shop.saruman.biz mysql:/etc/postfix/mysql-virtual-alias-maps.cf If you've put in the data from the previous section, then both commands should return the same result: ''shopkeeper@saruman.biz''. This shows that Postfix will deliver mail to shopkeeper or to webmaster to the mailbox of shopkeeper. ===Finishing up configuration files=== When everything works as planned, then we secure the configuration files against prying eyes. Remember, the configuration files contain the user/password combination which which to access the ''vmail'' SQL database. The ''vmail_admin'' user has only read rights, and passwords in there are encrypted, but nevertheless, this is information we need to protect. Thus: chown root:postfix /etc/postfix/mysql-*.cf chmod u=rw,g=r,o= /etc/postfix/mysql-*.cf This protects all four configuration files since only root can write them, members of group ''postfix'' can read them, and the rest of the world cannot access them at all. ==Configuring mail delivery through Dovecot LDA== E-mails get delivered to the virtual mailboxes by means of a Mail Delivery Agent (MDA). With Postfix, the standard MDA for delivery to virtual mailboxes is called ''virtual'', but we're not going to use that; we're going to use ''[http://wiki.dovecot.org/LDA Dovecot LDA]'', which is a program called ''deliver''. By the way, the abbreviation LDA stands for Local Delivery Agent, which of course means more or less the same as MDA. ===Enabling the Dovecot daemon=== To make Postfix use Dovecot LDA, we add the following line to ''/etc/postfix/master.cf'': dovecot unix - n n - - pipe flags=DRhu user=vmail:vmail argv=/usr/lib/dovecot/deliver -d ${recipient} This declares the service "dovecot" to mean using the program ''/usr/lib/dovecot/deliver'' with the right parameters. If we now let Postfix reload its files, it'll learn about this new service. Subsequently we can instruct Postfix to start using it, by declaring service "dovecot" to be the virtual transport of choice, and specifying one Dovecot-specific variable: postfix reload postconf -e virtual_transport=dovecot postconf -e dovecot_destination_recipient_limit=1 ===Dovecot default configuration=== Now to configure Dovecot itself: open ''/etc/dovecot/dovecot.conf'' with your favourite editor [[vim]]; first make sure the ''protocols ='' line reads protocols = imap imaps pop3 pop3s (which it should by default). The second setting is quite crucial. By default, the location of the mail directories is found automatically by Dovecot, but here that won't work. Find the line that reads ''#maildir_location ='', and change it to mail_location = maildir:/data/vmail/%d/%n/Maildir This will look for mail in directory ''/data/vmail/'''DOMAIN'''/'''USER'''/Maildir'', and expect this directory to be in "maildir" format. Next look for a section called "auth default". First define the allowed authentication mechanisms: mechanisms = plain login Then inside that same section you need to uncomment: passdb sql { args = /etc/dovecot/dovecot-sql.conf } which tells Dovecot that the passwords are stored in an SQL database (it's obvious that we'll now have to create this conf-file) and: userdb static { args = uid=120 gid=120 home=/data/vmail/%d/%n allow_all_users=yes } to tell Dovecot where the mailboxes are located. This is similar to the ''mail_location'' setting. Next task: comment out the section ''passdb pam'', so that Dovecot doesn't accidentally try to service local users as well. Next up: tell Dovecot to handle IMAP the same as previous versions of this virtual mailserver have - this can prove to be quite tricky if you already have mailboxes full of mail, put there by e.g. Courier-IMAP. What works for us, is namespace private { separator = . prefix = inbox = yes } However, your mileage may vary. You'll also want to comment out the ''passdb pam'' sections, since we're not hosting mail for local users. Next up, we'll edit the section ''socket listen'' so that Dovecot can access the user database (master section), and our Postfix mailserver can access Dovecot (client section): socket listen { master { path = /var/run/dovecot/auth-master mode = 0600 user = vmail } client { path = /var/spool/postfix/private/auth mode = 0660 user = postfix group = postfix } } Finally, the protocol section, where we specify log files, an address to put in mails when we send out nondelivery reports, and a place to store scripts: protocol lda { log_path = /var/log/appslog/mail/dovecot-deliver.log auth_socket_path = /var/run/dovecot/auth-master postmaster_address = postmaster@saruman.biz mail_plugins = cmusieve global_script_path = /data/vmail/globalsieverc } Now that we've finished the Dovecot configuration file, we need to create a fitting MySQL configuration file for Dovecot. The file is ''/etc/dovecot/dovecot-sql.conf'', and its contents are driver = mysql connect = host=127.0.0.1 dbname=vmail user=vmail_admin password=SuperSecret default_pass_scheme = PLAIN-MD5 password_query = SELECT email as user, passwd as password FROM view_users WHERE email='%u'; When you've created this file (as root), change the attributes of ''dovecot-sql.conf'' and ''dovecot.conf'', and then restart Dovecot to start using the new configuration. Note: ''dovecot.conf'' needs to be read by Postfix, hence the group ownership for the file. chmod u=rw,g=,o= /etc/dovecot/dovecot-sql.conf chgrp vmail /etc/dovecot/dovecot.conf chmod u=rw,g=r,o= /etc/dovecot/dovecot.conf /etc/init.d/dovecot restart ===Dovecot SSL configuration=== Out of the (Debian) box, Dovecot is SSL-enabled. We'll now replace the generic SSL-certificate, generated for the host by the Dovecot installation script, by our own certificate. To ths end, we first [[Creating_digital_certificates_with_our_root_certificate | generate an appropriate certificate]], e.g. an SSL wildcard certificate: "*.saruman.biz". This results in a public and a private certificate, both of which must be placed somewhere where Dovecot expects them and can read them. By default, Dovecot expects the following locations/filenames/owner/attributes: /etc/ssl/certs/dovecot.pem -rw-r--r-- root:dovecot 4624 bytes /etc/ssl/private/dovecot.pem -rw------- root:dovecot 1743 bytes If we may make a suggestion: rename the generated certificates in both locations to dovecot.pem.bak, place your generated certificates in their place, and set the owner/permissions like displayed here. However, if you've generated your own keys, you might have used a passphrase on the private key. You'll have to tell dovecot about it in its configuration file /etc/dovecot/dovecot.conf. To this end, edit the corresponding section by uncommenting the "ssl_" lines, and using your private key password (e.g. "zM7Ertq12") in the appropriate line: ssl_cert_file = /etc/ssl/certs/dovecot.pem ssl_key_file = /etc/ssl/private/dovecot.pem # If key file is password protected, give the password here. Alternatively # give it when starting dovecot with -p parameter. ssl_key_password = zM7Ertq12 Naturally you are free to place the keys in a different location, and/or use a different name... ==Finishing up== This is a good moment to test your configuration, if you haven't been able to test your work inbetween. If everything works as expected, you can add bells and whistles to your configuration. ===''smtpd'' TLS encryption=== The first addition we'd like to present covers the way Postfix handles incoming connections. Since authentication works, we can have Postfix distrust every (unauthenticated) connection: postconf -e mynetworks= Furthermore, since a default SSL certificate is installed by the Debian Postfix installation routine, we can encrypt all our connections using TLS; we enforce this using postconf -e smtpd_use_tls=yes postconf -e smtpd_tls_auth_only=yes Of course, you need to adjust the settings of your IMAP client so that it properly uses TLS and properly authenticates itself. If TLS works, you'll probably want to change the certificate as you have for Dovecot in the previous section. This is again pretty easy. If you haven't yet, now is the time to [[Creating_digital_certificates_with_our_root_certificate | creating that custom SSL certificate]] for our mail server - but you have to make sure that you DON'T use a password on the private key. Unlike Dovecot, Postfix cannot be told the password to the private key somewhere. For starters, look at the TLS-section of your ''main.cf'' that you currently have. Chances are it looks a bit like this: # TLS parameters smtpd_tls_cert_file=/etc/ssl/certs/ssl-cert-snakeoil.pem smtpd_tls_key_file=/etc/ssl/private/ssl-cert-snakeoil.key smtpd_use_tls=yes === Other additions === If everything ''still'' works after these changes, then congratulations, you now have a powerful, flexible and pretty secure mail setup. Of course, there are always points for improvements. We'll cover these in separate pages. One page that we want to direct you to now, is * [[Antispam measures]] for our Postfix mailserver cdc14b0de8009250e9e9ea81b9529e70a811dd99 2095 2093 2009-01-17T16:03:43Z Saruman! 2 /* Finishing up */ with SSL for postfix wikitext text/x-wiki ==E-mail server setup== What we want to accomplish here is the setup of a mail server with the following properties: * can serve multiple mail domains * can relay mail for other domains to other mail servers * can have one or more mailboxes per domain * users of these mailboxes can be virtual (do not need to have a Linux user account) * can have multiple aliases per mailbox * can forward mail for certain aliases to multiple mailboxes For this type of mail server setup, we owe a great thankyou to [http://workaround.org/articles/ispmail-etch/ Christoph Haas], whose advise has helped us create flexible and reliable mail servers since 2003. ==Preparation== We'll assume that the server currently has no mailserver installed, at least no other than the default ''exim'' mailserver. Furthermore, the server is already fitted with MySQL, and this database is running without problems. The hostname of the server must be set correctly, so that ''hostname -f'' returns a valid DNS name, like ''lighthouse.saruman.biz.''. It might also be an internal name like ''lighthouse.saruman.lan.'' but that will require us to give extra attention to the name under which Postfix will contact its collegues on the Internet. Also, the server can correctly [Networking_section#DNS_resolution_under_Debian | resolve DNS names] like [http://www.debian.org www.debian.org], preferably by running it's own caching DNS server. The server is kept on the correct date and time using NTP, TCP port 25 is open on the server, the ISP will allow connections from Internet to this port, and if there's a firewall running on this server, then it has port 25 open so as to not block incoming e-mail. ==Software installation== As a first step, we use [[APT and aptitude|apt or aptitude]] to make sure that our server is up-to-date. Then we can install the necessary software packages. Under Debian 5.0 "Lenny", the (single) packages is: * ''postfix'', the mail server itself - this includes the "virtual package" postfix-tls, that we want to use to secure connections to Postfix with the TLS protocol At the same time we can - and must - purge the following packages: * exim4 * exim4-base * exim4-daemon-light * exim4-config In ''aptitude'', only press "go" when you've marked all four of these packages "purge", or you cannot install postfix. When installing the postfix package, the Debian installer script will ask you several questions, which you can answer like this: * General type of mail configuration: Internet site * System mail name: the FQDN of the mail server that you've verified in the previous section. Note that the script will try to guess the DNS name, but that might yield a DNS name with a trailing dot. That is technically correct, but the installation script will barf. Remove the trailing dot before hitting &lt;enter>! * Postmaster mail address: the address that all mail should go to that is addressed to "root" and "postmaster". * Domain list: give the list of all domains that the machine can consider itself the FINAL destination for. This should at a minimum include an empty value, "localhost" and the FQDN of the machine itself (no trailing dots!); however, if you're running your own mail domain, you can also add that (e.g. "saruman.biz"). Thus, the list could look like this: saruman.biz, lighthouse.saruman.lan, localhost.saruman.lan, , localhost * Force synchronous updates? We think that's not necessary, but please read the question and decide for yourself * Local networks: something like ''127.0.0.0/8 [::ffff:127.0.0.0]/104 [::1]/128 192.168.67.0/24'' (the default, augmented with your local IP range) * Mailbox size limits: you can give postfix a limit in bytes, but we're going to use one single big mailbox for all users, so we cannot let Postfix guard it. Leave it at 0 (zero) so we don't have a size limit. * Character for local address extension: we leave it at ''+'' * Internet protocols to use: currently we don't have IPv6 support, so there's no sense in letting Postfix try to serve IPv6. We choose ''ipv4'' only. With the above data, the Debian install script for Postfix can do its job and configure Postfix with some basic settings. Now that Postfix is installed, we can install some dependent packages (we could install them in the same run, but if anything goes amiss with the postfix installation, then these packages are going to remain unconfigured as well): * ''postfix-doc'', the accompanying documentation; * ''postfix-mysql'', necessary to have Postfix talk to our MySQL server; * ''postfix-pcre'' to be able to parse regular expressions, which which we can combat spam; * ''dovecot-imapd'' is a daemon that will provide your users with IMAP access to their mail; * ''dovecot-pop3d'' is another daemon, but for the POP3 protocol. ==Virtual Mailman creation== When we're done, we'll need a "system user", a sort of virtual mailman that is the owner of all mailboxes that we're serving. We suggest the name "vmail" for this user. Note: this user does not get his own mailbox (i.e. there's no mailbox at vmail@saruman.biz). To create this user, and his home directory, we can run the following commands: groupadd -g 120 vmail useradd -g vmail -u 120 vmail -d /data/vmail -m -s /bin/false As you see, we've chosen a group ID and user ID of 120 (after confirming that this ID was not taken by another group or user, by checking ''/etc/passwd'' and ''/etc/group''. Furthermore, we've decided to keep the ''vmail'' user's home directory not under ''/home/vmail'', but in a special place where we're going to expect server data to reside - in our server, the ''/data'' directory (which is a RAID-5 array mounted under root). By adding ''-m'', we've actually created the home directory, and adding ''-s /bin/false'' makes totally sure that the user ''vmail'' can never ever log in - even if we've not created a password for this user, so ''vmail'' shouldn't be able to log in anyway. Better safe than sorry. To tell Postfix that this ''vmail'' user is someone special, we run postconf -e virtual_uid_maps=static:120 postconf -e virtual_gid_maps=static:120 That makes postfix understand that all mail for the virtual mail domains must be written to disk with these specified user and group ID's. ==MySQL configuration== ===Database preparation=== We will use the MySQL database to record data on our mail system, and then give our Postfix access to this database so that it can read its configuration from there. For starters, we'll create a MySQL database named "vmail", and a MySQL user named "vmail_admin" that can read all necessary data from that "vmail" database. Then, we create the necessary tables, and a view that links these tables. We do this with the MySQL client ''mysql''. However, we're quite lazy, so we don't create this database by hand (that's error-prone), but by use of a script [[create.vmail.sql]]. To this end, feed the [[create.vmail.sql]] script into the ''mysql'' client like this: mysql -u root -p < create.vmail.sql (This of course assumes you have ''create.vmail.sql'' in your current working directory; if not you can include the path to the file.) Simply give the MySQL root user password, and the script creates the database, the user, the necessary tables, and the view.<br> A note of caution: it is never a good idea to just run scripts without a proper understanding of what it does. Especially with MySQL, it will be advantageous if you understand the SQL commands. Open the script in a text editor, open the [http://dev.mysql.com/doc/refman/5.0/en/ MySQL command reference], and trace back what the script does exactly. ===Inserting data=== Next up, we fill the database with the first sets of values (either test data or the first of our production data). We'll start off with the virtual domains that we're hosting, by running the mysql client and feeding it information like this: mysql -u root -p vmail mysql> INSERT INTO virtual_domains (id, vdomain) VALUES (1, 'saruman.biz'); mysql> INSERT INTO virtual_domains (vdomain) VALUES ('wiki.saruman.biz'); mysql> INSERT INTO virtual_domains (vdomain) VALUES ('shop.saruman.biz'); This has the effect of creating three entries. You can check that everything worked as planned by executing mysql> select * from virtual_domains; Note: only the first entry needs an ''id'' value, because in MySQL we've defined that field as AUTO_INCREMENT. After creating your first virtual domain in the table, you never have to use a statement like the first INSERT again, only statements like the other two. Now the MySQL database has the information needed by Postfix to recognise that you have three virtual mail domains (namely the three domains in the VALUES section) for which it hosts virtual mailboxes. Postfix cannot read this information yet, but that'll be taken care of in the next section. Whle still within the mysql client, we can now create users: mysql> INSERT INTO virtual_users (id, domain_id, user, passwd) VALUES (1, 1, 'jan', MD5('JanSecret')); mysql> INSERT INTO virtual_users (domain_id, user, passwd) VALUES (1, 'mike', MD5('MikeSecret')); mysql> INSERT INTO virtual_users (domain_id, user, passwd) VALUES (3, 'shopkeeper', MD5('ShopSecret')); This has the effect of creating three users "jan" (in domain saruman.biz), "mike" (in domain saruman.biz) and "shopkeeper" (in domain shop.saruman.biz). Again, the ''id'' value is only ever needed in the first statement, because from now on every user addition will auto-increment ''id''. The passwords shown are encrypted with MD5, and put in the ''passwd'' field. Later on, the users will be able to access their mailboxes using this password; we won't tell Postfix anything about them, because it doesn't need the passwords. You can check the content of the ''virtual_users'' table with the right "select" statement, and you can now also see that the view ''view-users'' works: mysql> select * from virtual_users; mysql> select * from view_users; Next up, we're going to add some aliases, which are alternative e-mail addresses for the users; their primary e-mail address can already be seen in the ''view_users'' view, but perhaps you also want mail to "webmaster@shop.saruman.biz" to arrive at one or more mailboxes, e.g. in the mailbox for user "shopkeeper" (within domain "shop.saruman.biz") and this guy's home address ("j.doe@example.com"). Furthermore, we'll define catchall-addresses for all domains, that'll send all mail for which no mailbox can be found to the mailbox of user Mike (for the first two domains) and Webmaster (for shop.saruman.biz; Webmaster himself is an alias yet again, that points to shopkeeper@shop.saruman.biz). To create the catchall, leave out a value for the source address. This creates the empty value for source that will be expanded (using source@domain) to "@domain". mysql> INSERT INTO virtual_aliases (id, domain_id, source, destination) VALUES (1, 2, 'webmaster', 'shopkeeper@shop.saruman.biz'); mysql> INSERT INTO virtual_aliases (domain_id, source, destination) VALUES (2, 'webmaster', 'j.doe@example.com'); mysql> INSERT INTO virtual_aliases (domain_id, destination) VALUES (1, 'mike@saruman.biz'); mysql> INSERT INTO virtual_aliases (domain_id, destination) VALUES (2, 'mike@saruman.biz'); mysql> INSERT INTO virtual_aliases (domain_id, destination) VALUES (3, 'webmaster@saruman.biz'); Again, we don't need to add the ''id'' value any more after the first ever insertion into this table. We can check the result by running a select statement against the ''virtual_aliases'' table and ''view_aliases'' view: mysql> select * from virtual_aliases; mysql> select * from view_aliases; == Postfix configuration for MySQL lookups== Next, we're going to tell Postfix to use the ''vmail'' database, and also how to read the database (Postfix never writes the MySQL database). To this end, we're going to create three configuration files in directory ''/etc/postfix''. We'll start off with one configuration file, with which Postfix can determine if a domain name is among the domain(s) that it's actually hosting mailboxes for. Then we'll create the config file that checks the table that contains all the users that have a virtual mailbox, and finally we create the lookup for the table with all the aliases. ===Virtual mail domains lookup=== Create file ''/etc/postfix/mysql-virtual-domains.cf'' with the following content: user = vmail_admin password = SuperSecret hosts = 127.0.0.1 dbname = vmail query = SELECT 1 FROM virtual_domains WHERE vdomain='%s' Next, we tell postfix to check this configuration file when it needs to check "virtual_mailbox_domains": postconf -e virtual_mailbox_domains=mysql:/etc/postfix/mysql-virtual-domains.cf Use of this configuration file in postfix has the effect of returning "yes" when checking our database for the domain part of an email address. Naturally, this configuration file has to be fitted with the actual ''vmail_admin'' password rather than our example "SuperSecret". === Virtual mail user lookup=== Create the file ''/etc/postfix/mysql-virtual-mailbox-maps.cf'' with the following content: user = vmail_admin password = SuperSecret hosts = 127.0.0.1 dbname = vmail query = SELECT 1 FROM view_users WHERE email='%s' Next, we tell Postfix that this mapping file is supposed to be used for the ''virtual_mailbox_maps'' mapping: postconf -e virtual_mailbox_maps=mysql:/etc/postfix/mysql-virtual-mailbox-maps.cf The lookup of virtual mailboxes should work with the data we've put into the database previously. i.e. postmap -q jan@saruman.biz mysql:/etc/postfix/mysql-virtual-mailbox-maps.cf should return a '''1''' to acknowledge that "jan@saruman.biz" is indeed a virtual mailbox in our Postfix configuration. === Virtual alias lookup=== Create another cf file at ''/etc/postfix/mysql-virtual-alias-maps.cf'': user = vmail_admin password = SuperSecret hosts = 127.0.0.1 dbname = vmail query = SELECT destination FROM view_aliases WHERE email='%s' And create yet another cf file at ''/etc/postfix/mysql-email2email.cf'': user = vmail_admin password = SuperSecret hosts = 127.0.0.1 dbname = vmail query = SELECT email FROM view_users WHERE email='%s' Again, we tell Postfix that this mapping file is supposed to be used for the ''virtual_alias_maps'' mapping: postconf -e virtual_alias_maps=mysql:/etc/postfix/mysql-virtual-alias-maps.cf,mysql:/etc/postfix/mysql-email2email.cf The lookup of virtual aliases should now work as designed: postmap -q shopkeeper@shop.saruman.biz mysql:/etc/postfix/mysql-virtual-alias-maps.cf postmap -q webmaster@shop.saruman.biz mysql:/etc/postfix/mysql-virtual-alias-maps.cf If you've put in the data from the previous section, then both commands should return the same result: ''shopkeeper@saruman.biz''. This shows that Postfix will deliver mail to shopkeeper or to webmaster to the mailbox of shopkeeper. ===Finishing up configuration files=== When everything works as planned, then we secure the configuration files against prying eyes. Remember, the configuration files contain the user/password combination which which to access the ''vmail'' SQL database. The ''vmail_admin'' user has only read rights, and passwords in there are encrypted, but nevertheless, this is information we need to protect. Thus: chown root:postfix /etc/postfix/mysql-*.cf chmod u=rw,g=r,o= /etc/postfix/mysql-*.cf This protects all four configuration files since only root can write them, members of group ''postfix'' can read them, and the rest of the world cannot access them at all. ==Configuring mail delivery through Dovecot LDA== E-mails get delivered to the virtual mailboxes by means of a Mail Delivery Agent (MDA). With Postfix, the standard MDA for delivery to virtual mailboxes is called ''virtual'', but we're not going to use that; we're going to use ''[http://wiki.dovecot.org/LDA Dovecot LDA]'', which is a program called ''deliver''. By the way, the abbreviation LDA stands for Local Delivery Agent, which of course means more or less the same as MDA. ===Enabling the Dovecot daemon=== To make Postfix use Dovecot LDA, we add the following line to ''/etc/postfix/master.cf'': dovecot unix - n n - - pipe flags=DRhu user=vmail:vmail argv=/usr/lib/dovecot/deliver -d ${recipient} This declares the service "dovecot" to mean using the program ''/usr/lib/dovecot/deliver'' with the right parameters. If we now let Postfix reload its files, it'll learn about this new service. Subsequently we can instruct Postfix to start using it, by declaring service "dovecot" to be the virtual transport of choice, and specifying one Dovecot-specific variable: postfix reload postconf -e virtual_transport=dovecot postconf -e dovecot_destination_recipient_limit=1 ===Dovecot default configuration=== Now to configure Dovecot itself: open ''/etc/dovecot/dovecot.conf'' with your favourite editor [[vim]]; first make sure the ''protocols ='' line reads protocols = imap imaps pop3 pop3s (which it should by default). The second setting is quite crucial. By default, the location of the mail directories is found automatically by Dovecot, but here that won't work. Find the line that reads ''#maildir_location ='', and change it to mail_location = maildir:/data/vmail/%d/%n/Maildir This will look for mail in directory ''/data/vmail/'''DOMAIN'''/'''USER'''/Maildir'', and expect this directory to be in "maildir" format. Next look for a section called "auth default". First define the allowed authentication mechanisms: mechanisms = plain login Then inside that same section you need to uncomment: passdb sql { args = /etc/dovecot/dovecot-sql.conf } which tells Dovecot that the passwords are stored in an SQL database (it's obvious that we'll now have to create this conf-file) and: userdb static { args = uid=120 gid=120 home=/data/vmail/%d/%n allow_all_users=yes } to tell Dovecot where the mailboxes are located. This is similar to the ''mail_location'' setting. Next task: comment out the section ''passdb pam'', so that Dovecot doesn't accidentally try to service local users as well. Next up: tell Dovecot to handle IMAP the same as previous versions of this virtual mailserver have - this can prove to be quite tricky if you already have mailboxes full of mail, put there by e.g. Courier-IMAP. What works for us, is namespace private { separator = . prefix = inbox = yes } However, your mileage may vary. You'll also want to comment out the ''passdb pam'' sections, since we're not hosting mail for local users. Next up, we'll edit the section ''socket listen'' so that Dovecot can access the user database (master section), and our Postfix mailserver can access Dovecot (client section): socket listen { master { path = /var/run/dovecot/auth-master mode = 0600 user = vmail } client { path = /var/spool/postfix/private/auth mode = 0660 user = postfix group = postfix } } Finally, the protocol section, where we specify log files, an address to put in mails when we send out nondelivery reports, and a place to store scripts: protocol lda { log_path = /var/log/appslog/mail/dovecot-deliver.log auth_socket_path = /var/run/dovecot/auth-master postmaster_address = postmaster@saruman.biz mail_plugins = cmusieve global_script_path = /data/vmail/globalsieverc } Now that we've finished the Dovecot configuration file, we need to create a fitting MySQL configuration file for Dovecot. The file is ''/etc/dovecot/dovecot-sql.conf'', and its contents are driver = mysql connect = host=127.0.0.1 dbname=vmail user=vmail_admin password=SuperSecret default_pass_scheme = PLAIN-MD5 password_query = SELECT email as user, passwd as password FROM view_users WHERE email='%u'; When you've created this file (as root), change the attributes of ''dovecot-sql.conf'' and ''dovecot.conf'', and then restart Dovecot to start using the new configuration. Note: ''dovecot.conf'' needs to be read by Postfix, hence the group ownership for the file. chmod u=rw,g=,o= /etc/dovecot/dovecot-sql.conf chgrp vmail /etc/dovecot/dovecot.conf chmod u=rw,g=r,o= /etc/dovecot/dovecot.conf /etc/init.d/dovecot restart ===Dovecot SSL configuration=== Out of the (Debian) box, Dovecot is SSL-enabled. We'll now replace the generic SSL-certificate, generated for the host by the Dovecot installation script, by our own certificate. To ths end, we first [[Creating_digital_certificates_with_our_root_certificate | generate an appropriate certificate]], e.g. an SSL wildcard certificate: "*.saruman.biz". This results in a public and a private certificate, both of which must be placed somewhere where Dovecot expects them and can read them. By default, Dovecot expects the following locations/filenames/owner/attributes: /etc/ssl/certs/dovecot.pem -rw-r--r-- root:dovecot 4624 bytes /etc/ssl/private/dovecot.pem -rw------- root:dovecot 1743 bytes If we may make a suggestion: rename the generated certificates in both locations to dovecot.pem.bak, place your generated certificates in their place, and set the owner/permissions like displayed here. However, if you've generated your own keys, you might have used a passphrase on the private key. You'll have to tell dovecot about it in its configuration file /etc/dovecot/dovecot.conf. To this end, edit the corresponding section by uncommenting the "ssl_" lines, and using your private key password (e.g. "zM7Ertq12") in the appropriate line: ssl_cert_file = /etc/ssl/certs/dovecot.pem ssl_key_file = /etc/ssl/private/dovecot.pem # If key file is password protected, give the password here. Alternatively # give it when starting dovecot with -p parameter. ssl_key_password = zM7Ertq12 Naturally you are free to place the keys in a different location, and/or use a different name... ==Finishing up== This is a good moment to test your configuration, if you haven't been able to test your work inbetween. If everything works as expected, you can add bells and whistles to your configuration. ===''smtpd'' TLS encryption=== The first addition we'd like to present covers the way Postfix handles incoming connections. Since authentication works, we can have Postfix distrust every (unauthenticated) connection: postconf -e mynetworks= Furthermore, since a default SSL certificate is installed by the Debian Postfix installation routine, we can encrypt all our connections using TLS; we enforce this using postconf -e smtpd_use_tls=yes postconf -e smtpd_tls_auth_only=yes Of course, you need to adjust the settings of your IMAP client so that it properly uses TLS and properly authenticates itself. If TLS works, you'll probably want to change the certificate as you have for Dovecot in the previous section. This is again pretty easy. If you haven't yet, now is the time to [[Creating_digital_certificates_with_our_root_certificate | creating that custom SSL certificate]] for our mail server - but you have to make sure that you DON'T use a password on the private key. Unlike Dovecot, Postfix cannot be told the password to the private key somewhere. For starters, look at the TLS-section of your ''main.cf'' that you currently have. Chances are a big chunk of it looks like this: # TLS parameters smtpd_tls_cert_file=/etc/ssl/certs/ssl-cert-snakeoil.pem smtpd_tls_key_file=/etc/ssl/private/ssl-cert-snakeoil.key smtpd_use_tls=yes Now all you need to do is replace the name of the snakeoil-keys with those of appropriate ssl-certificates, the private key of which needs to be NOT passphrase-protected. For this you could copy the Dovecot certificates, if you strip that passphrase in the manner described in the [[Creating_digital_certificates_with_our_root_certificate#Creating_an_SSL_certificate | SSL certificate section]]. The ''main.cf'' then would become: # TLS parameters smtpd_tls_cert_file=/etc/ssl/certs/postfix.pem smtpd_tls_key_file=/etc/ssl/private/postfix.key smtpd_use_tls=yes Restart Postfix, and presto. === Other additions === If everything ''still'' works after these changes, then congratulations, you now have a powerful, flexible and pretty secure mail setup. Of course, there are always points for improvements. We'll cover these in separate pages. One page that we want to direct you to now, is * [[Antispam measures]] for our Postfix mailserver 03053fcd510af7095e755a9eaa06a83ede77925b 0 1477 2092 1774 2009-01-10T15:26:53Z 82.161.20.132 0 /* Installing Asterisk */ wikitext text/x-wiki =Installing Asterisk= Once the hardware configuration part is completed, we can start the installation of Asterisk itself. Using ''aptitude'' or ''apt-get'', install package ''asterisk''. On Debian 5.0 "Lenny", it should be Asterisk 1.4.21.2. With ''apt-get'', the command is simply apt-get install asterisk Note: many, many dependencies bring a lot of extra packages to your server when you install Asterisk. On a test machine, I counted 24 extra packages (for a total of 11.4MB to be downloaded). If you have telephony hardware, you've likely already configured it in the preceding sections. However, when Asterisk itself is installed, you can run the ''genzaptelconf'' command again, and it will not only re-configure your ''zaptel.conf'', but also it will generate ''/etc/asterisk/zapata-channels.conf'' genzaptelconf -svdM -c nl Now, as the command suggests, include the ''zapata-channels.conf'' file in ''/etc/asterisk/zapata.conf'', either by running echo '#include zapata-channels.conf' >>/etc/asterisk/zapata.conf or by opening zapata.conf in your favourite [[vim | text editor]] and pasting the line "#include zapata-channels.conf" (including the hash sign) somewhere near the end of the file. Another measure that you might wish to implement in advance is the addition of two lines for [http://www.voip-info.org/wiki/view/Asterisk+echo+cancellation echo cancellation]: echocancel=yes echocancelwhenbridged=no echotraining=800 When echo cancellation has been turned on, you can also tune two other parameters: the [http://wiki.ljackson.us/Asterisk_Echo rx gain and tx gain]. When you've rerun ''genzaptelconf'', Asterisk will have started at the end of the command. Your adaptation of ''zapata.conf'' is not yet noticed by Asterisk. Please reload or restart asterisk, e.g. by running /etc/init.d/asterisk restart =Installing Asterisk-GUI= Asterisk-GUI is not an essential part of an Asterisk installation, but in some respects it can make life much easier for you. On the other hand, installing it is NOT as easy as with other Debian packages - because it's not available as a Debian package. Thus, we'll have to compile the Asterisk-GUI from source. First obtain the latest version of the ''asterisk-gui'' package; it can be downloaded from the download section of [http://www.asterisk.org/ the Asterisk site]; most likely at [http://downloads.digium.com/pub/telephony/asterisk-gui/releases/ this place]. Then extract it in some logical place, like ''/usr/src/'': tar xzvf asterisk-gui-2.0.2.tar.gz /usr/src This creates the directory ''/usr/src/asterisk-gui-2.0.2'', in which the source for Asterisk-GUI can be found. ''cd'' to this directory, confiure, and compile the software: cd /usr/src/asterisk-gui-2.0.2 ./configure make make install These three commands should complete successfully. They all give pretty clear output when everything runs fine (we haven't seen them fail, so we can't tell what that would look like, or what to do then).<br> OK, so we now need to do some configuration on Asterisk-GUI. It's main configuration files are ''/etc/asterisk/http.conf'', where the Asterisk-GUI itself is configured, and ''/etc/asterisk/manager.conf'', which is part of the Asterisk Manager Interface (AMI), over which Asterisk-GUI makes its moves. So first we put the necessary extra info in ''manager.conf''. The Debian setup for AMI has a line that includes all *.conf files in ''/etc/asterisk/manager.d'', so we only need to include manager-specific information in ''manager.conf''. This means only the following line in the section ''[general]'': webenabled = yes Now we go to ''/etc/asterisk/manager.d'', and create ''asterisk-gui.conf''. In this, we can put the Asterisk-GUI specific lines - which really only define Asterisk-GUI users, with their passwords and their rights: [asterisk-admin] secret = nOguess1ng read = system,call,log,verbose,command,agent,user,config write = system,call,log,verbose,command,agent,user,config Note that this file contains user information (well, it contains Asterisk-GUI user info) with a password, so you might want to secure this file ''/etc/asterisk/manager.d/asterisk-gui.conf'' by changing the owner to asterisk:asterisk, and remove the world-readable attribute chown asterisk:asterisk /etc/asterisk/manager.d/asterisk-gui.conf chmod o= /etc/asterisk/manager.d/asterisk-gui.conf Furthermore, we need to edit the ''/etc/asterisk/http.conf'' file that our Asterisk-GUI installation has created, so that it contains at least the following information (comments stripped): [general] enabled=yes enablestatic=yes bindaddr=127.0.0.1 bindport=8088 prefix=asterisk This enables Asterisk-GUI, so that ''asterisk-admin'' can both issue AMI commands and view HTML pages, as long as a browser on the server itself is used. You could also change the bind address to that of an internal NIC on your server, which is convenient for admins, but less secure. Keep in mind though, that you can also use the [[Firewall section | iceditch firewall]] to limit access to port 8088 to certain subnets and/or IP numbers. Finally, we must work around a little Asterisk-GUI bug, by removing the (empty) directory ''static-http'' from ''/usr/share/asterisk'', and create a link there to the (non-empty) directory ''/var/lib/asterisk/static-http'': cd /usr/share/asterisk rmdir static-http ln -s /var/lib/asterisk/static-http static-http When all is said and done (well, '''done''', specifically), restart Asterisk. Asterisk-GUI should now be reachable on http://127.0.0.1:8088/asterisk/config/cfgbasic.html. Logging in there will make Asterisk-GUI configure itself ''and'' Asterisk. =Configuring and testing Asterisk= If you've done nothing more than the [[Installing and configuring Zaptel | previously described]] hardware installation and configuration, and the default Asterisk installation given above, then you can already do one very simple test: plug a standard analogue telephone in one of your FXS-ports, and see if you get a dialtone. (Ofcourse, if you've only got FXO-ports or no hardware at all, then this won't help you.)<br> Furthermore, you could just look at the back of your Linux machine; the small LEDs next to all ports should be lit green (not including those ports for which you haven't installed a module, ofcourse). A port with a module installed, but without a burning LED, signifies no driver loaded.<br> Other tests and status reports can be obtained from the following commands: * ''lszaptel'' should show your hardware, with all installed ports (all denoted "in use"); non-installed ports may be shown as FXO-ports. Note: be aware of the neverending confusion surrounding the port name (e.g. FXS) and what signalling it runs (e.g. FXO); remember that those two are always opposed: FXO-ports run FXS signaling, FXS-ports run FXO-signaling. Thus, a non-installed port is shown as running FXS-signaling. * ''ztcfg -vv'' should show a channel map, with for each hardware channel the channel number and the signaling protocol. * ''asterisk -r'' should give you an Asterisk console (if Asterisk is in fact running). If the above tests succeed, then it's time for our initial Asterisk configuration. In the first configuration test, we'll configure both an FXS and an FXO channel - since that's what's in [http://downloads.oreilly.com/books/9780596510480.pdf asterisk, TFOTF]. This configuration comes in three parts:<Br> First, we make sure our FXS and FXO channels are defined in ''/etc/zaptel.conf'' - as we've already ensured previously. For this configuration test, we confirm that ''zaptel.conf'' contains something like # Span 1: WCTDM/0 "Wildcard TDM410P Board 1" (MASTER) fxoks=1 fxsks=3 # Global data loadzone = nl defaultzone = nl Next up, we check ''/etc/asterisk/zapata.conf''. When we filter that file through ''grep -v ^\; | grep -v ^$'' (thus removing lines beginning with ";" and empty lines), '''AND''' we insert the contents of ''zapata-channels.conf'' at the place of the insert statement, then we get something like [trunkgroups] [channels] context=default switchtype=national signalling=fxo_ls rxwink=300 usecallerid=yes hidecallerid=no callwaiting=yes usecallingpres=yes callwaitingcallerid=yes threewaycalling=yes transfer=yes canpark=yes cancallforward=yes callreturn=yes echocancel=yes echocancelwhenbridged=yes rxgain=0.0 txgain=0.0 group=1 callgroup=1 pickupgroup=1 immediate=no ; from here it's all zapata_channel.conf: signalling=fxo_ks callerid="Channel 1" <6001> mailbox=6001 group=5 context=from-internal channel => 1 callerid= mailbox= group= context=default signalling=fxo_ks callerid="Channel 2" <6002> mailbox=6002 group=5 context=from-internal channel => 2 callerid= mailbox= group= context=default signalling=fxs_ks callerid=asreceived group=0 context=from-pstn channel => 3 context=default Well that's all nice and dandy, but for testing we'll temporarily replace this ''zapata.conf'' with a much more dressed down one: [trunkgroups] [channels] usecallerid=yes hidecallerid=no callwaiting=no threewaycalling=yes transfer=yes echocancel=yes echotraining=yes switchtype=national ; from here it's all zapata_channel.conf: ; the internal phone on module 1/port 1 context=phones signalling=fxo_ks channel => 1 ; the incoming line on module 3/port 3 context=incoming signalling=fxs_ks channel => 3 The third configuration file we're going to change, is the file containing the "dialplan", which is ''/etc/asterisk/extensions.conf''. We'll use the example from the TFOTF book: [globals] [general] [default] exten => s,1,Verbose(1|Unrouted call handler) exten => s,n,Answer() exten => s,n,Wait(1) exten => s,n,Playback(tt-weasels) exten => s,n,Hangup() [incoming_calls] [internal] exten => 500,1,Verbose(1|Echo test application) exten => 500,n,Echo() exten => 500,n,Hangup() [phones] include => internal [incoming] exten => s,1,Answer() exten => s,n,Echo() With all config files changed (and their owner still ''asterisk:asterisk''), we can reload the necessary files. First we connect an outside line to the FXO port. Now we stop asterisk, then unload the Zaptel drivers, then reload them all (so they'll definately read their config files) (note: our example is for a Digium TDM410P, with driver wctdm24xxp; adapt to your own driver): /etc/init.d/asterisk stop rmmod wctdm24xxp rmmod zaptel modprobe zaptel modprobe wctdm24xxp /etc/init.d/asterisk start For demonstration purposes, start up an Asterisk console (''asterisk -f''). Now we can call the outside line attached to the FXO port (e.g. with a cell phone), and we should see in our Asterisk console something like [Oct 8 09:06:12] NOTICE[5640]: chan_zap.c:6562 ss_thread: Got event 18 (Ring Begin)... [Oct 8 09:06:14] NOTICE[5640]: chan_zap.c:6562 ss_thread: Got event 2 (Ring/Answered)... Furthermore, if you speak into your phone, you should hear an echo. The other test is grabbing the phone that's connected to the FXS port, and dial 500. This also should deliver an echo, albeit much quicker. dc4eeb44f607586016cafe2259a37af937c688e3 0 1488 2094 1952 2009-01-13T20:18:03Z Saruman! 2 /* CA.sh - certificate creation made easy */ added passphrase removal wikitext text/x-wiki ==Preparing for certificate creation== When we're going to create certificates, we're going to use the ''openssl'' command twice: * once to create a "certificate signing request", in which we define all information to be included in the certificate, and actually generate the public and private key parts of the key pair, and * once to instruct the OpenSSL package to sign the certificate with our CA root certificate. The first step thus '''creates''' the actual keypair, and the second step '''signs''' the public key. However, we're going to need to input a lot of parameters on the ''openssl'' command line. We can make things a bit easier for us by specifying these in the ''openssl.cnf'' file, just as we have added some values when creating the CA itself. To be precise, we're going to add '''X.509 V3 extensions''' By default OpenSSL generates V1 certificates, but if we're not extremely worried about offending certain ancient web browsers, we can add V3 extensions, and even make ''openssl'' do that by default. To do this, we find in ''openssl.cnf'' the following line in the section ''[ req ]'', which is likely present but commented out: req_extensions = v3_req # The extensions to add to a certificate request Simply remove the # sign in front of it, so that it appears as given above. This by default enables V3 extensions. Furthermore, check the section ''[ v3_req ]''. It should look like this: [ v3_req ] # Extensions to add to a certificate request basicConstraints = CA:FALSE keyUsage = nonRepudiation, digitalSignature, keyEncipherment subjectKeyIdentifier = hash What is added is the last line, with ''subjectKeyIdentifier''; this line specifies how to identify the public key being certified, so that distinct keys used by the same subject can be differentiated (e.g. as key updating occurs, for example). Four values are possible, but the IETF Public Key Infrastructure (PKIX) working group recommends the setting ''subjectKeyIdentifier=hash'' ==Creating an SSL certificate== Now we can create an SSL certificate for a web server. For the Common Name of the certificate, we need the '''exact''' name of the web server that'll offer the SSL connections. However, some servers run different websites as Virtual Hosts, so they could be running, for example, www.saruman.biz, as well as shop.saruman.biz. That might present a problem, because if the certificate is issued for www.saruman.biz, then each visitor of shop.saruman.biz will get a warning along the lines of "Warning: The website you're trying to visit is shop.saruman.biz, but the certificate offered is for www.saruman.biz". To prevent that, we could use the wildcard character in the name of the certificate, so as to generate a certificate for *.saruman.biz. === CA.sh - certificate creation made easy=== Since we have the ''openssl.cnf'' set up just right, and the ''CA.sh'' script primed, generating an SSL certificate is not very hard. From any old directory, run as root /usr/lib/ssl/misc/CA.sh -newreq This will create the signing request. The questions it'll ask, are * a PEM passphrase, with which to protect the private key of the key pair. Note: you cannot generate a signing request without passphrase, so the private key you'll generate will ''always'' have a passphrase. If this is not what you want, do not despair: you can easily remove the passphrase from the private key after it's been generated (see further down). So just use a passphrase, even if you don't need one. * Country/State/Locality/Organization/Organizational Unit; just as with the CA root certificate creation, these have your preprogrammed defaults that you may or may not change. * Common Name; here we MUST give the DNS name of the host that is going to use the certificate, e.g. ''shop.saruman.biz'', or ''*.saruman.biz''. * Challenge password; leave it blank, it's just to protect your signing request while en-route to the CA - but that's you anyway :-) * Optional company name; leave that blank too, it's also extra information for the CA. Now your private key and your certificate signing request (CSR) are ready; they're called ''newkey.pem'' and ''newreq.pem'' by default, and are located in your working directory. Time to do some signing! From that same working directory, run /usr/lib/ssl/misc/CA.sh -sign The script will show that it's using the config file ''/usr/lib/ssl/openssl.cnf'' (as we indeed wish), and then ask for the super-duper-secret passphrase to the CA private key (provided you've left that in directory ''/etc/ssl/ca/private''). Feed the script the passphrase, and it'll get to work. It'll check the request, then show you the details of the certificate you're about to sign. An example would be Certificate Details: Serial Number: 1 (0x1) Validity Not Before: Oct 27 09:34:00 2008 GMT Not After : Nov 1 09:34:00 2009 GMT Subject: countryName = NL stateOrProvinceName = Utrecht organizationName = Saruman.biz organizationalUnitName = Internet Dept. commonName = shop.saruman.biz emailAddress = webmaster@saruman.biz X509v3 extensions: X509v3 Basic Constraints: CA:FALSE Netscape Comment: OpenSSL Generated Certificate X509v3 Subject Key Identifier: 30:F2:61:80:AA:CF:1B:F0:3E:44:41:D6:38:CC:31:F0:94:28:BD:2B X509v3 Authority Key Identifier: keyid:80:41:F8:A5:1F:C2:27:6E:CF:A9:28:8E:8A:EF:83:E7:FD:8A:D5:26 Certificate is to be certified until Nov 1 09:34:00 2009 GMT (370 days) Sign the certificate? [y/n]: After doing your CA duty and diligently checking all the data, just press ''y''. The script certifies the request, and asks if it is to commit the request. This means it'll update it's own database, by saving a copy of the signed certificate in ''/etc/ssl/ca/newcerts'' named after its serial number (''01.pem'' for this example). Furthermore the script will record the serial and ID's of the generated certificate so that the next certificate will have a new serial number. And now: hey presto! We have a ''newcert.pem'' in our working directory! For good measure: * delete ''newreq.pem'' * rename the generated private key ''newkey.pem'' to ''shop.saruman.biz.seckey.pem'' * rename hte generated public certificate ''newcert.pem'' to ''shop.saruman.biz.pem'' To remove the passphrase from the private key, use a command like this: openssl rsa -in shop.saruman.biz.seckey.pem -out shop.saruman.biz.key.pem This will make ''openssl'' ask for your passphrase, and then create the unsecured ''shop.saruman.biz.key.pem'' key file. Best practice: ALWAYS use a passphrase-protected key, unless the application cannot support it (e.g. Postfix). Save the secure private key and its PEM passphrase in a safe place (e.g. Keepass database). And if you removed the passphrase from the private key, then store it in an even safer place! Now you can deploy your certificate. (more on that in another section). === openssl - the hard way to certificate creation=== We don't actually need to use the ''CA.sh'' script, because we can do manually what the ''CA.sh'' script does. That gives us more control, but also more work. Let's see what we've got to do. We will now perform the first step in our "manual" certificate generation: we create a signing request with all the information that we want in our SSL certificate. We run the magic incantation - note how we already openssl req -new -nodes -keyout webmail.saruman.biz.key.pem -out webmail.saruman.biz.req.pem This generates a new private key (named ''webmail.saruman.biz.key.pem''), and a new, non-encrypted (because of ''-nodes''), key signing request named ''webmail.saruman.biz.req.pem''. We can leave out terms like ''-newkey rsa:2048'' and ''-days 370'' since we've put that in the configuration file. And naturally you're free to choose your own names for the keys. FIXME - need the full process here === Validating the generated certificates=== Again, we can use the ''openssl'' command to validate the keys we've generated. For instance, the ''CA.sh'' generated certificate, after renaming, is verified with openssl x509 -in shop.saruman.biz.pem -noout -purpose Certificate purposes: SSL client : Yes SSL client CA : No SSL server : Yes SSL server CA : No Netscape SSL server : Yes Netscape SSL server CA : No S/MIME signing : Yes S/MIME signing CA : No S/MIME encryption : Yes S/MIME encryption CA : No CRL signing : Yes CRL signing CA : No Any Purpose : Yes Any Purpose CA : Yes OCSP helper : Yes OCSP helper CA : No Notice that the certificate is valid for everything except CA tasks. Likewise, using ''-dates'' instead of ''-purpose'' lets you see the validity time period, and ''-text'' gives the whole text of the certificate. Note the line marked "issuer", and see how your own CA is referenced there. 72c34c68738b605a7725138e873b5ad9bc585c57 0 1434 2096 1537 2009-01-17T17:21:22Z Saruman! 2 added SMW wikitext text/x-wiki ==Installation of MediaWiki== An extra feature we added was support for iFrames by means of a little PHP script that we googled; the extension is called [[The websiteFrame PHP extension| websiteFrame.php]]. Furthermore, we [[wiki footer change |changed the Creative Commons picture]] in the footer from a remote one to a local one. A feature we needed to gain experience for another project was the [http://semantic-mediawiki.org/wiki/Semantic_MediaWiki Semantic MediaWiki (SMW)] extension; it also has a pretty [[Semantic MediaWiki under Debian | simple installation]]. 59eb6a554bcd2fdaa5ccb3954ed29f81bd377e89 2156 2096 2009-01-18T15:19:40Z Saruman! 2 /* Installation of MediaWiki */ added Password Reset extension wikitext text/x-wiki ==Installation of MediaWiki== An extra feature we added was support for iFrames by means of a little PHP script that we googled; the extension is called [[The websiteFrame PHP extension| websiteFrame.php]]. Furthermore, we [[wiki footer change |changed the Creative Commons picture]] in the footer from a remote one to a local one. For user management, we added the extension [[MediaWikiExtension_Password_Reset | Password Reset]]. A feature we needed to gain experience for another project was the [http://semantic-mediawiki.org/wiki/Semantic_MediaWiki Semantic MediaWiki (SMW)] extension; it also has a pretty [[Semantic MediaWiki under Debian | simple installation]]. cbce584eba2c66c511794aa954f5eea22c429cb1 2174 2156 2009-01-20T21:36:58Z Saruman! 2 added grouppermissionsmanager wikitext text/x-wiki ==Installation of MediaWiki== An extra feature we added was support for iFrames by means of a little PHP script that we googled; the extension is called [[The websiteFrame PHP extension| websiteFrame.php]]. Furthermore, we [[wiki footer change |changed the Creative Commons picture]] in the footer from a remote one to a local one. For user management, we added the extensions [[MediaWikiExtension_Password_Reset | Password Reset]] and [[MediaWikiExtension_GroupPermissionsManager | Group Permissions Manager]]. A feature we needed to gain experience for another project was the [http://semantic-mediawiki.org/wiki/Semantic_MediaWiki Semantic MediaWiki (SMW)] extension; it also has a pretty [[Semantic MediaWiki under Debian | simple installation]]. 8a311a3aafff1238377282d8e2a55e3f2687678f 0 1499 2097 2009-01-17T17:28:09Z Saruman! 2 page started wikitext text/x-wiki ==Installing Semantic MediaWiki (SMW) under Debian== Installation consists of these simple steps: 1) Use Aptitude to install package ''mediawiki-semediawiki'' (under Lenny that's version 1.2-1) 2) Add the following lines to your ''LocalSettings.php'' (conveniently located at ''/etc/mediawiki'': include_once("$IP/extensions/SemanticMediaWiki/includes/SMW_Settings.php"); enableSemantics('dworkin.saruman.biz'); Actually, the string for ''enableSemantics'' is an identifier, needed to identify any exported data. The [http://semantic-mediawiki.org/wiki/Help:Installation Semantic MediaWiki website] suggests using the server's host name for this purpose (if you have multiple hostnames, just pick any one of them). 3) Adjust your namespaces - since we haven't modified the MediaWiki namespaces relative to the original Debian installation, we don't need that. 4) Setup the SMW tables in the MySQL database. To this end, we simply go to 5109f09a041989fc27c60611a55389dfbe00f311 2099 2097 2009-01-17T18:39:21Z Saruman! 2 /* Installing Semantic MediaWiki (SMW) under Debian */ updated for Debian - tmp wikitext text/x-wiki ==Installing Semantic MediaWiki (SMW) under Debian== Installation consists of these simple steps: 1) Use Aptitude to install package ''mediawiki-semediawiki'' (under Lenny that's version 1.2-1) 2) Edit the file ''/etc/mediawiki-extensions/extensions-available/SemanticMediaWiki.php''. All you need to do is change the string for ''enableSemantics'' from ''localhost'' to the hostname of your server: <?php include_once('extensions/SemanticMediaWiki/includes/SMW_Settings.php'); enableSemantics('dworkin.saruman.biz'); ?> Actually, the string for ''enableSemantics'' is an identifier, needed to identify any exported data. The [http://semantic-mediawiki.org/wiki/Help:Installation Semantic MediaWiki website] suggests using the server's host name for this purpose (if you have multiple hostnames, just pick any one of them). 3) We now run the maintenance script that sets up the MySQL database. This is a two-step affair: - first set the MW_INSTALL_PATH environment variable to the root of the MediaWiki installation. This path is where ''LocalSettings.php'' and ''index.php'' are located; most likely it's ''/usr/share/mediawiki''. MW_INSTALL_PATH=/usr/share/mediawiki export $MW_INSTALL_PATH cd /usr/share/mediawiki-semediawiki/maintenance 4) Adjust your namespaces - since we haven't modified the MediaWiki namespaces relative to the original Debian installation, we don't need that. 4) Setup the SMW tables in the MySQL database. To this end, we simply go to 0443c109cf5c7bd05dd836e02b6ae5d281789b55 2100 2099 2009-01-17T18:53:17Z Saruman! 2 further adjusted SMW-setup wikitext text/x-wiki ==Installing Semantic MediaWiki (SMW) under Debian== Installation consists of these simple steps: 1) Use Aptitude to install package ''mediawiki-semediawiki'' (under Lenny that's version 1.2-1) 2) Edit the file ''/etc/mediawiki-extensions/extensions-available/SemanticMediaWiki.php''. All you need to do is change the string for ''enableSemantics'' from ''localhost'' to the hostname of your server: <?php include_once('extensions/SemanticMediaWiki/includes/SMW_Settings.php'); enableSemantics('dworkin.saruman.biz'); ?> Actually, the string for ''enableSemantics'' is an identifier, needed to identify any exported data. The [http://semantic-mediawiki.org/wiki/Help:Installation Semantic MediaWiki website] suggests using the server's host name for this purpose (if you have multiple hostnames, just pick any one of them). 3) Enable the SMW extension, by creating a link to it under ''/etc/mediawiki-extensions/extensions-enabled'': cd /etc/mediawiki-extensions/extensions-enabled/ ln -s ../extensions-available/SemanticMediaWiki.php 4) We now run the maintenance script that sets up the MySQL database. This is a two-step affair:<br> - first set the MW_INSTALL_PATH environment variable to the root of the MediaWiki installation. This path is where ''LocalSettings.php'' and ''index.php'' are located; most likely it's ''/usr/share/mediawiki''.<br> - then go to the directory where the SMW maintenance scripts are located, and execute ''SMW_setup.php''.<br> The sequence will thus look something like this: MW_INSTALL_PATH=/usr/share/mediawiki export $MW_INSTALL_PATH cd /usr/share/mediawiki-semediawiki/maintenance php SMW_setup.php The php-script should report setting up some nine tables, named ''smw_ids'', ''smw_redi2'' et cetera. These are the extra MySQL tables that SMW needs. 5) Adjust your namespaces - since we haven't modified the MediaWiki namespaces relative to the original Debian installation, we don't need that. cacc9d96e0196fd84cfcc9f14f9367c0ff8f7514 2102 2100 2009-01-17T19:03:55Z Saruman! 2 Finished SMW installation instructions. wikitext text/x-wiki ==Installing Semantic MediaWiki (SMW) under Debian== Installation consists of these simple steps: 1) Use Aptitude to install package ''mediawiki-semediawiki'' (under Lenny that's version 1.2-1) 2) Adjust your namespaces - since we haven't modified the MediaWiki namespaces relative to the original Debian installation, we don't need that. 3) Edit the file ''/etc/mediawiki-extensions/extensions-available/SemanticMediaWiki.php''. All you need to do is change the string for ''enableSemantics'' from ''localhost'' to the hostname of your server: <?php include_once('extensions/SemanticMediaWiki/includes/SMW_Settings.php'); enableSemantics('dworkin.saruman.biz'); ?> Actually, the string for ''enableSemantics'' is an identifier, needed to identify any exported data. The [http://semantic-mediawiki.org/wiki/Help:Installation Semantic MediaWiki website] suggests using the server's host name for this purpose (if you have multiple hostnames, just pick any one of them). 4) Enable the SMW extension, by creating a link to it under ''/etc/mediawiki-extensions/extensions-enabled'': cd /etc/mediawiki-extensions/extensions-enabled/ ln -s ../extensions-available/SemanticMediaWiki.php 5) We now run the maintenance script that creates the necessary tables in your MySQL MediaWiki database. This is a two-step affair:<br> - first set the MW_INSTALL_PATH environment variable to the root of the MediaWiki installation. This path is where ''LocalSettings.php'' and ''index.php'' are located; most likely it's ''/usr/share/mediawiki''.<br> - then go to the directory where the SMW maintenance scripts are located, and execute ''SMW_setup.php''.<br> The sequence will thus look something like this: MW_INSTALL_PATH=/usr/share/mediawiki export $MW_INSTALL_PATH cd /usr/share/mediawiki-semediawiki/maintenance php SMW_setup.php The php-script should report setting up some nine tables, named ''smw_ids'', ''smw_redi2'' et cetera. These are the extra MySQL tables that SMW needs. 6) Next, log into your MediaWiki with an account with administrative rights. If you now visit your ''Special pages'', you'll find taht under the section ''Restricted special pages'' there is now an entry titled ''Admin functions for Semantic MediaWiki''. Open it, and find two sections: * '''Preparing database for Semantic MediaWiki'''<br>Here you'll have to press the button labeled ''Initialise or upgrade tables''; this will initialise the newly created tables. A dull page should appear, reporting actions for each of the nine new tables, and ending with the status message ''The storage engine was set up successfully.'' * '''Announce your wiki'''<br>Clicking this button is optional; what it will do is post the URL of your wiki on the [http://semantic-mediawiki.org/wiki/Special:SMWRegistry SMW Registry page] over on the SMW site. <br> <br> That's it! You can now start [http://semantic-mediawiki.org/wiki/Help:User_manual using SMW]. 78abeb74a7515cbc802833f3a5a5c49f0107ae61 2106 2102 2009-01-17T20:09:36Z Saruman! 2 /* Installing Semantic MediaWiki (SMW) under Debian */ added mwenext wikitext text/x-wiki ==Installing Semantic MediaWiki (SMW) under Debian== Installation consists of these simple steps: 1) Use Aptitude to install package ''mediawiki-semediawiki'' (under Lenny that's version 1.2-1) 2) Adjust your namespaces - since we haven't modified the MediaWiki namespaces relative to the original Debian installation, we don't need that. 3) Edit the file ''/etc/mediawiki-extensions/extensions-available/SemanticMediaWiki.php''. All you need to do is change the string for ''enableSemantics'' from ''localhost'' to the hostname of your server: <?php include_once('extensions/SemanticMediaWiki/includes/SMW_Settings.php'); enableSemantics('dworkin.saruman.biz'); ?> Actually, the string for ''enableSemantics'' is an identifier, needed to identify any exported data. The [http://semantic-mediawiki.org/wiki/Help:Installation Semantic MediaWiki website] suggests using the server's host name for this purpose (if you have multiple hostnames, just pick any one of them). 4) Enable the SMW extension, by creating a link to it under ''/etc/mediawiki-extensions/extensions-enabled'': cd /etc/mediawiki-extensions/extensions-enabled/ ln -s ../extensions-available/SemanticMediaWiki.php By the way, this should also work with the MediaWiki extension enabler command: mwenext SemanticMediaWiki.php 5) We now run the maintenance script that creates the necessary tables in your MySQL MediaWiki database. This is a two-step affair:<br> - first set the MW_INSTALL_PATH environment variable to the root of the MediaWiki installation. This path is where ''LocalSettings.php'' and ''index.php'' are located; most likely it's ''/usr/share/mediawiki''.<br> - then go to the directory where the SMW maintenance scripts are located, and execute ''SMW_setup.php''.<br> The sequence will thus look something like this: MW_INSTALL_PATH=/usr/share/mediawiki export $MW_INSTALL_PATH cd /usr/share/mediawiki-semediawiki/maintenance php SMW_setup.php The php-script should report setting up some nine tables, named ''smw_ids'', ''smw_redi2'' et cetera. These are the extra MySQL tables that SMW needs. 6) Next, log into your MediaWiki with an account with administrative rights. If you now visit your ''Special pages'', you'll find taht under the section ''Restricted special pages'' there is now an entry titled ''Admin functions for Semantic MediaWiki''. Open it, and find two sections: * '''Preparing database for Semantic MediaWiki'''<br>Here you'll have to press the button labeled ''Initialise or upgrade tables''; this will initialise the newly created tables. A dull page should appear, reporting actions for each of the nine new tables, and ending with the status message ''The storage engine was set up successfully.'' * '''Announce your wiki'''<br>Clicking this button is optional; what it will do is post the URL of your wiki on the [http://semantic-mediawiki.org/wiki/Special:SMWRegistry SMW Registry page] over on the SMW site. <br> <br> That's it! You can now start [http://semantic-mediawiki.org/wiki/Help:User_manual using SMW]. 22ea0aaa1dea0b0f2754239180953dc80ce9277c 0 1 2150 1985 2009-01-18T08:48:27Z Saruman! 2 added link to Apache/PHP for LAMP wikitext text/x-wiki <big>'''Welcome to SaruWiki.'''</big> This Wiki is intended to document bits and bobs about [http://www.kernel.org/ Linux] (and some Unix) in general, and [http://www.debian.org Debian] in particular. In it, [[SaruWiki:About|we]] wish to collect the tips and tricks of both [[SaruWiki:About|our own team of Linux admins]] and those of other interested users. Consult the [http://meta.wikimedia.org/wiki/Help:Contents User's Guide] for information on using this wiki's software. <big>NOTE:</big> '''you must confirm edits''' when you're not logged in with a user account. Thanks to the Mediawiki ConfirmEdit extension we've cut our wikispam considerably. Sorry to make you anonymous contributors jump through this little hoop for every edit, but there you are. ---- <big>'''Main Content'''</big> * Setting up a [[Debian Lenny base server]] is a howto on the installation of a very basic Linux box under Lenny (it's actually not even a server yet). * The use of [[APT and aptitude]] is crucial to the concept of a Debian machine. * [[Roll your own kernel]] discusses the pros and cons of compiling your own kernel, and how to do it. * [[Essential system software]] lists all (sets of) packages that we deem, well, essential. * [[Apache2 and PHP5]] are essential packages if you want to light your own little [[LAMP]]. * [[Pluggable Authentication Modules (PAM)]] is a great way to secure your server and arrange logins - if you get to understand them * [[Certificate fundamentals | The "certificates" section]] explains how you create your own Certificate Authority (CA) and the neat things you can do with it. * [[Database 101]] introduces you to MySQL. * [[OpenLDAP]] is a rudimentary howto about getting OpenLDAP to be your central user repository. * The [[Installing SaMBa with OpenLDAP support | SaMBa section]] explains how to install SaMBa with OpenLDAP as user backend. * [[Add an X11 server]] to your server, if you need one. * Of course we have a [[e-mail server section]], where we focus on Postfix and virtual mail domains, and add in a whiff of MySQL and OpenLDAP. * The [[Asterisk section]] is about all things re: telephony on Debian Lenny. * The [[system boot procedure]] section explains what we can customise in the standard ways Debian boots. * The [[networking section]] treats subjects like setting persistent routes. * The [[firewall section]] is where we discuss "IPtables" (netfilter) and how we use it for firewalling. * The [[native IPsec tunnel]] section describes how to configure an IPsec tunnel. * Using ''md'' for [[software RAID]] contains our ideas and observations on redundancy. * [[Hardware monitoring]] is important for your server's health and reliability. * [[Vmware_server|VMware Server basics]] gives some pointers on how to install VMware Server on a Debian server box. * Make your server a [[Microsoft PPTP server | Microsoft client compatible VPN Server ]]. * How to install [[Mediawiki Installation | Mediawiki]] on your Debian server - like what you're looking at now. ---- '''Note''': the Wiki admins reserve the right to edit or remove any content they feel is not suitable for this site, not relevant, (too) inaccurate or otherwise not in line with the intentions and spirit of the admin team. ---- <websiteFrame> website=http://www.google.com/talk/service/badge/Show?tk&#61;z01q6amlqld8jocej2ca891jl9dunqqra83nhehaoqpednb5skkur0fv70jsuavce4ii9ms5e9afdr8qmpsc1d9upni4jom8g1em3p1cvq1p5eo1ugv162fosgprdv867iuememlcogfle8n3dmcf97durjld85avnh8k5lm1&amp;w=200&amp;h=60 border=0 height=60 width=200 name=GoogleChatwithSaruman! allowtransparency=true </websiteFrame> 1614dcb9622b66fccf7761c006b94ad565e9d5d6 2203 2150 2009-01-22T16:46:21Z Saruman! 2 added inputbox (but have to add the extension as well :-) wikitext text/x-wiki <big>'''Welcome to SaruWiki.'''</big> This Wiki is intended to document bits and bobs about [http://www.kernel.org/ Linux] (and some Unix) in general, and [http://www.debian.org Debian] in particular. In it, [[SaruWiki:About|we]] wish to collect the tips and tricks of both [[SaruWiki:About|our own team of Linux admins]] and those of other interested users. Consult the [http://meta.wikimedia.org/wiki/Help:Contents User's Guide] for information on using this wiki's software. <big>NOTE:</big> '''you must confirm edits''' when you're not logged in with a user account. Thanks to the Mediawiki ConfirmEdit extension we've cut our wikispam considerably. Sorry to make you anonymous contributors jump through this little hoop for every edit, but there you are. ---- <big>'''Main Content'''</big> * Setting up a [[Debian Lenny base server]] is a howto on the installation of a very basic Linux box under Lenny (it's actually not even a server yet). * The use of [[APT and aptitude]] is crucial to the concept of a Debian machine. * [[Roll your own kernel]] discusses the pros and cons of compiling your own kernel, and how to do it. * [[Essential system software]] lists all (sets of) packages that we deem, well, essential. * [[Apache2 and PHP5]] are essential packages if you want to light your own little [[LAMP]]. * [[Pluggable Authentication Modules (PAM)]] is a great way to secure your server and arrange logins - if you get to understand them * [[Certificate fundamentals | The "certificates" section]] explains how you create your own Certificate Authority (CA) and the neat things you can do with it. * [[Database 101]] introduces you to MySQL. * [[OpenLDAP]] is a rudimentary howto about getting OpenLDAP to be your central user repository. * The [[Installing SaMBa with OpenLDAP support | SaMBa section]] explains how to install SaMBa with OpenLDAP as user backend. * [[Add an X11 server]] to your server, if you need one. * Of course we have a [[e-mail server section]], where we focus on Postfix and virtual mail domains, and add in a whiff of MySQL and OpenLDAP. * The [[Asterisk section]] is about all things re: telephony on Debian Lenny. * The [[system boot procedure]] section explains what we can customise in the standard ways Debian boots. * The [[networking section]] treats subjects like setting persistent routes. * The [[firewall section]] is where we discuss "IPtables" (netfilter) and how we use it for firewalling. * The [[native IPsec tunnel]] section describes how to configure an IPsec tunnel. * Using ''md'' for [[software RAID]] contains our ideas and observations on redundancy. * [[Hardware monitoring]] is important for your server's health and reliability. * [[Vmware_server|VMware Server basics]] gives some pointers on how to install VMware Server on a Debian server box. * Make your server a [[Microsoft PPTP server | Microsoft client compatible VPN Server ]]. * How to install [[Mediawiki Installation | Mediawiki]] on your Debian server - like what you're looking at now. If you'd like to create a new page, please log in and go ahead: <inputbox> type=create </inputbox> ---- '''Note''': the Wiki admins reserve the right to edit or remove any content they feel is not suitable for this site, not relevant, (too) inaccurate or otherwise not in line with the intentions and spirit of the admin team. ---- <websiteFrame> website=http://www.google.com/talk/service/badge/Show?tk&#61;z01q6amlqld8jocej2ca891jl9dunqqra83nhehaoqpednb5skkur0fv70jsuavce4ii9ms5e9afdr8qmpsc1d9upni4jom8g1em3p1cvq1p5eo1ugv162fosgprdv867iuememlcogfle8n3dmcf97durjld85avnh8k5lm1&amp;w=200&amp;h=60 border=0 height=60 width=200 name=GoogleChatwithSaruman! allowtransparency=true </websiteFrame> 09aeb32beb0f1743fd44283754eaaad6f302a67f 0 1506 2151 2009-01-18T08:57:13Z Saruman! 2 Acronym explained wikitext text/x-wiki ==L.A.M.P.== LAMP is an acronym: it usually stands for * '''L'''inux, the operating system (well, actually only the kernel - so "Linux" actually refers to "GNU/Linux" - but "GAMP" or "GLAMP" just aren't nice acronyms :-) * '''A'''pache, the web server * '''M'''ySQL, the database server * '''P'''HP, the dynamic web page scripting language However, under ''P'' you sometimes find Perl or Python. With this acronym "LAMP", people can refer to a solution stack of software, which can run (dynamic) web sites. An extremely nice feature of this software stack is that it consists only of open source components, giving you all the benefits of OS; another equally nice feature is that the stack can be realized for free, e.g. using the Debian distribution, or just very cheap, using a commercial distribution like Red Hat or SuSE. 201eb4c4c4e6f163b6bf6d36846bdfc2453a0c6b 0 1507 2152 2009-01-18T09:15:25Z Saruman! 2 Page started wikitext text/x-wiki ==Apache2 and PHP5== ===Installation of Apache2=== Contribution needed. ===Configuration of Apache2=== Once Apache2 is in place, you might want to [[Enabling SSL for Apache2 | enable SSL]] for it. ===Installation of PHP5=== Contribution needed. 9d1826384bb09bd03e7f5b21da3e1a68a0f4e7d9 0 1508 2153 2009-01-18T11:21:44Z Saruman! 2 Page started wikitext text/x-wiki ==Apache2 and SSL== ===The problem with SSL and Virtual Hosting=== To enable SSL for Apache2, you must first realise some important limitations. First off: let's look at simple HTTP. One Apache instance can run multiple websites on one server (one IP address), as so-called virtual hosts. The visitors type in any one of your websites (www.saruman.biz or www.iceditch.nl), get the same IP number (212.238.151.172), and send the HTTP request there, on port 80. Apache receives the request, looks in it, notices the actual URI in it (say: http://www.saruman.biz or http://www.saruman.biz/wiki/index.php/Main_Page), and directs the request to the right website, the right virtual host. Now consider what happens if we introduce SSL: any request to the HTTPS-port of the server (port 443) is encrypted using the public SSL-certificate of the server. However, this certificate is investigated by the browser of your visitors - one of the (sets of) things that must match, is the common name of the certificate (which must match the DNS-name of the website your visitor is visiting). Thus, a visitor for https://www.saruman.biz expects the SSL certificate to be in the name of www.saruman.biz, but a visitor for https://www.iceditch.nl expects the certificate to be in the name of www.iceditch.nl. Reasonable, eh? But wait - the single Apache2 webserver can have multiple websites, but only ''one'' SSL certificate! And that'll be presented to the visitor ''before'' Apache gets to hear which virtual host the visitor wants to visit. This means that when multiple virtual hosts on a single Apache2 webserver are "put on SSL", they all share the same SSL certificate. And this means that if we have an SSL certificate for www.saruman.biz, that visitors to the HTTPS-version of www.saruman.biz will be presented the "right" SSL certificate, but visitors to the HTTPS-version of www.iceditch.nl will get a certificate for www.saruman.biz as well - leading to nagging warnings in the browser of each one of your visitors. In effect, you can run only ''one'' virtual host, that's accessible over HTTPS, and gets no raised eyebrows on the certificate name issue. SO! Is this a totally unavoidable problem? For most situations: yes. But in some cases there are workarounds. ===Two solutions for the problem of SSL Certificate names and Virtual Hosting=== ===SSL for your main protected website=== First we determine which one of our virtual hosts (assuming you have multiple) we need to provide SSL for. If you have multiple IP numbers for your servers, then you can select the same number of virtual hosts without running into the problems described previously. The only prerequisite for this is, that you've mapped each of those virtual hosts to a different IP number, so that a request to virtual host "one" gets resolved to IP address "one", virtual host "two" to IP address "two" et cetera. Now we can start by obtaining the necessary SSL certificates. dfd3be1564b61c51c6edc8ce100d059b9b381499 2158 2153 2009-01-18T16:20:12Z Saruman! 2 expounded SSL certificates to include wildcards wikitext text/x-wiki ==Apache2 and SSL== ===The problem with SSL and Virtual Hosting=== To enable SSL for Apache2, you must first realise some important limitations. This section is meant to outline these limitations. First off: let's look at simple HTTP traffic, something that has nothing to do with SSL - but bear with me. One Apache instance can run multiple websites on one server (one IP address), as so-called virtual hosts. First off, let's assume we have one single server, serving two websites. These can be found using two different DNS names, e.g. www.saruman.biz and www.iceditch.nl. Now suppose a visitor wants to visit one of these sites. The visitor types in a URI pertaining to any one of the websites (containing the DNS name www.saruman.biz or www.iceditch.nl). In both cases he gets the same IP number (212.238.151.172), so his browser sends the HTTP request there, on port 80. Apache receives the request, looks in it, notices the actual URI in it (say: http://www.iceditch.nl/index.htm or http://www.saruman.biz/wiki/index.php/Main_Page), and directs the request to the right website, the right virtual host. So far, no problem at all. Now consider what happens if we introduce SSL: any request to the HTTPS-port of the server (port 443) gets encrypted using the public SSL-certificate of the server. However, before using it, this certificate is investigated by the browser of the visitor - one of the (sets of) things that must match, is the common name of the certificate (which must match the DNS-name of the website the visitor is visiting). Thus, a visitor for https://www.saruman.biz expects the SSL certificate to be in the name of www.saruman.biz, and so does his browser. But a visitor for https://www.iceditch.nl expects the certificate to be in the name of www.iceditch.nl. Reasonable, eh? But wait - the single Apache2 webserver can have multiple websites, but only ''one'' SSL certificate! And that'll be presented to the visitor at the setup of the HTTPS session, ''before'' Apache gets to hear which virtual host the visitor wants to visit. This means that when multiple virtual hosts on a single Apache2 webserver are "put on SSL", they all share the same SSL certificate. And this means that if we have an SSL certificate for www.saruman.biz, that visitors to the HTTPS-version of www.saruman.biz will be presented the "right" SSL certificate, but visitors to the HTTPS-version of www.iceditch.nl will get a certificate for www.saruman.biz as well - leading to nagging warnings in the browser of each one of your visitors. In effect, you can run only ''one'' virtual host, that's accessible over HTTPS, and gets no raised eyebrows on the certificate name issue. SO! Is this a totally unavoidable problem? For most situations: yes. But in some cases there are workarounds. ===A solution for the problem of SSL Certificate names and Virtual Hosting=== One workaround would be to have two IP numbers for your server, and have two instances of Apache2 listen on port 443: one instance on the IP of www.saruman.biz, and hosting virtual site www.saruman.biz, and using an SSL certificate for www.saruman.biz. The other instance could then listen on the IP number for www.iceditch.nl and use an SSL certificate signed correspondingly. Simple, effective - but requiring multiple IP numbers, and sort of defeating the reason for having virtual hosting in the first place. A better workaround is to have all virtual hosts be hosted on URI's that are based on the same toplevel domain, e.g. www.saruman.biz, shop.saruman.biz, webmail.saruman.biz etcetera. When multiple virtual hosts share a common DNS domain, then the (single) SSL certificate for these (multiple) virtual hosts could be based on a wildcard SSL certificate name - in this case *.saruman.biz. The certificate would match all those virtual hosts. Alas, it still wouldn't match www.iceditch.nl... ===SSL for your main protected website=== First we determine which one of our virtual hosts (assuming you have multiple) we need to provide SSL for. If you have multiple IP numbers for your servers, then you can select the same number of virtual hosts without running into the problems described previously. The only prerequisite for this is, that you've mapped each of those virtual hosts to a different IP number, so that a request to virtual host "one" gets resolved to IP address "one", virtual host "two" to IP address "two" et cetera. Now we can start by obtaining the necessary SSL certificates. 781e4a1448ab7eaa627ce75206b29ed7be4025a2 2159 2158 2009-01-18T20:56:12Z Saruman! 2 started SSL process wikitext text/x-wiki ==Apache2 and SSL== ===The problem with SSL and Virtual Hosting=== To enable SSL for Apache2, you must first realise some important limitations. This section is meant to outline these limitations. First off: let's look at simple HTTP traffic, something that has nothing to do with SSL - but bear with me. One Apache instance can run multiple websites on one server (one IP address), as so-called virtual hosts. First off, let's assume we have one single server, serving two websites. These can be found using two different DNS names, e.g. www.saruman.biz and www.iceditch.nl. Now suppose a visitor wants to visit one of these sites. The visitor types in a URI pertaining to any one of the websites (containing the DNS name www.saruman.biz or www.iceditch.nl). In both cases he gets the same IP number (212.238.151.172), so his browser sends the HTTP request there, on port 80. Apache receives the request, looks in it, notices the actual URI in it (say: http://www.iceditch.nl/index.htm or http://www.saruman.biz/wiki/index.php/Main_Page), and directs the request to the right website, the right virtual host. So far, no problem at all. Now consider what happens if we introduce SSL: any request to the HTTPS-port of the server (port 443) gets encrypted using the public SSL-certificate of the server. However, before using it, this certificate is investigated by the browser of the visitor - one of the (sets of) things that must match, is the common name of the certificate (which must match the DNS-name of the website the visitor is visiting). Thus, a visitor for https://www.saruman.biz expects the SSL certificate to be in the name of www.saruman.biz, and so does his browser. But a visitor for https://www.iceditch.nl expects the certificate to be in the name of www.iceditch.nl. Reasonable, eh? But wait - the single Apache2 webserver can have multiple websites, but only ''one'' SSL certificate! And that'll be presented to the visitor at the setup of the HTTPS session, ''before'' Apache gets to hear which virtual host the visitor wants to visit. This means that when multiple virtual hosts on a single Apache2 webserver are "put on SSL", they all share the same SSL certificate. And this means that if we have an SSL certificate for www.saruman.biz, that visitors to the HTTPS-version of www.saruman.biz will be presented the "right" SSL certificate, but visitors to the HTTPS-version of www.iceditch.nl will get a certificate for www.saruman.biz as well - leading to nagging warnings in the browser of each one of your visitors. In effect, you can run only ''one'' virtual host, that's accessible over HTTPS, and gets no raised eyebrows on the certificate name issue. SO! Is this a totally unavoidable problem? For most situations: yes. But in some cases there are workarounds. ===A solution for the problem of SSL Certificate names and Virtual Hosting=== One workaround would be to have two IP numbers for your server, and have two instances of Apache2 listen on port 443: one instance on the IP of www.saruman.biz, and hosting virtual site www.saruman.biz, and using an SSL certificate for www.saruman.biz. The other instance could then listen on the IP number for www.iceditch.nl and use an SSL certificate signed correspondingly. Simple, effective - but requiring multiple IP numbers, and sort of defeating the reason for having virtual hosting in the first place. We hesitate to call this a true "workaround". Another workaround would be to have multiple Apache2 instances listen on the ''same'' IP number, but on ''different'' ports: only one could sit behind the port that's default for HTTPS (443); any other site would have to sit behind another port (e.g. 444). This however would force users to type the port in with the URI. In our example: if www.saruman.biz sits behind 443, then www.iceditch.nl could have an SSL protected site behind port 444, but visitors would have to use the URI ''https://www.iceditch.nl:444/index.htm''. Not the handiest or prettiest solution either. A much better workaround, unfortunately of limited applicability, is to have all virtual hosts be hosted on URI's that are based on the same toplevel domain, e.g. www.saruman.biz, shop.saruman.biz, webmail.saruman.biz etcetera. When multiple virtual hosts share a common DNS domain, then the (single) SSL certificate for these (multiple) virtual hosts could be based on a wildcard SSL certificate name - in this case *.saruman.biz. The certificate would match all those virtual hosts. Alas, it still wouldn't match www.iceditch.nl... If you cannot implement either one of these two "solutions", then you're stuck with this: you can have ''one'' website behind SSL encryption with a matching SSL certificate; any other website that your Apache webserver is serving will have to do without SSL, or with a nasty error message for every visitor, every time they visit the site. ===SSL for your main protected website=== OK, let's assume you cannot employ either of the two offered "workarounds", or don't need multiple SSL sites to begin with. We can now determine which one of our virtual hosts (assuming you have multiple) we want to provide SSL for. We'll say that the website that this virtual host is serving is the main protected website. With www.saruman.biz as our example, let's implement SSL. We can start by obtaining the necessary SSL certificates. We determine that the site is located at URI www.saruman.biz, and request an SSL certificate for www.saruman.biz (or for *.saruman.biz) from a trusted Certificate Authority (CA) such as Thawte. Optionally, we generate our own SSL certificate, as has been described in the [[Certificate_fundamentals | certificate section]]. Note that we need the private key to be without passphrase. Let's suppose we have the certificates, and we (re)name them "apache2.pem" and "apache2.unsec.key". As a sidenote: you ''could'' leave the private key protected with a password ("apache2.sec.key" as it were), but then every time you restart your webserver ''and'' every time you (re)boot your server, Apache2 would have to ask you for the passphrase. Not practical for most solutions. Let's just store the unsecured private key in a very secure fashion. We can store the two files (key and certificate) in what is considere the default SSL location (''/etc/ssl/'', in subdirectories ''certs'' and ''private'') but for Apache2 it seems to be common to store the key and certificate in directory ''/etc/apache2/ssl''. Make absolutely sure that the key file is owned by ''root:root'' and ''chmod''ded to 400; and for neatness you might want to make it so that the certificate is owned by ''www-data:www-data'' and ''chmod''ded to 444. Thus: bdb2a36d470197b564ddb4a47a850ad19ecceb9f 2160 2159 2009-01-18T21:03:12Z Saruman! 2 /* SSL for your main protected website */ certificates finished wikitext text/x-wiki ==Apache2 and SSL== ===The problem with SSL and Virtual Hosting=== To enable SSL for Apache2, you must first realise some important limitations. This section is meant to outline these limitations. First off: let's look at simple HTTP traffic, something that has nothing to do with SSL - but bear with me. One Apache instance can run multiple websites on one server (one IP address), as so-called virtual hosts. First off, let's assume we have one single server, serving two websites. These can be found using two different DNS names, e.g. www.saruman.biz and www.iceditch.nl. Now suppose a visitor wants to visit one of these sites. The visitor types in a URI pertaining to any one of the websites (containing the DNS name www.saruman.biz or www.iceditch.nl). In both cases he gets the same IP number (212.238.151.172), so his browser sends the HTTP request there, on port 80. Apache receives the request, looks in it, notices the actual URI in it (say: http://www.iceditch.nl/index.htm or http://www.saruman.biz/wiki/index.php/Main_Page), and directs the request to the right website, the right virtual host. So far, no problem at all. Now consider what happens if we introduce SSL: any request to the HTTPS-port of the server (port 443) gets encrypted using the public SSL-certificate of the server. However, before using it, this certificate is investigated by the browser of the visitor - one of the (sets of) things that must match, is the common name of the certificate (which must match the DNS-name of the website the visitor is visiting). Thus, a visitor for https://www.saruman.biz expects the SSL certificate to be in the name of www.saruman.biz, and so does his browser. But a visitor for https://www.iceditch.nl expects the certificate to be in the name of www.iceditch.nl. Reasonable, eh? But wait - the single Apache2 webserver can have multiple websites, but only ''one'' SSL certificate! And that'll be presented to the visitor at the setup of the HTTPS session, ''before'' Apache gets to hear which virtual host the visitor wants to visit. This means that when multiple virtual hosts on a single Apache2 webserver are "put on SSL", they all share the same SSL certificate. And this means that if we have an SSL certificate for www.saruman.biz, that visitors to the HTTPS-version of www.saruman.biz will be presented the "right" SSL certificate, but visitors to the HTTPS-version of www.iceditch.nl will get a certificate for www.saruman.biz as well - leading to nagging warnings in the browser of each one of your visitors. In effect, you can run only ''one'' virtual host, that's accessible over HTTPS, and gets no raised eyebrows on the certificate name issue. SO! Is this a totally unavoidable problem? For most situations: yes. But in some cases there are workarounds. ===A solution for the problem of SSL Certificate names and Virtual Hosting=== One workaround would be to have two IP numbers for your server, and have two instances of Apache2 listen on port 443: one instance on the IP of www.saruman.biz, and hosting virtual site www.saruman.biz, and using an SSL certificate for www.saruman.biz. The other instance could then listen on the IP number for www.iceditch.nl and use an SSL certificate signed correspondingly. Simple, effective - but requiring multiple IP numbers, and sort of defeating the reason for having virtual hosting in the first place. We hesitate to call this a true "workaround". Another workaround would be to have multiple Apache2 instances listen on the ''same'' IP number, but on ''different'' ports: only one could sit behind the port that's default for HTTPS (443); any other site would have to sit behind another port (e.g. 444). This however would force users to type the port in with the URI. In our example: if www.saruman.biz sits behind 443, then www.iceditch.nl could have an SSL protected site behind port 444, but visitors would have to use the URI ''https://www.iceditch.nl:444/index.htm''. Not the handiest or prettiest solution either. A much better workaround, unfortunately of limited applicability, is to have all virtual hosts be hosted on URI's that are based on the same toplevel domain, e.g. www.saruman.biz, shop.saruman.biz, webmail.saruman.biz etcetera. When multiple virtual hosts share a common DNS domain, then the (single) SSL certificate for these (multiple) virtual hosts could be based on a wildcard SSL certificate name - in this case *.saruman.biz. The certificate would match all those virtual hosts. Alas, it still wouldn't match www.iceditch.nl... If you cannot implement either one of these two "solutions", then you're stuck with this: you can have ''one'' website behind SSL encryption with a matching SSL certificate; any other website that your Apache webserver is serving will have to do without SSL, or with a nasty error message for every visitor, every time they visit the site. ===SSL for your main protected website=== OK, let's assume you cannot employ either of the two offered "workarounds", or don't need multiple SSL sites to begin with. We can now determine which one of our virtual hosts (assuming you have multiple) we want to provide SSL for. We'll say that the website that this virtual host is serving is the main protected website. With www.saruman.biz as our example, let's implement SSL. We can start by obtaining the necessary SSL certificates. We determine that the site is located at URI www.saruman.biz, and request an SSL certificate for www.saruman.biz (or for *.saruman.biz) from a trusted Certificate Authority (CA) such as Thawte. Optionally, we generate our own SSL certificate, as has been described in the [[Certificate_fundamentals | certificate section]]. Note that we need the private key to be without passphrase. Let's suppose we have the certificates, and we (re)name them "apache2.pem" and "apache2.unsec.key". As a sidenote: you ''could'' leave the private key protected with a password ("apache2.sec.key" as it were), but then every time you restart your webserver ''and'' every time you (re)boot your server, Apache2 would have to ask you for the passphrase. Not practical for most solutions. Let's just store the unsecured private key in a very secure fashion. We can store the two files (key and certificate) in what is considere the default SSL location (''/etc/ssl/'', in subdirectories ''certs'' and ''private'') but for Apache2 it seems to be common to store the key and certificate in directory ''/etc/apache2/ssl''. Make absolutely sure that the key file is owned by ''root:root'' and ''chmod''ded to 400; and for neatness you might want to make it so that the certificate is owned by ''www-data:www-data'' and ''chmod''ded to 444. Thus: host:/etc/apache2/ssl# ls -l total 12 -r--r--r-- 1 www-data www-data 4624 2009-01-18 21:56 apache2.pem -r-------- 1 root root 1675 2009-01-18 21:57 apache2.unsec.key Next up, we can enable SSL for Apache2. There's a helper script under Debian to make it easy for you: a2enmod ssl Most howto's then tell you how you need to change ''/etc/apache2/ports.conf'' to include port 443, but with Debian 4.0 "Lenny" that's not necessary, since that file contains a section like this: <IfModule mod_ssl.c> # SSL name based virtual hosts are not yet supported, therefore no # NameVirtualHost statement here Listen 443 </IfModule> So now we're left to enable SSL with the right parameters for the main protected website itself. f2a9561770d03ec3ec0567f91597e88eddcf392d 2209 2160 2009-01-25T09:42:39Z Saruman! 2 small edits on ssl certs wikitext text/x-wiki ==Apache2 and SSL== ===The problem with SSL and Virtual Hosting=== To enable SSL for Apache2, you must first realise some important limitations. This section is meant to outline these limitations. First off: let's look at simple HTTP traffic, something that has nothing to do with SSL - but bear with me. One Apache instance can run multiple websites on one server (one IP address), as so-called virtual hosts. First off, let's assume we have one single server, serving two websites. These can be found using two different DNS names, e.g. www.saruman.biz and www.iceditch.nl. Now suppose a visitor wants to visit one of these sites. The visitor types in a URI pertaining to any one of the websites (containing the DNS name www.saruman.biz or www.iceditch.nl). In both cases he gets the same IP number (212.238.151.172), so his browser sends the HTTP request there, on port 80. Apache receives the request, looks in it, notices the actual URI in it (say: http://www.iceditch.nl/index.htm or http://www.saruman.biz/wiki/index.php/Main_Page), and directs the request to the right website, the right virtual host. So far, no problem at all. Now consider what happens if we introduce SSL: any request to the HTTPS-port of the server (port 443) gets encrypted using the public SSL-certificate of the server. However, before using it, this certificate is investigated by the browser of the visitor - one of the (sets of) things that must match, is the common name of the certificate (which must match the DNS-name of the website the visitor is visiting). Thus, a visitor for https://www.saruman.biz expects the SSL certificate to be in the name of www.saruman.biz, and so does his browser. But a visitor for https://www.iceditch.nl expects the certificate to be in the name of www.iceditch.nl. Reasonable, eh? But wait - the single Apache2 webserver can have multiple websites, but only ''one'' SSL certificate! And that'll be presented to the visitor at the setup of the HTTPS session, ''before'' Apache gets to hear which virtual host the visitor wants to visit. This means that when multiple virtual hosts on a single Apache2 webserver are "put on SSL", they all share the same SSL certificate. And this means that if we have an SSL certificate for www.saruman.biz, that visitors to the HTTPS-version of www.saruman.biz will be presented the "right" SSL certificate, but visitors to the HTTPS-version of www.iceditch.nl will get a certificate for www.saruman.biz as well - leading to nagging warnings in the browser of each one of your visitors. In effect, you can run only ''one'' virtual host, that's accessible over HTTPS, and gets no raised eyebrows on the certificate name issue. SO! Is this a totally unavoidable problem? For most situations: yes. But in some cases there are workarounds. ===A solution for the problem of SSL Certificate names and Virtual Hosting=== One workaround would be to have two IP numbers for your server, and have two instances of Apache2 listen on port 443: one instance on the IP of www.saruman.biz, and hosting virtual site www.saruman.biz, and using an SSL certificate for www.saruman.biz. The other instance could then listen on the IP number for www.iceditch.nl and use an SSL certificate signed correspondingly. Simple, effective - but requiring multiple IP numbers, and sort of defeating the reason for having virtual hosting in the first place. We hesitate to call this a true "workaround". Another workaround would be to have multiple Apache2 instances listen on the ''same'' IP number, but on ''different'' ports: only one could sit behind the port that's default for HTTPS (443); any other site would have to sit behind another port (e.g. 444). This however would force users to type the port in with the URI. In our example: if www.saruman.biz sits behind 443, then www.iceditch.nl could have an SSL protected site behind port 444, but visitors would have to use the URI ''https://www.iceditch.nl:444/index.htm''. Not the handiest or prettiest solution either. A much better workaround, unfortunately of limited applicability, is to have all virtual hosts be hosted on URI's that are based on the same toplevel domain, e.g. www.saruman.biz, shop.saruman.biz, webmail.saruman.biz etcetera. When multiple virtual hosts share a common DNS domain, then the (single) SSL certificate for these (multiple) virtual hosts could be based on a wildcard SSL certificate name - in this case *.saruman.biz. The certificate would match all those virtual hosts. Alas, it still wouldn't match www.iceditch.nl... If you cannot implement either one of these two "solutions", then you're stuck with this: you can have ''one'' website behind SSL encryption with a matching SSL certificate; any other website that your Apache webserver is serving will have to do without SSL, or with a nasty error message for every visitor, every time they visit the site. ==SSL for your main protected website== OK, let's assume you cannot employ either of the two offered "workarounds", or don't need multiple SSL sites to begin with. We can now determine which one of our virtual hosts (assuming you have multiple) we want to provide SSL for. We'll say that the website that this virtual host is serving is the main protected website. With www.saruman.biz as our example, let's implement SSL. ===getting the SSL keys=== We can start by obtaining the necessary SSL certificates. We determine that the site is located at URI www.saruman.biz, and request an SSL certificate for www.saruman.biz (or for *.saruman.biz) from a trusted Certificate Authority (CA) such as Thawte. Optionally, we generate our own SSL certificate, as has been described in the [[Certificate_fundamentals | certificate section]]. Note that we need the private key to be without passphrase. Sidenotes: if you need to remove the passphrase from your private key, follow the instructions in the section [[Creating_digital_certificates_with_our_root_certificate#CA.sh_-_certificate_creation_made_easy | creating digital certificates with our root certificate]]. Optionally, you ''could'' leave the private key protected with a password ("apache2.sec.key" as it were), but then every time you restart your webserver ''and'' every time you (re)boot your server, Apache2 would have to ask you for the passphrase. Not practical for most solutions. Let's just agree to store the unsecured private key in a very secure fashion. Let's suppose we have the certificates, and we have (re)named them "apache2.pem" and "apache2.unsec.key". We can store the two files (key and certificate) in what is considered the default SSL location (''/etc/ssl/'', in subdirectories ''certs'' and ''private''); however for Apache2 it seems to be common to store the key and certificate in directory ''/etc/apache2/ssl''. It is not really important what you choose, as long as you protect the unprotected key. In this example, we'll store the key and certificate in ''/etc/apache2/ssl''. Make absolutely sure that the key file is owned by ''root:root'' and ''chmod''ded to 400; and for neatness you might want to make it so that the certificate is owned by ''www-data:www-data'' and ''chmod''ded to 444. Thus: host:/etc/apache2/ssl# ls -l total 12 -r--r--r-- 1 www-data www-data 4624 2009-01-18 21:56 apache2.pem -r-------- 1 root root 1675 2009-01-18 21:57 apache2.unsec.key ===Prepare Apache for SSL=== Next up, we can enable SSL for Apache2. There's a helper script under Debian to make it easy for you: a2enmod ssl Most howto's then tell you how you need to change ''/etc/apache2/ports.conf'' to include port 443, but with Debian 4.0 "Lenny" that's not necessary, since that file contains a section like this: <IfModule mod_ssl.c> # SSL name based virtual hosts are not yet supported, therefore no # NameVirtualHost statement here Listen 443 </IfModule> So now we're left to enable SSL with the right parameters for the main protected website itself. ===Enable SSL for your websites=== b1bae8bff67e76e746cc521e3c63bed0f4424d79 0 1510 2157 2009-01-18T15:35:58Z Saruman! 2 Added password reset extension instructions wikitext text/x-wiki ==Mediawiki Extension: Password Reset== Sometimes you as a Mediawiki administrator might feel the need to reset a user's password manually. Unfortunately, there is no such function in the MediaWiki software. [http://www.imdb.com/title/tt0096928/ Bogus!] But fortunately, there now exists an extension that adds this functionality. [http://www.imdb.com/title/tt0096928/ Most excellent!] ==Adding the extension== First, download the five files that make up the Password Reset extension from here: [http://www.mediawiki.org/wiki/Extension:Password_Reset Mediawiki Extension:Password Reset]. These five files are to be placed in the extension directory of your Debian MediaWiki installation, presumably '' /usr/share/mediawiki-extensions''. Make sure these five files are owned by root, and cannot be edited by anyone else. As root: cd /usr/share/mediawiki-extensions chown root:root PasswordReset* chmod 644 PasswordReset* Next, mark the extension available to MediaWiki: cd /etc/mediawiki-extensions/extensions-available ln -s /usr/share/mediawiki-extensions/PasswordReset.php Then, enable the extension (either by using the ''mwenext'' command, or by this): cd /etc/mediawiki-extensions/extensions-enabled ln -s ../extensions-available/PasswordReset.php Finally, grant the permission to use this extension to some group (presumably a very ''limited'' group!!). To this end, add something like the following to the file ''/etc/mediawiki/LocalSettings.php'': #Account management # PasswordReset extension adds the following capability $wgGroupPermissions['bureaucrat']['passwordreset'] = true; This adds the Password Reset capability to the Mediawiki administrator group "bureaucrat", of which WikiAdmin is a member - and presumably you too. ==Using the extension== To reset a user's password, you need the following: * your MediaWiki user account needs to be in a MediaWiki group that has been granted the right to use PasswordReset, e.g. ''bureaucrat'' as depicted above * you must be logged in with that MediaWiki account * you need to know the exact name of the MediaWiki account for which to reset the password In the left navigation area, click on ''Special pages''; scroll down to the section ''Restricted special pages'', you should see an entry ''Password reset''. Click it to enter the Password Reset special page. The interface is very simple: Username, New password, Confirm new password, and a button "Reset password". What more do you need? bbd9e3618a84ce7a90efef1b77fc029bed5b85e2 0 1513 2175 2009-01-20T22:11:20Z Saruman! 2 Page started wikitext text/x-wiki ==Mediawiki Extension: Group Permissions Manager== Sometimes you as a Mediawiki administrator might feel the need to add or remove a group, or edit a groups rights. Unfortunately, there is no such function in the MediaWiki software itself, you'd have to edit the ''LocalSettings.php'' file somehow. [http://www.imdb.com/title/tt0096928/ Bogus!] But fortunately, there now exists an extension that adds this functionality. [http://www.imdb.com/title/tt0096928/ Most excellent!] ==Adding the extension== First, download the three files that make up the GroupPermissionsManager extension from here: [http://www.mediawiki.org/wiki/Extension:GroupPermissionsManager Mediawiki Extension:Group Permissions Manager]. The files are named * GPManager.php * GPManager_body.php * GPManager.i18n.php These three files are to be placed in a subdirectory ''GPManager'' of the extension directory of your Debian MediaWiki installation, presumably ''/usr/share/mediawiki-extensions''. As of the writing of this page, the files are not offered as downloads, you'll have to open an editor and cut & paste the texts. If you do this as root, the files will automatically have the right owner and permissions, but else, you'll have to make sure these three files are owned by root, and cannot be edited by anyone else. As root: cd /usr/share/mediawiki-extensions chown root:root GPManager cd GPManager chown root:root GPManager* chmod 644 GPManager* Next, we have to make a small alteration to ''/usr/share/mediawiki/includes/GlobalFunctions.php'' because there's a bug in MediaWiki 1.12, and that's the version that Lenny uses. The alteration is described in [http://www.mediawiki.org/wiki/Extension:GroupPermissionsManager#Patch a patch prescription on the MediaWiki site], but in essence we add a line after line number 422: the line beginning with "wfRunHooks": function wfMsgGetKey( $key, $useDB, $forContent = false, $transform = true ) { global $wgParser, $wgContLang, $wgMessageCache, $wgLang; wfRunHooks( 'NormalizeMessageKey', array( &$key, &$useDB, &$langCode, &$transform ) ); Next, we mark the extension available to MediaWiki: cd /etc/mediawiki-extensions/extensions-available ln -s /usr/share/mediawiki-extensions/GPManager/GPManager.php Then, enable the extension (either by using the ''mwenext'' command, or by this): cd /etc/mediawiki-extensions/extensions-enabled ln -s ../extensions-available/GPManager.php Finally, we create a directory @@@ grant the permission to @@@ This adds the @@ capability to the Mediawiki administrator group "bureaucrat", of which WikiAdmin is a member - and presumably you too. ==Using the extension== To manage group permissions, you need the following: * your MediaWiki user account needs to be in a MediaWiki group that has been granted the right to use PasswordReset, e.g. ''bureaucrat'' as depicted above * you must be logged in with that MediaWiki account * you need to know d In the left navigation area, click on ''Special pages''; scroll down to the section ''Restricted special pages'', you should see an entry ''@@''. Click it to enter the @@ special page. @@@ e825709789a06e07cb4fd4e25e92e88990e1c020 2176 2175 2009-01-21T17:27:57Z Saruman! 2 tested OK wikitext text/x-wiki ==Mediawiki Extension: Group Permissions Manager== Sometimes you as a Mediawiki administrator might feel the need to add or remove a group, or edit a groups rights. Unfortunately, there is no such function in the MediaWiki software itself, you'd have to edit the ''LocalSettings.php'' file somehow. [http://www.imdb.com/title/tt0096928/ Bogus!] But fortunately, there now exists an extension that adds this functionality. [http://www.imdb.com/title/tt0096928/ Most excellent!] ==Adding the extension== First, download the three files that make up the GroupPermissionsManager extension from here: [http://www.mediawiki.org/wiki/Extension:GroupPermissionsManager Mediawiki Extension:Group Permissions Manager]. The files are named * GPManager.php * GPManager_body.php * GPManager.i18n.php Contrary to the instructions on the extension's homepage, these three files are to be placed in the extension directory of your Debian MediaWiki installation, presumably ''/usr/share/mediawiki-extensions'' (so definately NOT in a subdirectory like ''GPManage''). As of the writing of this page, the files are not offered as downloads, you'll have to open an editor and cut & paste the texts. If you do this as root, the files will automatically have the right owner and permissions, but else, you'll have to make sure these three files are owned by root, and cannot be edited by anyone else. As root: cd /usr/share/mediawiki-extensions chown root:root GPManager* chmod 644 GPManager* Next, we have to make a small alteration to ''/usr/share/mediawiki/includes/GlobalFunctions.php'' because there's a bug in MediaWiki 1.12, and that's the version that Lenny uses. The alteration is described in [http://www.mediawiki.org/wiki/Extension:GroupPermissionsManager#Patch a patch prescription on the MediaWiki site], but in essence we add a line after line number 422: the line beginning with "wfRunHooks": function wfMsgGetKey( $key, $useDB, $forContent = false, $transform = true ) { global $wgParser, $wgContLang, $wgMessageCache, $wgLang; wfRunHooks( 'NormalizeMessageKey', array( &$key, &$useDB, &$langCode, &$transform ) ); Next, we create a directory where Group Permissions Manager will keep the configuration files. In the Debian style, we need something under ''/etc'' so we suggest creating ''/etc/mediawiki/config''. After that, grant the permission to write in this directory to the web server daemon, for Apache2 ''www-data''. Finally, create a symlink to this config directory in the place where GPManager actually ''expects'' it, namely in the directory where the PHP-script itself resides (here: ''/usr/share/mediawiki-extensions/''). All of this can be achieved by following these steps: cd /etc/mediawiki mkdir config chown www-data:www-data config cd /usr/share/mediawiki-extensions ln -s /etc/mediawiki/config Now we can mark the extension available to MediaWiki: cd /etc/mediawiki-extensions/extensions-available ln -s /usr/share/mediawiki-extensions/GPManager.php Then, enable the extension mwenext GPManager.php (Alternatively, you could just use this:) cd /etc/mediawiki-extensions/extensions-enabled ln -s ../extensions-available/GPManager.php This by default adds an extra capability to the Mediawiki administrator group "bureaucrat", of which WikiAdmin is a member - and presumably you too. The capability is to use a ''Special'' page to create, manage, and remove Wiki groups and their permissions. ==Using the extension== To manage group permissions, you need the following: * your MediaWiki user account needs to be in a MediaWiki group that has been granted the right to use Group Permissions Manager, e.g. ''bureaucrat'' as depicted above; * you must be logged in with that MediaWiki account; * you need to know the name of the group whose permissions you want to manage (or create or delete). In the left navigation area, click on ''Special pages''; scroll down to the section ''Restricted special pages'', you should see an entry ''Manage Group Permissions''. Click it to enter the Manage Group Permissions special page. Here, you'll find just an empty box and a "Go" button. Fill in the name of the group you want to create/manage/delete, and click "Go". You'll find yourself in a long page with group permissions, each of which can be "true", "false" or "inherit". Setting a permission to "true" or "false" enables or disables the permission for this group, while leaving it on "inherit" means the group gets the default permission that MediaWiki assigns every group - just think of the default rights of the default group "users" Furthermore: * If the group pre-exists, you'll find above the list a comment box and a "Delete group" button, where you can remove the group, while leaving the comment in the ''GroupPermissionsLog.log'' log file. * Furthermore, if the group pre-exists, the permissions list ends with a comment box and a "Change group permissions" button. Clicking that button will change the group permissions to the set designated in the permissions list. The changes, along with all other group permissions, can be found in the ''/etc/mediawiki/config'' directory in file ''GroupPermissons.php''. Clicking the button will also have resulted in a backup of the ''GroupPermissons.php'' file in that same directory, but named ''GroupPermissons.<timestamp>.php'', e.g. ''GroupPermissions.21012009171713.php''. * If the group name is "new", no "Delete group" button is shown, but the permissions list ends with a comment box and an "Add group" button, which will create the group with the designated name, while leaving the comment in the ''GroupPermissionsLog.log'' log file. Again, the comment is logged, and a backup of the ''GroupPermissons.php'' file is made. 01e9ffae6f492324c28a987771b5b8418316a551 2204 2176 2009-01-22T19:39:45Z Saruman! 2 [[MediaWikiExtension GroupPermissionsManager]] moved to [[MediaWikiExtension GroupPermissionsManager2.00]]: Old extension replaced by new one wikitext text/x-wiki ==Mediawiki Extension: Group Permissions Manager== Sometimes you as a Mediawiki administrator might feel the need to add or remove a group, or edit a groups rights. Unfortunately, there is no such function in the MediaWiki software itself, you'd have to edit the ''LocalSettings.php'' file somehow. [http://www.imdb.com/title/tt0096928/ Bogus!] But fortunately, there now exists an extension that adds this functionality. [http://www.imdb.com/title/tt0096928/ Most excellent!] ==Adding the extension== First, download the three files that make up the GroupPermissionsManager extension from here: [http://www.mediawiki.org/wiki/Extension:GroupPermissionsManager Mediawiki Extension:Group Permissions Manager]. The files are named * GPManager.php * GPManager_body.php * GPManager.i18n.php Contrary to the instructions on the extension's homepage, these three files are to be placed in the extension directory of your Debian MediaWiki installation, presumably ''/usr/share/mediawiki-extensions'' (so definately NOT in a subdirectory like ''GPManage''). As of the writing of this page, the files are not offered as downloads, you'll have to open an editor and cut & paste the texts. If you do this as root, the files will automatically have the right owner and permissions, but else, you'll have to make sure these three files are owned by root, and cannot be edited by anyone else. As root: cd /usr/share/mediawiki-extensions chown root:root GPManager* chmod 644 GPManager* Next, we have to make a small alteration to ''/usr/share/mediawiki/includes/GlobalFunctions.php'' because there's a bug in MediaWiki 1.12, and that's the version that Lenny uses. The alteration is described in [http://www.mediawiki.org/wiki/Extension:GroupPermissionsManager#Patch a patch prescription on the MediaWiki site], but in essence we add a line after line number 422: the line beginning with "wfRunHooks": function wfMsgGetKey( $key, $useDB, $forContent = false, $transform = true ) { global $wgParser, $wgContLang, $wgMessageCache, $wgLang; wfRunHooks( 'NormalizeMessageKey', array( &$key, &$useDB, &$langCode, &$transform ) ); Next, we create a directory where Group Permissions Manager will keep the configuration files. In the Debian style, we need something under ''/etc'' so we suggest creating ''/etc/mediawiki/config''. After that, grant the permission to write in this directory to the web server daemon, for Apache2 ''www-data''. Finally, create a symlink to this config directory in the place where GPManager actually ''expects'' it, namely in the directory where the PHP-script itself resides (here: ''/usr/share/mediawiki-extensions/''). All of this can be achieved by following these steps: cd /etc/mediawiki mkdir config chown www-data:www-data config cd /usr/share/mediawiki-extensions ln -s /etc/mediawiki/config Now we can mark the extension available to MediaWiki: cd /etc/mediawiki-extensions/extensions-available ln -s /usr/share/mediawiki-extensions/GPManager.php Then, enable the extension mwenext GPManager.php (Alternatively, you could just use this:) cd /etc/mediawiki-extensions/extensions-enabled ln -s ../extensions-available/GPManager.php This by default adds an extra capability to the Mediawiki administrator group "bureaucrat", of which WikiAdmin is a member - and presumably you too. The capability is to use a ''Special'' page to create, manage, and remove Wiki groups and their permissions. ==Using the extension== To manage group permissions, you need the following: * your MediaWiki user account needs to be in a MediaWiki group that has been granted the right to use Group Permissions Manager, e.g. ''bureaucrat'' as depicted above; * you must be logged in with that MediaWiki account; * you need to know the name of the group whose permissions you want to manage (or create or delete). In the left navigation area, click on ''Special pages''; scroll down to the section ''Restricted special pages'', you should see an entry ''Manage Group Permissions''. Click it to enter the Manage Group Permissions special page. Here, you'll find just an empty box and a "Go" button. Fill in the name of the group you want to create/manage/delete, and click "Go". You'll find yourself in a long page with group permissions, each of which can be "true", "false" or "inherit". Setting a permission to "true" or "false" enables or disables the permission for this group, while leaving it on "inherit" means the group gets the default permission that MediaWiki assigns every group - just think of the default rights of the default group "users" Furthermore: * If the group pre-exists, you'll find above the list a comment box and a "Delete group" button, where you can remove the group, while leaving the comment in the ''GroupPermissionsLog.log'' log file. * Furthermore, if the group pre-exists, the permissions list ends with a comment box and a "Change group permissions" button. Clicking that button will change the group permissions to the set designated in the permissions list. The changes, along with all other group permissions, can be found in the ''/etc/mediawiki/config'' directory in file ''GroupPermissons.php''. Clicking the button will also have resulted in a backup of the ''GroupPermissons.php'' file in that same directory, but named ''GroupPermissons.<timestamp>.php'', e.g. ''GroupPermissions.21012009171713.php''. * If the group name is "new", no "Delete group" button is shown, but the permissions list ends with a comment box and an "Add group" button, which will create the group with the designated name, while leaving the comment in the ''GroupPermissionsLog.log'' log file. Again, the comment is logged, and a backup of the ''GroupPermissons.php'' file is made. 01e9ffae6f492324c28a987771b5b8418316a551 14 1515 2179 2009-01-21T20:34:47Z Saruman! 2 Dimensions introduced wikitext text/x-wiki ==Dimensions== The dimensions are an important aspect of the DYA|Infrastructure [[Building Block meta-model]]. The dimensions via which the infrastructure landscape can be inventoried, organized and described, have been chosen for their practical applicability. (Currently) no scientific model lies beneath the choices made for these dimensions, but extensive testing in practice confirms that the current dimensions have the right amount of independence and granularity. ca8c05e05b1cad88052dadcc401698b756ed8374 0 1532 2205 2009-01-22T19:39:45Z Saruman! 2 [[MediaWikiExtension GroupPermissionsManager]] moved to [[MediaWikiExtension GroupPermissionsManager2.00]]: Old extension replaced by new one wikitext text/x-wiki #REDIRECT [[MediaWikiExtension GroupPermissionsManager2.00]] d3440a1e80d65e917992bfe667dbad794cd99ea7 2206 2205 2009-01-22T20:26:58Z Saruman! 2 started conversion from 2.00 to 3.6.2 instructions. wikitext text/x-wiki ==Mediawiki Extension: Group Permissions Manager== Sometimes you as a Mediawiki administrator might feel the need to add or remove a group, or edit a groups rights. Unfortunately, there is no such function in the MediaWiki software itself, you'd have to edit the ''LocalSettings.php'' file somehow. [http://www.imdb.com/title/tt0096928/ Bogus!] But fortunately, there now exists an extension that adds this functionality. [http://www.imdb.com/title/tt0096928/ Most excellent!] Note: if you want to install the older version 2.00 of this plugin (which is much simpler, both in installation and in functionality), then go to the [[MediaWikiExtension GroupPermissionsManager2.00| Group Permissions Manager 2.00]] page. The instructions on this page are for the 3.2.6 version (build r45886). ==Adding the extension== First, download the latest snapshot of the GroupPermissionsManager extension from here: [http://www.mediawiki.org/wiki/Extension:GroupPermissionsManager Mediawiki Extension:Group Permissions Manager]. It's a single archive with a name that looks like ''GroupPermissionsManager-trunk-r45886.tar.gz''. You'll best extract it in some temporary place (e.g. ''/tmp''); out comes a little directory structure like this: GroupPermissionsManager |-- plugins | |-- disabled | `-- messages `-- scripts You'll have to make sure all files and directories are owned by root, and that the PHP files cannot be edited by anyone else than root. As root: cd /tmp/GroupPermissionsManager chown -R root:root * chmod -R 644 *.php Next, contrary to the instructions on the extension's homepage, all files and directories under the ''GroupPermissionsManager'' directory are to be placed directly in the extension directory of your Debian MediaWiki installation, presumably ''/usr/share/mediawiki-extensions''. This is because the Debian way of managing MediaWiki extension is non-standard. We can do this with the following commands: cd /tmp/GroupPermissionsManager mv * /usr/share/mediawiki-extensions Next, we have to make a small alteration to ''/usr/share/mediawiki/includes/GlobalFunctions.php'' because there's a bug or shortcoming in MediaWiki 1.12, and that's the version that Lenny uses. The alteration is described in [http://www.mediawiki.org/wiki/Extension:GroupPermissionsManager#Patch a patch prescription on the MediaWiki site], but in essence we add a line after line number 422: the line beginning with "wfRunHooks": function wfMsgGetKey( $key, $useDB, $forContent = false, $transform = true ) { global $wgParser, $wgContLang, $wgMessageCache, $wgLang; wfRunHooks( 'NormalizeMessageKey', array( &$key, &$useDB, &$langCode, &$transform ) ); Next, we create a directory where Group Permissions Manager will keep the configuration files. In the Debian style, we need something under ''/etc'' so we suggest creating ''/etc/mediawiki/config''. After that, grant the permission to write in this directory to the web server daemon, for Apache2 ''www-data''.<br> Finally, create a symlink to this config directory in the place where GroupPermissionsManager actually ''expects'' it, namely in the directory where the PHP-script itself resides (here: ''/usr/share/mediawiki-extensions/''). All of this can be achieved by following these steps: cd /etc/mediawiki mkdir config chown www-data:www-data config cd /usr/share/mediawiki-extensions ln -s /etc/mediawiki/config Now we can mark the extension available to MediaWiki: cd /etc/mediawiki-extensions/extensions-available ln -s ln -s /usr/share/mediawiki-extensions/GroupPermissionsManager.php Then, enable the extension mwenext GroupPermissionsManager.php This by default adds an extra capability to the Mediawiki administrator group "bureaucrat", of which WikiAdmin is a member - and presumably you too. The capability is to use a ''Special'' page to create, manage, and remove Wiki groups and their permissions. ==Using the extension== To manage group permissions, you need the following: * your MediaWiki user account needs to be in a MediaWiki group that has been granted the right to use Group Permissions Manager, e.g. ''bureaucrat'' as depicted above; * you must be logged in with that MediaWiki account; * you need to know the name of the group whose permissions you want to manage (or create or delete). In the left navigation area, click on ''Special pages''; scroll down to the section ''Restricted special pages'', you should see an entry ''Manage Group Permissions''. Click it to enter the Manage Group Permissions special page. Here, you'll find just an empty box and a "Go" button. Fill in the name of the group you want to create/manage/delete, and click "Go". You'll find yourself in a long page with group permissions, each of which can be "true", "false" or "inherit". Setting a permission to "true" or "false" enables or disables the permission for this group, while leaving it on "inherit" means the group gets the default permission that MediaWiki assigns every group - just think of the default rights of the default group "users" Furthermore: * If the group pre-exists, you'll find above the list a comment box and a "Delete group" button, where you can remove the group, while leaving the comment in the ''GroupPermissionsLog.log'' log file. * Furthermore, if the group pre-exists, the permissions list ends with a comment box and a "Change group permissions" button. Clicking that button will change the group permissions to the set designated in the permissions list. The changes, along with all other group permissions, can be found in the ''/etc/mediawiki/config'' directory in file ''GroupPermissons.php''. Clicking the button will also have resulted in a backup of the ''GroupPermissons.php'' file in that same directory, but named ''GroupPermissons.<timestamp>.php'', e.g. ''GroupPermissions.21012009171713.php''. * If the group name is "new", no "Delete group" button is shown, but the permissions list ends with a comment box and an "Add group" button, which will create the group with the designated name, while leaving the comment in the ''GroupPermissionsLog.log'' log file. Again, the comment is logged, and a backup of the ''GroupPermissons.php'' file is made. 4b9d2ea31b77cdf321ee044c0c5b5ba7e5687c62 2207 2206 2009-01-22T20:39:23Z Saruman! 2 finialised installation instructions wikitext text/x-wiki ==Mediawiki Extension: Group Permissions Manager== Sometimes you as a Mediawiki administrator might feel the need to add or remove a group, or edit a groups rights. Unfortunately, there is no such function in the MediaWiki software itself, you'd have to edit the ''LocalSettings.php'' file somehow. [http://www.imdb.com/title/tt0096928/ Bogus!] But fortunately, there now exists an extension that adds this functionality. [http://www.imdb.com/title/tt0096928/ Most excellent!] Note: if you want to install the older version 2.00 of this plugin (which is much simpler, both in installation and in functionality), then go to the [[MediaWikiExtension GroupPermissionsManager2.00| Group Permissions Manager 2.00]] page. The instructions on this page are for the 3.2.6 version (build r45886). ==Adding the extension== First, download the latest snapshot of the GroupPermissionsManager extension from here: [http://www.mediawiki.org/wiki/Extension:GroupPermissionsManager Mediawiki Extension:Group Permissions Manager]. It's a single archive with a name that looks like ''GroupPermissionsManager-trunk-r45886.tar.gz''. You'll best extract it in some temporary place (e.g. ''/tmp''); out comes a little directory structure like this: GroupPermissionsManager |-- plugins | |-- disabled | `-- messages `-- scripts You'll have to make sure all files and directories are owned by root, and that the PHP files cannot be edited by anyone else than root. As root: cd /tmp/GroupPermissionsManager chown -R root:root * chmod -R 644 *.php Next, contrary to the instructions on the extension's homepage, all files and directories under the ''GroupPermissionsManager'' directory are to be placed directly in the extension directory of your Debian MediaWiki installation, presumably ''/usr/share/mediawiki-extensions''. This is because the Debian way of managing MediaWiki extension is non-standard. We can do this with the following commands: cd /tmp/GroupPermissionsManager mv * /usr/share/mediawiki-extensions Next, we have to make a small alteration to ''/usr/share/mediawiki/includes/GlobalFunctions.php'' because there's a bug or shortcoming in MediaWiki 1.12, and that's the version that Lenny uses. The alteration is described in [http://www.mediawiki.org/wiki/Extension:GroupPermissionsManager#Patch a patch prescription on the MediaWiki site], but in essence we add a line after line number 422: the line beginning with "wfRunHooks": function wfMsgGetKey( $key, $useDB, $forContent = false, $transform = true ) { global $wgParser, $wgContLang, $wgMessageCache, $wgLang; wfRunHooks( 'NormalizeMessageKey', array( &$key, &$useDB, &$langCode, &$transform ) ); Next, we create a directory where Group Permissions Manager will keep the configuration files. In the Debian style, we need something under ''/etc'' so we suggest creating ''/etc/mediawiki/config''. After that, grant the permission to write in this directory to the web server daemon, for Apache2 ''www-data''.<br> Finally, create a symlink to this config directory in the place where GroupPermissionsManager actually ''expects'' it, namely in the directory where the PHP-script itself resides (here: ''/usr/share/mediawiki-extensions/''). All of this can be achieved by following these steps: cd /etc/mediawiki mkdir config chown www-data:www-data config cd /usr/share/mediawiki-extensions ln -s /etc/mediawiki/config Now we can mark the extension ''GroupPermissionsManager.php'' available to MediaWiki: cd /etc/mediawiki-extensions/extensions-available ln -s /usr/share/mediawiki-extensions/GroupPermissionsManager.php Then, enable the extension mwenext GroupPermissionsManager.php This by default adds some extra capabilities to the Mediawiki administrator group "bureaucrat", of which WikiAdmin is a member - and presumably you too. The capabilities are to use a ''Special'' page to create, manage, and remove Wiki groups and their permissions. ==Using the extension== To manage group permissions, you need the following: * your MediaWiki user account needs to be in a MediaWiki group that has been granted the right to use Group Permissions Manager, e.g. ''bureaucrat'' as depicted above; * you must be logged in with that MediaWiki account; * you need to know the name of the group whose permissions you want to manage (or create or delete). In the left navigation area, click on ''Special pages''; scroll down to the section ''Restricted special pages'', you should see an entry ''Manage Group Permissions''. Click it to enter the Manage Group Permissions special page. Here, you'll find just an empty box and a "Go" button. Fill in the name of the group you want to create/manage/delete, and click "Go". You'll find yourself in a long page with group permissions, each of which can be "true", "false" or "inherit". Setting a permission to "true" or "false" enables or disables the permission for this group, while leaving it on "inherit" means the group gets the default permission that MediaWiki assigns every group - just think of the default rights of the default group "users" Furthermore: * If the group pre-exists, you'll find above the list a comment box and a "Delete group" button, where you can remove the group, while leaving the comment in the ''GroupPermissionsLog.log'' log file. * Furthermore, if the group pre-exists, the permissions list ends with a comment box and a "Change group permissions" button. Clicking that button will change the group permissions to the set designated in the permissions list. The changes, along with all other group permissions, can be found in the ''/etc/mediawiki/config'' directory in file ''GroupPermissons.php''. Clicking the button will also have resulted in a backup of the ''GroupPermissons.php'' file in that same directory, but named ''GroupPermissons.<timestamp>.php'', e.g. ''GroupPermissions.21012009171713.php''. * If the group name is "new", no "Delete group" button is shown, but the permissions list ends with a comment box and an "Add group" button, which will create the group with the designated name, while leaving the comment in the ''GroupPermissionsLog.log'' log file. Again, the comment is logged, and a backup of the ''GroupPermissons.php'' file is made. e2927ada15b5e7ed0d95d33d10f1660877025d0e 0 1508 2210 2209 2009-01-25T10:36:18Z Saruman! 2 SSLpassphrasedialogue added wikitext text/x-wiki ==Apache2 and SSL== ===The problem with SSL and Virtual Hosting=== To enable SSL for Apache2, you must first realize some important limitations. This section is meant to outline these limitations. First off: let's look at simple HTTP traffic, something that has nothing to do with SSL - but bear with me. One Apache instance can run multiple websites on one server (one IP address), as so-called virtual hosts. First off, let's assume we have one single server, serving two websites. These can be found using two different DNS names, e.g. www.saruman.biz and www.iceditch.nl. Now suppose a visitor wants to visit one of these sites. The visitor types in a URI pertaining to any one of the websites (containing the DNS name www.saruman.biz or www.iceditch.nl). In both cases he gets the same IP number (212.238.151.172), so his browser sends the HTTP request there, on port 80. Apache receives the request, looks in it, notices the actual URI in it (say: http://www.iceditch.nl/index.htm or http://www.saruman.biz/wiki/index.php/Main_Page), and directs the request to the right website, the right virtual host. So far, no problem at all. Now consider what happens if we introduce SSL: any request to the HTTPS-port of the server (port 443) gets encrypted using the public SSL-certificate of the server. However, before using it, this certificate is investigated by the browser of the visitor - one of the (sets of) things that must match, is the common name of the certificate (which must match the DNS-name of the website the visitor is visiting). Thus, a visitor for https://www.saruman.biz expects the SSL certificate to be in the name of www.saruman.biz, and so does his browser. But a visitor for https://www.iceditch.nl expects the certificate to be in the name of www.iceditch.nl. Reasonable, eh? But wait - the single Apache2 web server can have multiple websites, but only ''one'' SSL certificate! And that'll be presented to the visitor at the setup of the HTTPS session, ''before'' Apache gets to hear which virtual host the visitor wants to visit. This means that when multiple virtual hosts on a single Apache2 webserver are "put on SSL", they all share the same SSL certificate. And this means that if we have an SSL certificate for www.saruman.biz, that visitors to the HTTPS-version of www.saruman.biz will be presented the "right" SSL certificate, but visitors to the HTTPS-version of www.iceditch.nl will get a certificate for www.saruman.biz as well - leading to nagging warnings in the browser of each one of your visitors. In effect, you can run only ''one'' virtual host, that's accessible over HTTPS, and gets no raised eyebrows on the certificate name issue. SO! Is this a totally unavoidable problem? For most situations: yes. But in some cases there are workarounds. ===A solution for the problem of SSL Certificate names and Virtual Hosting=== One workaround would be to have two IP numbers for your server, and have two instances of Apache2 listen on port 443: one instance on the IP of www.saruman.biz, and hosting virtual site www.saruman.biz, and using an SSL certificate for www.saruman.biz. The other instance could then listen on the IP number for www.iceditch.nl and use an SSL certificate signed correspondingly. Simple, effective - but requiring multiple IP numbers, and sort of defeating the reason for having virtual hosting in the first place. We hesitate to call this a true "workaround". Another workaround would be to have multiple Apache2 instances listen on the ''same'' IP number, but on ''different'' ports: only one could sit behind the port that's default for HTTPS (443); any other site would have to sit behind another port (e.g. 444). This however would force users to type the port in with the URI. In our example: if www.saruman.biz sits behind 443, then www.iceditch.nl could have an SSL protected site behind port 444, but visitors would have to use the URI ''https://www.iceditch.nl:444/index.htm''. Not the handiest or prettiest solution either. A much better workaround, unfortunately of limited applicability, is to have all virtual hosts be hosted on URI's that are based on the same toplevel domain, e.g. www.saruman.biz, shop.saruman.biz, webmail.saruman.biz etcetera. When multiple virtual hosts share a common DNS domain, then the (single) SSL certificate for these (multiple) virtual hosts could be based on a wildcard SSL certificate name - in this case *.saruman.biz. The certificate would match all those virtual hosts. Alas, it still wouldn't match www.iceditch.nl... If you cannot implement either one of these two "solutions", then you're stuck with this: you can have ''one'' website behind SSL encryption with a matching SSL certificate; any other website that your Apache web server is serving will have to do without SSL, or with a nasty error message for every visitor, every time they visit the site. ==SSL for your main protected website== OK, let's assume you cannot employ either of the two offered "workarounds", or don't need multiple SSL sites to begin with. We can now determine which one of our virtual hosts (assuming you have multiple) we want to provide SSL for. We'll say that the website that this virtual host is serving is the main protected website. With www.saruman.biz as our example, let's implement SSL. ===getting the SSL keys=== We can start by obtaining the necessary SSL certificates. We determine that the site is located at URI www.saruman.biz, and request an SSL certificate for www.saruman.biz (or for *.saruman.biz) from a trusted Certificate Authority (CA) such as Thawte. Optionally, we generate our own SSL certificate, as has been described in the [[Certificate_fundamentals | certificate section]]. Note that we need the private key to be without passphrase, OR we need to create a script that [http://httpd.apache.org/docs/2.2/mod/mod_ssl.html#sslpassphrasedialog provides the passphrase]. This script would need to contain the following code (assuming your passphrase is ''th7sWUSAphuB''): #!/bin/sh echo "th7sWUSAphuB" The script would need to be made executable for ''www-data'', and be located somewhere "safe". If the script was named ''keypass'' and located in ''/etc/apache2'', then in the SSL section of the Apache2 configuration, we could include the statement SSLPassPhraseDialog exec:/ect/apache2/passphrase However, since we feel a bit reluctant to expose our passphrase in this manner, we've decided to go with the passphraseless approach. Sidenote 1: If you need to remove the passphrase from your private key, follow the instructions in the section [[Creating_digital_certificates_with_our_root_certificate#CA.sh_-_certificate_creation_made_easy | creating digital certificates with our root certificate]].<br> Sidenote 2: Optionally, you ''could'' leave the private key protected with a password ("apache2.sec.key" as it were) ''and'' do without the SSLPassPhraseDialog soultion. But then every time you restart your webserver ''and'' every time you (re)boot your server, Apache2 would have to ask you for the passphrase. Not practical for most solutions. Let's just agree to store the unsecured private key in a very secure fashion. Let's suppose we have the certificates, and we have (re)named them "apache2.pem" and "apache2.unsec.key". We can store the two files (key and certificate) in what is considered the default SSL location (''/etc/ssl/'', in subdirectories ''certs'' and ''private''); however for Apache2 it seems to be common to store the key and certificate in directory ''/etc/apache2/ssl''. It is not really important what you choose, as long as you protect the unprotected key. In this example, we'll store the key and certificate in ''/etc/apache2/ssl''. Make absolutely sure that the key file is owned by ''root:root'' and ''chmod''ded to 400; and for neatness you might want to make it so that the certificate is owned by ''www-data:www-data'' and ''chmod''ded to 444. Thus: host:/etc/apache2/ssl# ls -l total 12 -r--r--r-- 1 www-data www-data 4624 2009-01-18 21:56 apache2.pem -r-------- 1 root root 1675 2009-01-18 21:57 apache2.unsec.key ===Prepare Apache for SSL=== Next up, we can enable SSL for Apache2. There's a helper script under Debian to make it easy for you: a2enmod ssl This simply creates a symlink in ''/etc/apace2/mods-enabled'' to the two files ''ssl.load'' and ''ssl.conf'' in the directory ''/etc/apache2/mods-available''. And when you look in the file ''/etc/apache2/mods-available/ssl.conf'', you'll see that most default settings for your SSL website are set there. This does NOT mean that you should make additions and alterations in that file, since this is a Debian file that might be overwritten with upgrades etcetera. We'll set the SSL parameters we need for our website in its own configuration file - see further down. Most howto's then tell you how you need to change ''/etc/apache2/ports.conf'' to include port 443, but with Debian 5.0 "Lenny" that's not necessary, since that file contains a section like this: <IfModule mod_ssl.c> # SSL name based virtual hosts are not yet supported, therefore no # NameVirtualHost statement here Listen 443 </IfModule> So now we're left to enable SSL with the right parameters for the main protected website itself. ===Enable SSL for your websites=== So now we can enable SSL for our main site. Since your web server is a Debian server, every website will have its configuration defined in a separate file in ''/etc/apache2/sites-available''. 5eeb21bfaeea617e8b752e32efb6e73ce53aa909 2211 2210 2009-01-25T11:23:11Z Saruman! 2 /* getting the SSL keys */ rewrite so that certs are in /etc/ssl wikitext text/x-wiki ==Apache2 and SSL== ===The problem with SSL and Virtual Hosting=== To enable SSL for Apache2, you must first realize some important limitations. This section is meant to outline these limitations. First off: let's look at simple HTTP traffic, something that has nothing to do with SSL - but bear with me. One Apache instance can run multiple websites on one server (one IP address), as so-called virtual hosts. First off, let's assume we have one single server, serving two websites. These can be found using two different DNS names, e.g. www.saruman.biz and www.iceditch.nl. Now suppose a visitor wants to visit one of these sites. The visitor types in a URI pertaining to any one of the websites (containing the DNS name www.saruman.biz or www.iceditch.nl). In both cases he gets the same IP number (212.238.151.172), so his browser sends the HTTP request there, on port 80. Apache receives the request, looks in it, notices the actual URI in it (say: http://www.iceditch.nl/index.htm or http://www.saruman.biz/wiki/index.php/Main_Page), and directs the request to the right website, the right virtual host. So far, no problem at all. Now consider what happens if we introduce SSL: any request to the HTTPS-port of the server (port 443) gets encrypted using the public SSL-certificate of the server. However, before using it, this certificate is investigated by the browser of the visitor - one of the (sets of) things that must match, is the common name of the certificate (which must match the DNS-name of the website the visitor is visiting). Thus, a visitor for https://www.saruman.biz expects the SSL certificate to be in the name of www.saruman.biz, and so does his browser. But a visitor for https://www.iceditch.nl expects the certificate to be in the name of www.iceditch.nl. Reasonable, eh? But wait - the single Apache2 web server can have multiple websites, but only ''one'' SSL certificate! And that'll be presented to the visitor at the setup of the HTTPS session, ''before'' Apache gets to hear which virtual host the visitor wants to visit. This means that when multiple virtual hosts on a single Apache2 webserver are "put on SSL", they all share the same SSL certificate. And this means that if we have an SSL certificate for www.saruman.biz, that visitors to the HTTPS-version of www.saruman.biz will be presented the "right" SSL certificate, but visitors to the HTTPS-version of www.iceditch.nl will get a certificate for www.saruman.biz as well - leading to nagging warnings in the browser of each one of your visitors. In effect, you can run only ''one'' virtual host, that's accessible over HTTPS, and gets no raised eyebrows on the certificate name issue. SO! Is this a totally unavoidable problem? For most situations: yes. But in some cases there are workarounds. ===A solution for the problem of SSL Certificate names and Virtual Hosting=== One workaround would be to have two IP numbers for your server, and have two instances of Apache2 listen on port 443: one instance on the IP of www.saruman.biz, and hosting virtual site www.saruman.biz, and using an SSL certificate for www.saruman.biz. The other instance could then listen on the IP number for www.iceditch.nl and use an SSL certificate signed correspondingly. Simple, effective - but requiring multiple IP numbers, and sort of defeating the reason for having virtual hosting in the first place. We hesitate to call this a true "workaround". Another workaround would be to have multiple Apache2 instances listen on the ''same'' IP number, but on ''different'' ports: only one could sit behind the port that's default for HTTPS (443); any other site would have to sit behind another port (e.g. 444). This however would force users to type the port in with the URI. In our example: if www.saruman.biz sits behind 443, then www.iceditch.nl could have an SSL protected site behind port 444, but visitors would have to use the URI ''https://www.iceditch.nl:444/index.htm''. Not the handiest or prettiest solution either. A much better workaround, unfortunately of limited applicability, is to have all virtual hosts be hosted on URI's that are based on the same toplevel domain, e.g. www.saruman.biz, shop.saruman.biz, webmail.saruman.biz etcetera. When multiple virtual hosts share a common DNS domain, then the (single) SSL certificate for these (multiple) virtual hosts could be based on a wildcard SSL certificate name - in this case *.saruman.biz. The certificate would match all those virtual hosts. Alas, it still wouldn't match www.iceditch.nl... If you cannot implement either one of these two "solutions", then you're stuck with this: you can have ''one'' website behind SSL encryption with a matching SSL certificate; any other website that your Apache web server is serving will have to do without SSL, or with a nasty error message for every visitor, every time they visit the site. ==SSL for your main protected website== OK, let's assume you cannot employ either of the two offered "workarounds", or don't need multiple SSL sites to begin with. We can now determine which one of our virtual hosts (assuming you have multiple) we want to provide SSL for. We'll say that the website that this virtual host is serving is the main protected website. With www.saruman.biz as our example, let's implement SSL. ===getting the SSL keys=== We can start by obtaining the necessary SSL certificates. We determine that the site is located at URI www.saruman.biz, and request an SSL certificate for www.saruman.biz (or for *.saruman.biz) from a trusted Certificate Authority (CA) such as Thawte. Optionally, we generate our own SSL certificate, as has been described in the [[Certificate_fundamentals | certificate section]]. Note that we need the private key to be without passphrase, OR we need to create a script that [http://httpd.apache.org/docs/2.2/mod/mod_ssl.html#sslpassphrasedialog provides the passphrase]. This script would need to contain the following code (assuming your passphrase is ''th7sWUSAphuB''): #!/bin/sh echo "th7sWUSAphuB" The script would need to be made executable for ''www-data'', and be located somewhere "safe". If the script was named ''keypass'' and located in ''/etc/apache2'', then in the SSL section of the Apache2 configuration, we could include the statement SSLPassPhraseDialog exec:/ect/apache2/passphrase However, since we feel a bit reluctant to expose our passphrase in this manner, we've decided to go with the passphraseless approach. Sidenote 1: If you need to remove the passphrase from your private key, follow the instructions in the section [[Creating_digital_certificates_with_our_root_certificate#CA.sh_-_certificate_creation_made_easy | creating digital certificates with our root certificate]].<br> Sidenote 2: Optionally, you ''could'' leave the private key protected with a password ("apache2.sec.key" as it were) ''and'' do without the SSLPassPhraseDialog soultion. But then every time you restart your webserver ''and'' every time you (re)boot your server, Apache2 would have to ask you for the passphrase. Not practical for most solutions. Let's just agree to store the unsecured private key in a very secure fashion. Let's suppose we have the certificates, and we have (re)named them "apache2.pem" and "apache2.unsec.key". We can store the two files (key and certificate) in what is considered the default SSL location (''/etc/ssl/'', in subdirectories ''certs'' and ''private''); although for Apache2 it also seems to be common to store the key and certificate in directory ''/etc/apache2/ssl''. It is not really important what you choose, as long as you protect the unprotected key. In this example, we'll store the key and certificate in ''/etc/ssl''. Make absolutely sure that the key file is owned by ''root:root'' and ''chmod''ded to 400; and for neatness you might want to make it so that the certificate is owned by ''www-data:www-data'' and ''chmod''ded to 444. Thus: host:/etc/ssl# ls -l */apache* -r--r--r-- 1 www-data www-data 4624 2009-01-18 21:56 certs/apache2.pem -r-------- 1 root root 1675 2009-01-18 21:57 private/apache2.unsec.key ===Prepare Apache for SSL=== Next up, we can enable SSL for Apache2. There's a helper script under Debian to make it easy for you: a2enmod ssl This simply creates a symlink in ''/etc/apace2/mods-enabled'' to the two files ''ssl.load'' and ''ssl.conf'' in the directory ''/etc/apache2/mods-available''. And when you look in the file ''/etc/apache2/mods-available/ssl.conf'', you'll see that most default settings for your SSL website are set there. This does NOT mean that you should make additions and alterations in that file, since this is a Debian file that might be overwritten with upgrades etcetera. We'll set the SSL parameters we need for our website in its own configuration file - see further down. Most howto's then tell you how you need to change ''/etc/apache2/ports.conf'' to include port 443, but with Debian 5.0 "Lenny" that's not necessary, since that file contains a section like this: <IfModule mod_ssl.c> # SSL name based virtual hosts are not yet supported, therefore no # NameVirtualHost statement here Listen 443 </IfModule> So now we're left to enable SSL with the right parameters for the main protected website itself. ===Enable SSL for your websites=== So now we can enable SSL for our main site. Since your web server is a Debian server, every website will have its configuration defined in a separate file in ''/etc/apache2/sites-available''. cead617267d776d3e10c3b6fec22cb739c33010c 102 1534 2217 2009-01-25T16:32:05Z Saruman! 2 Page started wikitext text/x-wiki An environment prescribes [[:Category:Quality_Attribute|Quality Attributes]] to any [[:Category:Working_Area | Working Area]]. The prescription of Quality Attributes is the mechanism by which the Infrastructure Architect can account for different external influences on the products within a Working Area. c74e7131f4fd7728e4b579e6cce4a73fd00aa3be 2218 2217 2009-01-25T16:34:29Z Saruman! 2 Rewording wikitext text/x-wiki An [[:Category:Environment | Environment]] within a [[:Category:Working_Area | Working Area]] '''prescribes''' [[:Category:Quality_Attribute|Quality Attributes]] to the products that fall within that Environment. The prescription of Quality Attributes is the mechanism by which the Infrastructure Architect can account for different external influences on the products within that specific Working Area. 59f3eb934b5c8803c1ee6ed31bce3cef7f02687e 102 1535 2219 2009-01-25T16:37:07Z Saruman! 2 Page started wikitext text/x-wiki An [[:Category:Environment | Environment]] '''Resorts Under''' a [[:Category:Working_Area | Working Area]]. This is the relation that signifies the subdivision of a Working Area into separate Environments. c3fbd48fa5b911f4258428174e01a08f56966199 102 1537 2231 2009-01-26T07:41:34Z Saruman! 2 Page started wikitext text/x-wiki Environment Code is an abbreviation of the Working Area and the Environment. Usually the abbreviation consists of two capitals, a dot and two more capitals. 0e26f975f6d06af4297281206afadb1c6f01c5a0 0 1466 2237 1633 2009-01-27T17:05:12Z Saruman! 2 Added database move wikitext text/x-wiki == MySQL installation == As with any package to be installed: use aptitude, update your APT, then make sure all your (other) software is up-to-date. Then find package ''mysql-server'' - under Lenny it'll be version 5.0.51a-something. Installing it will also automatically install some dependent packages, like mysql-common, mysql-client etcetera. So after downloading some 40MiB of files, MySQL is installed. Should you consult [http://dev.mysql.com/doc/refman/5.0/en/unix-post-installation.html the official MySQL documentation], you might see mention of the ''mysql_install_db'' script - do not worry about that, since Debian has run it for you when it was setting up the database. To now configure the MySQL server, please take the following steps: Think up a strong password for the MySQL root user; something like ''waYacUbaT2uW''. DON'T use this example password, [http://www.pctools.com/guides/password/ generate your own one!]. Start the MySQL client from the command line: mysql -u root Then, from the mysql client prompt, set the password for the MySQL root user. At installation time, two accounts "root" were created, each with an empty password - NOT safe! One account is used to connect to the MySQL server from localhost, one to connect from the IP address of the machine. They can be treated as two different accounts, but we don't recommend that. We thus give both accounts the same password: mysql> SET PASSWORD FOR 'root'@'localhost' = PASSWORD('waYacUbaT2uW'); mysql> SET PASSWORD FOR 'root'@'<hostname>' = PASSWORD('waYacUbaT2uW'); Furthermore, there are two anonymous accounts created. These also have no password, and get full permission on the ''test'' database, as well as on any database who's name begins with ''test_''. These accounts can be fitted with a password (like we did for root - just use two quotes with nothing inbetween them, instead of two quotes with ''root'' inbetween), or they can be removed - which we recommend. The (single) command for this is: <pre>mysql> DROP USER '';</pre> To verify the installation you might want to take some of the following steps: * run ''mysqlshow -u root -p'', and see if that command outputs at least two databases (''information_schema'' and ''mysql''); * check out the settings of your MySQL server by running ''mysqladmin -u root -p variables'' (piping the output to ''less'' or a file, if necessary); * have a peek in ''/var/lib/mysql''; the database data files should be there; * check ''/var/log'' for two logfiles ''mysql.err'' and ''mysql.log''. ==Moving the MySQL databases== By default the location of your Debian MySQL databases is ''/var/lib/mysql/<database>''. However, sometimes you wish your databases to be in a different location. E.g. ''/data/mysql'', where ''/data'' is a mounted dedicated RAID array. Or perhaps even ''/data/mysql'' is its own array. Whatever the reason, to move ''all'' MySQL databases from ''/var/lib/mysql'' to another location, you can follow these steps: * Create the new directory, e.g. ''/data/mysql'' * Make this directory owned by user/group ''mysql'' cd /data mkdir mysql chown mysql:mysql mysql * Shut down the database server with one of the following commands: mysqladmin -u root -p shutdown invoke-rc.d mysql stop * Make a backup copy of ''/etc/mysql/my.cnf'', then edit this file. Find the section ''[mysqld]'' and change the line ''datadir = /var/lib/mysql'' to datadir = /data/mysql * As root, move (or better yet: copy) ''all'' of the content of ''/var/lib/mysql'' over to ''/data/mysql''. Make sure you don't accidentally change the ownership or permissions of the files and folders in the ''/var/lib/mysql'' folder. We expect each and every file and folder to be owned by ''mysql:mysql''. Copy command would be (as root): cp -p -r /var/lib/mysql/* /data/mysql * Check and doublecheck your ''my.cnf'' settings and your database file owners, attributes and size. After the next step, there ''may'' be no way back! * Start up your database server: invoke-rc.d mysql start * Check the working of your MySQL server: ** issue the following command to get status information (to see if MySQL is running after your start command): invoke-rc.d mysql status ** look under ''/var/log'' for the default MySQL log files ''mysql.log'' and ''mysql.err'' ** check your SysLog (standard: ''/var/log/syslog'') for MySQL error messages, since the default Debian configuration is to log MySQL errors there, rather than in the previously mentioned MySQL logfiles. e83ac13ca71f9a4e36834fb9a3dcce42b790800e 2293 2237 2009-02-01T10:52:53Z Saruman! 2 distinguished between etch and lenny wikitext text/x-wiki == MySQL installation == As with any package to be installed: use aptitude, update your APT, then make sure all your (other) software is up-to-date. Then find package ''mysql-server'' - under Debian 5.0 "Lenny" it'll be version 5.0.51a-something. Installing it will also automatically install some dependent packages, like mysql-common, mysql-client etcetera. So after downloading some 40MiB of files, MySQL is installed. The installation script under Debian Lenny asks you for a password for the MySQL root user. Think up a strong password for the MySQL root user; something like ''waYacUbaT2uW''. DON'T use this example password, [http://www.pctools.com/guides/password/ generate your own one!]. DO NOT use the password of the Linux ''root'' user. Should you consult [http://dev.mysql.com/doc/refman/5.0/en/unix-post-installation.html the official MySQL documentation], you might see mention of the ''mysql_install_db'' script - do not worry about that, since Debian has run it for you when it was setting up the database. The standard user accounts that have been created by the installation script are: * 'root'@'localhost' * 'root'@'<hostname>' * 'root'@'127.0.0.1' All three root accounts are secured with the same password, the one you specified when installing the package ''mysql-server''. ---- '''NOTE for Debian 4.0 "Etch"''' When you install MySQL under Etch, there are two root accounts with empty passwords, and two anonymous accounts. NOT safe! You'll want to rectify this in order to secure your MySQL server. Please take the following steps. Start the MySQL client from the command line: mysql -u root Then, from the mysql client prompt, set the password for the MySQL root users. They can be treated as two different accounts, but we don't recommend that. We thus give both accounts the same password: mysql> SET PASSWORD FOR 'root'@'localhost' = PASSWORD('waYacUbaT2uW'); mysql> SET PASSWORD FOR 'root'@'<hostname>' = PASSWORD('waYacUbaT2uW'); Furthermore, there are two anonymous accounts created. These also have no password, and get full permission on the ''test'' database, as well as on any database who's name begins with ''test_''. These accounts can be fitted with a password (like we did for root - just use two quotes with nothing in between them, instead of two quotes with ''root'' in between), or they can be removed - which we recommend. The (single) command for this is: <pre>mysql> DROP USER '';</pre> '''End of NOTE''' ---- To verify the installation you might want to take some of the following steps: * run ''mysqlshow -u root -p'', and see if that command outputs at least two databases (''information_schema'' and ''mysql''); * check out the settings of your MySQL server by running ''mysqladmin -u root -p variables'' (piping the output to ''less'' or a file, if necessary); * have a peek in ''/var/lib/mysql''; the database data files should be there; * check ''/var/log'' for two logfiles ''mysql.err'' and ''mysql.log''. ==Moving the MySQL databases== By default the location of your Debian MySQL databases is ''/var/lib/mysql/<database>''. However, sometimes you wish your databases to be in a different location. E.g. ''/data/mysql'', where ''/data'' is a mounted dedicated RAID array. Or perhaps even ''/data/mysql'' is its own array. Whatever the reason, to move ''all'' MySQL databases from ''/var/lib/mysql'' to another location, you can follow these steps: * Create the new directory, e.g. ''/data/mysql'' * Make this directory owned by user/group ''mysql'' cd /data mkdir mysql chown mysql:mysql mysql * Shut down the database server with one of the following commands: mysqladmin -u root -p shutdown invoke-rc.d mysql stop * Make a backup copy of ''/etc/mysql/my.cnf'', then edit this file. Find the section ''[mysqld]'' and change the line ''datadir = /var/lib/mysql'' to datadir = /data/mysql * As root, move (or better yet: copy) ''all'' of the content of ''/var/lib/mysql'' over to ''/data/mysql''. Make sure you don't accidentally change the ownership or permissions of the files and folders in the ''/var/lib/mysql'' folder. We expect each and every file and folder to be owned by ''mysql:mysql''. Copy command would be (as root): cp -p -r /var/lib/mysql/* /data/mysql * Check and doublecheck your ''my.cnf'' settings and your database file owners, attributes and size. After the next step, there ''may'' be no way back! * Start up your database server: invoke-rc.d mysql start * Check the working of your MySQL server: ** issue the following command to get status information (to see if MySQL is running after your start command): invoke-rc.d mysql status ** look under ''/var/log'' for the default MySQL log files ''mysql.log'' and ''mysql.err'' ** check your SysLog (standard: ''/var/log/syslog'') for MySQL error messages, since the default Debian configuration is to log MySQL errors there, rather than in the previously mentioned MySQL logfiles. 85da6c7ac7b7b21db2a3058e3664a11d830fae1c 102 1540 2242 2009-01-28T11:23:28Z 171.21.80.126 0 Page started wikitext text/x-wiki Working Area Code is an abbreviation of the Working Area. Usually the abbreviation consists of two capitals. 8f83b42afa5413bdabd9b5daf7908639a4a1af14 102 1543 2245 2009-01-28T15:55:34Z Saruman! 2 Page started wikitext text/x-wiki Building Block Code is an abbreviation of the Working Area and the Environment, appended with an abbreviated description of the Building Block name. Usually the abbreviation consists of two capitals, a dot, two more capitals, a dot, and the abbreviated description (two to ten letters). 9484142fb7d08f122989c97112cf941362a74977 102 1548 2255 2009-01-28T20:06:47Z Saruman! 2 type defined wikitext text/x-wiki ==End of Support date== [[:has type::Date]] This is the date after which no (extended) support is available. f12273c5490d2166603ce8b06b6411831bc0a82a 2256 2255 2009-01-28T20:07:56Z Saruman! 2 moved type declaration wikitext text/x-wiki ==End of Support date== This is the [[has type::Date]] after which no (extended) support is available. 7bd93671034fdaf50fbdaad17019f5bb4e41134e 102 1549 2257 2009-01-28T20:09:20Z Saruman! 2 Page started wikitext text/x-wiki ==General Availability date== This is the [[has type::Date]] from which the product became generally available; usually this marks the beginning of the official support period. e70481e7beb0f7224c4f540519a98bb2ada8596c 102 1550 2259 2009-01-28T20:11:21Z Saruman! 2 Page started wikitext text/x-wiki ==Extended Support date== This is the [[has type::Date]] after which no "standard" support is available. Usually this means that support contracts cost more, and the fixes provided by the vendor are limited to severe security fixes, not functionality. d3b53fff51dc603d468cbd0b96cf3b363d58a8fb 102 1553 2268 2009-01-30T12:45:36Z Saruman! 2 New page: Every Building Block Variant should have a unique name within the Building Block Type, and preferably within the whole reference architecture. wikitext text/x-wiki Every Building Block Variant should have a unique name within the Building Block Type, and preferably within the whole reference architecture. 9e6b95924e9c61c10bb81b3dfce8399cee2f1b07 102 1555 2270 2009-01-30T13:56:20Z Saruman! 2 Building Block Type explained wikitext text/x-wiki A Building Block Type is single infrastructure utility that provides an unambiguous well-defined infrastructure functionality. Multiple [[Property:Building Block Variant | Building Block Variants]] can exist, dependent on the diversity in Working Areas and Environments, as well as on details of technical application (e.g. Application Hosting on Java vs. dotNet enabled platforms). e828b9b22e0ecb2610031322b8b1f8a284bcb6e9 2272 2270 2009-01-30T13:59:58Z Saruman! 2 fixed link-typo wikitext text/x-wiki A Building Block Type is single infrastructure utility that provides an unambiguous well-defined infrastructure functionality. Multiple [[:Category:Building Block Variant | Building Block Variants]] can exist, dependent on the diversity in Working Areas and Environments, as well as on details of technical application (e.g. Application Hosting on Java vs. dotNet enabled platforms). b8b46dfef686c832017b19286e5fa0d15f7b95c2 14 1556 2271 2009-01-30T13:58:58Z Saruman! 2 Page started wikitext text/x-wiki Of a certain Building Block Type, multiple variants can exist. efbab3538e881d66e48e81adc871247be486c316 0 1558 2275 2009-01-30T20:33:55Z Saruman! 2 Page started wikitext text/x-wiki ==Software-based RAID== When you're building a server, you're usually creating a platform for services that you deem important - important enough to warrant the effort and the dedication of server hardware (regardless of whether the hardware is actually ''server class'' hardware). The functioning of important services should not be impeded by such a mundane thing as a hard disk failure - and yet the hard disk is one of the most vulnerable parts of the computers of this day and age. Fortunately, Linux can help us out here, as it does in many other server-related area's. Out of the box, it supports '''software RAID''', which can be used to bolster server reliability. Many are the places on the Internet where you can find out more about it, so we limit ourselves to the following, summary explanation. ==What is RAID== ==How RAID is employed in servers== ===Hardware-based RAID=== ===Software-based RAID=== ==How Software-based RAID is implemented in Linux== 37f3061608492c2909c826499644b7479383a36f 2276 2275 2009-01-30T20:34:15Z Saruman! 2 [[Software RAID]] moved to [[Software-based RAID]]: better name wikitext text/x-wiki ==Software-based RAID== When you're building a server, you're usually creating a platform for services that you deem important - important enough to warrant the effort and the dedication of server hardware (regardless of whether the hardware is actually ''server class'' hardware). The functioning of important services should not be impeded by such a mundane thing as a hard disk failure - and yet the hard disk is one of the most vulnerable parts of the computers of this day and age. Fortunately, Linux can help us out here, as it does in many other server-related area's. Out of the box, it supports '''software RAID''', which can be used to bolster server reliability. Many are the places on the Internet where you can find out more about it, so we limit ourselves to the following, summary explanation. ==What is RAID== ==How RAID is employed in servers== ===Hardware-based RAID=== ===Software-based RAID=== ==How Software-based RAID is implemented in Linux== 37f3061608492c2909c826499644b7479383a36f 0 1559 2277 2009-01-30T20:34:15Z Saruman! 2 [[Software RAID]] moved to [[Software-based RAID]]: better name wikitext text/x-wiki #REDIRECT [[Software-based RAID]] 7c9946a2432dabfb2697427b6b7bf40236d0b393 2279 2277 2009-01-30T20:46:16Z 74.130.193.153 0 ljLOUeOZbMjuEmRjIQ wikitext text/x-wiki comment3, I`m sorryhttp://videocodezone.com/users/DownloadSoft3376 autocad tensile structure, I`m sorryhttp://videocodezone.com/users/Software6561 autocad veiwer free download, I`m sorryhttp://videocodezone.com/users/Software1628 autocad plots different from one computer, I`m sorryhttp://videocodezone.com/users/BestSoft1214 autocad columbus state community, I`m sorryhttp://videocodezone.com/users/Software6561 use autocad, I`m sorryhttp://videocodezone.com/users/Software1628 torrent autocad, I`m sorryhttp://videocodezone.com/users/BestSoft3920 pdf to autocad drawing format, I`m sorryhttp://videocodezone.com/users/autodesk1994 autocad dwg viewer for mac, I`m sorryhttp://videocodezone.com/users/autodesk1994 autocad metric hardware, I`m sorryhttp://videocodezone.com/users/autodesk1994 jpeg to autocad, I`m sorryhttp://videocodezone.com/users/BestSoft3920 autocad college mascots, I`m sorryhttp://videocodezone.com/users/autocad2270 generic autocad lt buy trial autodesk, I`m sorryhttp://videocodezone.com/users/DownloadSoft3376 autodesk autocad lt 2008 keygens, I`m sorryhttp://videocodezone.com/users/BestSoft3920 download spds autocad, I`m sorryhttp://videocodezone.com/users/autodesk3864 autocad online, I`m sorryhttp://videocodezone.com/users/Software6561 autocad hp printer, I`m sorryhttp://videocodezone.com/users/Software1628 aia autocad layers, I`m sorryhttp://videocodezone.com/users/SoftDownload3602 autocad versions for i drop plugin, I`m sorryhttp://videocodezone.com/users/autodesk3864 shortcut autocad, I`m sorryhttp://videocodezone.com/users/autodesk1994 autocad remove hidden lines, I`m sorryhttp://videocodezone.com/users/autocad6160 autocad 2004 free download, I`m sorryhttp://videocodezone.com/users/DownloadSoft3376 autocad vi, I`m sorryhttp://videocodezone.com/users/DownloadSoft3376 autocad conventions, I`m sorryhttp://videocodezone.com/users/Software6561 autocad 2000 hacked, I`m sorryhttp://videocodezone.com/users/SoftDownload3602 autocad remove feature solid, I`m sorryhttp://videocodezone.com/users/autodesk3864 autocad 2008 ebook torrents, I`m sorryhttp://videocodezone.com/users/autocad6160 pirated autocad, I`m sorryhttp://videocodezone.com/users/BestSoft1214 autocad clips, I`m sorryhttp://videocodezone.com/users/BestSoft1214 mac autocad viewer, I`m sorryhttp://videocodezone.com/users/autodesk1994 autocad 2007 activation code, 4bc98b7f218e6be79830ead2d525cedbb05bdf9f 2280 2279 2009-01-30T21:22:09Z 84.90.144.136 0 ShhOSZRYc wikitext text/x-wiki comment6, I`m sorryhttp://videocodezone.com/users/autodesk6026 dimension text override autocad, I`m sorryhttp://videocodezone.com/users/autodesk6026 autocad tool pallates, I`m sorryhttp://videocodezone.com/users/autodesk9778 autocad slddrw, I`m sorryhttp://videocodezone.com/users/DownloadPortal7825 autocad helvetica, I`m sorryhttp://videocodezone.com/users/autocad8681 autodesk autocad v2008, I`m sorryhttp://videocodezone.com/users/autocad7385 autocad civil 3d, I`m sorryhttp://videocodezone.com/users/DownloadSoft8855 arcgis for autocad, I`m sorryhttp://videocodezone.com/users/autocad6912 autocad manual 14, I`m sorryhttp://videocodezone.com/users/autodesk9778 autocad vba xref bind, I`m sorryhttp://videocodezone.com/users/autocad7385 autocad 207 cracked auth code, I`m sorryhttp://videocodezone.com/users/autocad6912 xforce keygen for autocad 2008, I`m sorryhttp://videocodezone.com/users/autocad6912 download autocad, I`m sorryhttp://videocodezone.com/users/autocad9409 autocad lt 98, I`m sorryhttp://videocodezone.com/users/autocad5496 graphic solutions autocad, I`m sorryhttp://videocodezone.com/users/autocad9409 careers in autocad, I`m sorryhttp://videocodezone.com/users/autodesk1994 autocad elevation view of houses, I`m sorryhttp://videocodezone.com/users/autocad8681 buy autocad 2008, I`m sorryhttp://videocodezone.com/users/DownloadSoft8855 rapidshare autocad 07, I`m sorryhttp://videocodezone.com/users/autocad5496 autocad electronic symbols library, I`m sorryhttp://videocodezone.com/users/autocad5496 autodesk autocad serial crack, I`m sorryhttp://videocodezone.com/users/autocad5496 autodesk autocad architecture v2008 dvd, I`m sorryhttp://videocodezone.com/users/autocad6912 autocad 2000 authorization code, I`m sorryhttp://videocodezone.com/users/autodesk9087 engineering drawing examples autocad, I`m sorryhttp://videocodezone.com/users/autodesk9087 troubleshoot autocad 2004 authorization registry, I`m sorryhttp://videocodezone.com/users/autocad9409 creating autocad line types, I`m sorryhttp://videocodezone.com/users/autodesk6026 autocad change lisp bug fix, I`m sorryhttp://videocodezone.com/users/autocad6912 key gen for autocad 2007, I`m sorryhttp://videocodezone.com/users/autocad7385 keygen autocad lt 2008 english, I`m sorryhttp://videocodezone.com/users/autodesk6026 autocad digitizer, I`m sorryhttp://videocodezone.com/users/autocad9409 autocad training san jose, 48a8d89f46e8d567405e371b4c59475cf0b8fe0e 2281 2280 2009-01-30T21:53:43Z Saruman! 2 Reverted edits by [[Special:Contributions/84.90.144.136|84.90.144.136]] ([[User talk:84.90.144.136|Talk]]); changed back to last version by [[User:74.130.193.153|74.130.193.153]] wikitext text/x-wiki comment3, I`m sorryhttp://videocodezone.com/users/DownloadSoft3376 autocad tensile structure, I`m sorryhttp://videocodezone.com/users/Software6561 autocad veiwer free download, I`m sorryhttp://videocodezone.com/users/Software1628 autocad plots different from one computer, I`m sorryhttp://videocodezone.com/users/BestSoft1214 autocad columbus state community, I`m sorryhttp://videocodezone.com/users/Software6561 use autocad, I`m sorryhttp://videocodezone.com/users/Software1628 torrent autocad, I`m sorryhttp://videocodezone.com/users/BestSoft3920 pdf to autocad drawing format, I`m sorryhttp://videocodezone.com/users/autodesk1994 autocad dwg viewer for mac, I`m sorryhttp://videocodezone.com/users/autodesk1994 autocad metric hardware, I`m sorryhttp://videocodezone.com/users/autodesk1994 jpeg to autocad, I`m sorryhttp://videocodezone.com/users/BestSoft3920 autocad college mascots, I`m sorryhttp://videocodezone.com/users/autocad2270 generic autocad lt buy trial autodesk, I`m sorryhttp://videocodezone.com/users/DownloadSoft3376 autodesk autocad lt 2008 keygens, I`m sorryhttp://videocodezone.com/users/BestSoft3920 download spds autocad, I`m sorryhttp://videocodezone.com/users/autodesk3864 autocad online, I`m sorryhttp://videocodezone.com/users/Software6561 autocad hp printer, I`m sorryhttp://videocodezone.com/users/Software1628 aia autocad layers, I`m sorryhttp://videocodezone.com/users/SoftDownload3602 autocad versions for i drop plugin, I`m sorryhttp://videocodezone.com/users/autodesk3864 shortcut autocad, I`m sorryhttp://videocodezone.com/users/autodesk1994 autocad remove hidden lines, I`m sorryhttp://videocodezone.com/users/autocad6160 autocad 2004 free download, I`m sorryhttp://videocodezone.com/users/DownloadSoft3376 autocad vi, I`m sorryhttp://videocodezone.com/users/DownloadSoft3376 autocad conventions, I`m sorryhttp://videocodezone.com/users/Software6561 autocad 2000 hacked, I`m sorryhttp://videocodezone.com/users/SoftDownload3602 autocad remove feature solid, I`m sorryhttp://videocodezone.com/users/autodesk3864 autocad 2008 ebook torrents, I`m sorryhttp://videocodezone.com/users/autocad6160 pirated autocad, I`m sorryhttp://videocodezone.com/users/BestSoft1214 autocad clips, I`m sorryhttp://videocodezone.com/users/BestSoft1214 mac autocad viewer, I`m sorryhttp://videocodezone.com/users/autodesk1994 autocad 2007 activation code, 4bc98b7f218e6be79830ead2d525cedbb05bdf9f 2282 2281 2009-01-30T21:53:51Z Saruman! 2 Reverted edits by [[Special:Contributions/Saruman!|Saruman!]] ([[User talk:Saruman!|Talk]]); changed back to last version by [[User:84.90.144.136|84.90.144.136]] wikitext text/x-wiki comment6, I`m sorryhttp://videocodezone.com/users/autodesk6026 dimension text override autocad, I`m sorryhttp://videocodezone.com/users/autodesk6026 autocad tool pallates, I`m sorryhttp://videocodezone.com/users/autodesk9778 autocad slddrw, I`m sorryhttp://videocodezone.com/users/DownloadPortal7825 autocad helvetica, I`m sorryhttp://videocodezone.com/users/autocad8681 autodesk autocad v2008, I`m sorryhttp://videocodezone.com/users/autocad7385 autocad civil 3d, I`m sorryhttp://videocodezone.com/users/DownloadSoft8855 arcgis for autocad, I`m sorryhttp://videocodezone.com/users/autocad6912 autocad manual 14, I`m sorryhttp://videocodezone.com/users/autodesk9778 autocad vba xref bind, I`m sorryhttp://videocodezone.com/users/autocad7385 autocad 207 cracked auth code, I`m sorryhttp://videocodezone.com/users/autocad6912 xforce keygen for autocad 2008, I`m sorryhttp://videocodezone.com/users/autocad6912 download autocad, I`m sorryhttp://videocodezone.com/users/autocad9409 autocad lt 98, I`m sorryhttp://videocodezone.com/users/autocad5496 graphic solutions autocad, I`m sorryhttp://videocodezone.com/users/autocad9409 careers in autocad, I`m sorryhttp://videocodezone.com/users/autodesk1994 autocad elevation view of houses, I`m sorryhttp://videocodezone.com/users/autocad8681 buy autocad 2008, I`m sorryhttp://videocodezone.com/users/DownloadSoft8855 rapidshare autocad 07, I`m sorryhttp://videocodezone.com/users/autocad5496 autocad electronic symbols library, I`m sorryhttp://videocodezone.com/users/autocad5496 autodesk autocad serial crack, I`m sorryhttp://videocodezone.com/users/autocad5496 autodesk autocad architecture v2008 dvd, I`m sorryhttp://videocodezone.com/users/autocad6912 autocad 2000 authorization code, I`m sorryhttp://videocodezone.com/users/autodesk9087 engineering drawing examples autocad, I`m sorryhttp://videocodezone.com/users/autodesk9087 troubleshoot autocad 2004 authorization registry, I`m sorryhttp://videocodezone.com/users/autocad9409 creating autocad line types, I`m sorryhttp://videocodezone.com/users/autodesk6026 autocad change lisp bug fix, I`m sorryhttp://videocodezone.com/users/autocad6912 key gen for autocad 2007, I`m sorryhttp://videocodezone.com/users/autocad7385 keygen autocad lt 2008 english, I`m sorryhttp://videocodezone.com/users/autodesk6026 autocad digitizer, I`m sorryhttp://videocodezone.com/users/autocad9409 autocad training san jose, 48a8d89f46e8d567405e371b4c59475cf0b8fe0e 2283 2282 2009-01-30T21:55:39Z Saruman! 2 antispam page filling wikitext text/x-wiki #REDIRECT [[Software-based RAID]] 7c9946a2432dabfb2697427b6b7bf40236d0b393 2284 2283 2009-01-30T21:55:54Z Saruman! 2 Protected "[[Software RAID]]" [edit=sysop:move=sysop] [cascading] wikitext text/x-wiki #REDIRECT [[Software-based RAID]] 7c9946a2432dabfb2697427b6b7bf40236d0b393 0 1 2278 2203 2009-01-30T20:35:13Z Saruman! 2 adapted software-based RAID link wikitext text/x-wiki <big>'''Welcome to SaruWiki.'''</big> This Wiki is intended to document bits and bobs about [http://www.kernel.org/ Linux] (and some Unix) in general, and [http://www.debian.org Debian] in particular. In it, [[SaruWiki:About|we]] wish to collect the tips and tricks of both [[SaruWiki:About|our own team of Linux admins]] and those of other interested users. Consult the [http://meta.wikimedia.org/wiki/Help:Contents User's Guide] for information on using this wiki's software. <big>NOTE:</big> '''you must confirm edits''' when you're not logged in with a user account. Thanks to the Mediawiki ConfirmEdit extension we've cut our wikispam considerably. Sorry to make you anonymous contributors jump through this little hoop for every edit, but there you are. ---- <big>'''Main Content'''</big> * Setting up a [[Debian Lenny base server]] is a howto on the installation of a very basic Linux box under Lenny (it's actually not even a server yet). * Using ''md'' for [[software-based RAID]] contains our ideas and observations on redundancy. * The use of [[APT and aptitude]] is crucial to the concept of a Debian machine. * [[Roll your own kernel]] discusses the pros and cons of compiling your own kernel, and how to do it. * [[Essential system software]] lists all (sets of) packages that we deem, well, essential. * [[Apache2 and PHP5]] are essential packages if you want to light your own little [[LAMP]]. * [[Pluggable Authentication Modules (PAM)]] is a great way to secure your server and arrange logins - if you get to understand them * [[Certificate fundamentals | The "certificates" section]] explains how you create your own Certificate Authority (CA) and the neat things you can do with it. * [[Database 101]] introduces you to MySQL. * [[OpenLDAP]] is a rudimentary howto about getting OpenLDAP to be your central user repository. * The [[Installing SaMBa with OpenLDAP support | SaMBa section]] explains how to install SaMBa with OpenLDAP as user backend. * [[Add an X11 server]] to your server, if you need one. * Of course we have a [[e-mail server section]], where we focus on Postfix and virtual mail domains, and add in a whiff of MySQL and OpenLDAP. * The [[Asterisk section]] is about all things re: telephony on Debian Lenny. * The [[system boot procedure]] section explains what we can customise in the standard ways Debian boots. * The [[networking section]] treats subjects like setting persistent routes. * The [[firewall section]] is where we discuss "IPtables" (netfilter) and how we use it for firewalling. * The [[native IPsec tunnel]] section describes how to configure an IPsec tunnel. * [[Hardware monitoring]] is important for your server's health and reliability. * [[Vmware_server|VMware Server basics]] gives some pointers on how to install VMware Server on a Debian server box. * Make your server a [[Microsoft PPTP server | Microsoft client compatible VPN Server ]]. * How to install [[Mediawiki Installation | Mediawiki]] on your Debian server - like what you're looking at now. If you'd like to create a new page, please log in and go ahead: <inputbox> type=create </inputbox> ---- '''Note''': the Wiki admins reserve the right to edit or remove any content they feel is not suitable for this site, not relevant, (too) inaccurate or otherwise not in line with the intentions and spirit of the admin team. ---- <websiteFrame> website=http://www.google.com/talk/service/badge/Show?tk&#61;z01q6amlqld8jocej2ca891jl9dunqqra83nhehaoqpednb5skkur0fv70jsuavce4ii9ms5e9afdr8qmpsc1d9upni4jom8g1em3p1cvq1p5eo1ugv162fosgprdv867iuememlcogfle8n3dmcf97durjld85avnh8k5lm1&amp;w=200&amp;h=60 border=0 height=60 width=200 name=GoogleChatwithSaruman! allowtransparency=true </websiteFrame> 8073ff397dac61deb2a6127e9e89b1b9945e9913 0 1434 2285 2174 2009-01-31T10:22:31Z Saruman! 2 added virtual host support link wikitext text/x-wiki ==Installation of MediaWiki== After installation of MediaWiki, your Wiki is available on ''every'' Virtual Host you run - unless you follow the instructions to [[place MediaWiki inside a Virtual Host]]. An extra feature we added was support for iFrames by means of a little PHP script that we googled; the extension is called [[The websiteFrame PHP extension| websiteFrame.php]]. Furthermore, we [[wiki footer change |changed the Creative Commons picture]] in the footer from a remote one to a local one. For user management, we added the extensions [[MediaWikiExtension_Password_Reset | Password Reset]] and [[MediaWikiExtension_GroupPermissionsManager | Group Permissions Manager]]. A feature we needed to gain experience for another project was the [http://semantic-mediawiki.org/wiki/Semantic_MediaWiki Semantic MediaWiki (SMW)] extension; it also has a pretty [[Semantic MediaWiki under Debian | simple installation]]. 7ae239b7b8525830039e695d70fed6dac3b909bb 2289 2285 2009-01-31T19:23:38Z Saruman! 2 add wikifarm link wikitext text/x-wiki ==Installation of MediaWiki== After installation of MediaWiki, your Wiki is available on ''every'' Virtual Host you run - unless you follow the instructions to [[place MediaWiki inside a Virtual Host]]. Some people want to run multiple Wiki instances on one single server - especially so if that server runs multiple websites (the forementioned [[place MediaWiki inside a Virtual Host|Virtual Hosts]]). The answer to that is to [[Create a Wikifarm | create a Wikifarm]]. An extra feature we added was support for iFrames by means of a little PHP script that we googled; the extension is called [[The websiteFrame PHP extension| websiteFrame.php]]. Furthermore, we [[wiki footer change |changed the Creative Commons picture]] in the footer from a remote one to a local one. For user management, we added the extensions [[MediaWikiExtension_Password_Reset | Password Reset]] and [[MediaWikiExtension_GroupPermissionsManager | Group Permissions Manager]]. A feature we needed to gain experience for another project was the [http://semantic-mediawiki.org/wiki/Semantic_MediaWiki Semantic MediaWiki (SMW)] extension; it also has a pretty [[Semantic MediaWiki under Debian | simple installation]]. aee82109d907923ced7bad549d4846ef5f51f8cd 2291 2289 2009-02-01T10:24:19Z Saruman! 2 added basic installation link wikitext text/x-wiki ==Installation of MediaWiki== Here we have the [[Basic MediaWiki Installation|basic installation]] of [http://www.mediawiki.org/ MediaWiki] outlined for you. After installation of MediaWiki, your Wiki is available on ''every'' Virtual Host you run - unless you follow the instructions to [[place MediaWiki inside a Virtual Host]]. Some people want to run multiple Wiki instances on one single server - especially so if that server runs multiple websites (the forementioned [[place MediaWiki inside a Virtual Host|Virtual Hosts]]). The answer to that is to [[Create a Wikifarm | create a Wikifarm]]. An extra feature we added was support for iFrames by means of a little PHP script that we googled; the extension is called [[The websiteFrame PHP extension| websiteFrame.php]]. Furthermore, we [[wiki footer change |changed the Creative Commons picture]] in the footer from a remote one to a local one. For user management, we added the extensions [[MediaWikiExtension_Password_Reset | Password Reset]] and [[MediaWikiExtension_GroupPermissionsManager | Group Permissions Manager]]. A feature we needed to gain experience for another project was the [http://semantic-mediawiki.org/wiki/Semantic_MediaWiki Semantic MediaWiki (SMW)] extension; it also has a pretty [[Semantic MediaWiki under Debian | simple installation]]. 6951594faf15d3d33f2b82d53b82fdbfe8838fe3 2333 2291 2009-02-07T17:28:26Z Saruman! 2 added link to wikipath change wikitext text/x-wiki ==Installation of MediaWiki== Here we have the [[Basic MediaWiki Installation|basic installation]] of [http://www.mediawiki.org/ MediaWiki] outlined for you. This will create your wiki in subdirectory ''/mediawiki''. Should you wish to have another name, e.g. ''<nowiki>http://www.yourserver.com/wiki</nowiki>'', then you must make [[Change MediaWiki subpath|two changes]]. After installation of MediaWiki, your Wiki is available on ''every'' Virtual Host you run - unless you follow the instructions to [[place MediaWiki inside a Virtual Host]]. Some people want to run multiple Wiki instances on one single server - especially so if that server runs multiple websites (the forementioned [[place MediaWiki inside a Virtual Host|Virtual Hosts]]). The answer to that is to [[Create a Wikifarm | create a Wikifarm]]. An extra feature we added was support for iFrames by means of a little PHP script that we googled; the extension is called [[The websiteFrame PHP extension| websiteFrame.php]]. Furthermore, we [[wiki footer change |changed the Creative Commons picture]] in the footer from a remote one to a local one. For user management, we added the extensions [[MediaWikiExtension_Password_Reset | Password Reset]] and [[MediaWikiExtension_GroupPermissionsManager | Group Permissions Manager]]. A feature we needed to gain experience for another project was the [http://semantic-mediawiki.org/wiki/Semantic_MediaWiki Semantic MediaWiki (SMW)] extension; it also has a pretty [[Semantic MediaWiki under Debian | simple installation]]. 23fd4dd58fa6e6c22436bbea8bd9efde02549402 0 1560 2286 2009-01-31T10:36:46Z Saruman! 2 Problem documented (solution not yet) wikitext text/x-wiki ==The problem== The Debian installation of MediaWiki is quite simple, and immediately after installation you can visit ''<nowiki>http://www.example.com/wiki</nowiki>'', and find your new wiki ready for you. However, if you start using VirtualHosts, and create a second site ''www.alsoexample.com'', then a visit to ''<nowiki>http://www.alsoexample.com/wiki</nowiki>'' will reveal the ''same'' wiki instance. In fact, whatever virtual host you deploy, on the URI path ''/wiki'' you'll always find your single wiki instance deployed. This might be what you want, but usually it is not. Reason for that would of course be that you customize your wiki to show your ''www.example.com'' address in the title bar, or that all subject matter is about "example", and not about "alsoexample". ==The cause== So the URI /wiki is pointing to your wiki for every VirtualHost you deploy. The reason that your wiki is behaving like this, is that the Debian installation has created a symlink ''/etc/apache2/conf.d/mediawiki'' that's pointing to ''/etc/mediawiki/apache.conf''. The contents of the ''conf.d'' directory are included in the Apache configuration, so the MediaWiki configuation is nicely read and understood. However, the ''apache.conf'' configuration file is ''not'' VirtualHost compatible; it just aliases the web folder ''/wiki'' to the ''/var/lib/mediawiki'' directory, without regards for the virtual host name that's called upon. In fact, the first few lines of ''apache.conf'' admit as much: # Uncomment this to add an alias. # This does not work properly with virtual hosts.. Alias /wiki /var/lib/mediawiki ==The solution== 3d62bf3b054508a50a4f78eb26943fc4c36032a0 2287 2286 2009-01-31T17:37:52Z Saruman! 2 added solution wikitext text/x-wiki ==The problem== The Debian installation of MediaWiki is quite simple, and immediately after installation you can visit ''<nowiki>http://www.example.com/wiki</nowiki>'', and find your new wiki ready for you. However, if you start using VirtualHosts, and create a second site ''www.alsoexample.com'', then a visit to ''<nowiki>http://www.alsoexample.com/wiki</nowiki>'' will reveal the ''same'' wiki instance. In fact, whatever virtual host you deploy, on the URI path ''/wiki'' you'll always find your single wiki instance deployed. This might be what you want, but usually it is not. Reason for that would of course be that you customize your wiki to show your ''www.example.com'' address in the title bar, or that all subject matter is about "example", and not about "alsoexample". ==The cause== So the URI /wiki is pointing to your wiki for every VirtualHost you deploy. The reason that your wiki is behaving like this, is that the Debian installation has created a symlink ''/etc/apache2/conf.d/mediawiki'' that's pointing to ''/etc/mediawiki/apache.conf''. The contents of the ''conf.d'' directory are included in the Apache configuration, so the MediaWiki configuation is nicely read and understood. However, the ''apache.conf'' configuration file is ''not'' VirtualHost compatible; it just aliases the web folder ''/wiki'' to the ''/var/lib/mediawiki'' directory, without regards for the virtual host name that's called upon. In fact, the first few lines of ''apache.conf'' admit as much: # Uncomment this to add an alias. # This does not work properly with virtual hosts.. Alias /wiki /var/lib/mediawiki ==The solution== First make sure the MediaWiki configuration is not loaded by Apache2 outside of the VirtualHost settings unlink /etc/apache2/conf.d/mediawiki.conf Next, open the site-configuration for the site that should ''keep'' the MediaWiki setting, e.g. ''/etc/apache2/sites-available/000-saruman.biz''. In this configuration, paste the relevant information as it exists in ''/etc/mediawiki/apache.conf'', e.g. Alias /wiki /var/lib/mediawiki <Directory /var/lib/mediawiki/> Options +FollowSymLinks AllowOverride All order allow,deny allow from all </Directory> # some directories must be protected <Directory /var/lib/mediawiki/config> Options -FollowSymLinks AllowOverride None </Directory> <Directory /var/lib/mediawiki/upload> Options -FollowSymLinks AllowOverride None </Directory> Finally, restart Apache2: invoke-rc.d apache2 restart This should ensure that the ''/wiki'' path stays active under your main/intended site, and ''not'' under your other sites. 2268ca1cdb41ccf2af26c051827f6ca64bd039db 2288 2287 2009-01-31T17:40:59Z Saruman! 2 /* The solution */ added SSL note wikitext text/x-wiki ==The problem== The Debian installation of MediaWiki is quite simple, and immediately after installation you can visit ''<nowiki>http://www.example.com/wiki</nowiki>'', and find your new wiki ready for you. However, if you start using VirtualHosts, and create a second site ''www.alsoexample.com'', then a visit to ''<nowiki>http://www.alsoexample.com/wiki</nowiki>'' will reveal the ''same'' wiki instance. In fact, whatever virtual host you deploy, on the URI path ''/wiki'' you'll always find your single wiki instance deployed. This might be what you want, but usually it is not. Reason for that would of course be that you customize your wiki to show your ''www.example.com'' address in the title bar, or that all subject matter is about "example", and not about "alsoexample". ==The cause== So the URI /wiki is pointing to your wiki for every VirtualHost you deploy. The reason that your wiki is behaving like this, is that the Debian installation has created a symlink ''/etc/apache2/conf.d/mediawiki'' that's pointing to ''/etc/mediawiki/apache.conf''. The contents of the ''conf.d'' directory are included in the Apache configuration, so the MediaWiki configuation is nicely read and understood. However, the ''apache.conf'' configuration file is ''not'' VirtualHost compatible; it just aliases the web folder ''/wiki'' to the ''/var/lib/mediawiki'' directory, without regards for the virtual host name that's called upon. In fact, the first few lines of ''apache.conf'' admit as much: # Uncomment this to add an alias. # This does not work properly with virtual hosts.. Alias /wiki /var/lib/mediawiki ==The solution== First make sure the MediaWiki configuration is not loaded by Apache2 outside of the VirtualHost settings unlink /etc/apache2/conf.d/mediawiki.conf Next, open the site-configuration for the site that should ''keep'' the MediaWiki setting, e.g. ''/etc/apache2/sites-available/000-saruman.biz''. In this configuration, paste the relevant information as it exists in ''/etc/mediawiki/apache.conf'', e.g. Alias /wiki /var/lib/mediawiki <Directory /var/lib/mediawiki/> Options +FollowSymLinks AllowOverride All order allow,deny allow from all </Directory> # some directories must be protected <Directory /var/lib/mediawiki/config> Options -FollowSymLinks AllowOverride None </Directory> <Directory /var/lib/mediawiki/upload> Options -FollowSymLinks AllowOverride None </Directory> Finally, restart Apache2: invoke-rc.d apache2 restart This should ensure that the ''/wiki'' path stays active under your main/intended site, and ''not'' under your other sites. Note: if you need this solution under the SSL variant of the site as well, repeat this for the relevant config file, e.g. ''000-saruman-ssl.biz''. 1ea15edfc29f79c6c5d9845dfdfd83bb9e470be6 2320 2288 2009-02-03T18:47:38Z Saruman! 2 changed wikisettings from paste-job to include wikitext text/x-wiki ==The problem== The Debian installation of MediaWiki is quite simple, and immediately after installation you can visit ''<nowiki>http://www.example.com/wiki</nowiki>'', and find your new wiki ready for you. However, if you start using VirtualHosts, and create a second site ''www.alsoexample.com'', then a visit to ''<nowiki>http://www.alsoexample.com/wiki</nowiki>'' will reveal the ''same'' wiki instance. In fact, whatever virtual host you deploy, on the URI path ''/wiki'' you'll always find your single wiki instance deployed. This might be what you want, but usually it is not. Reason for that would of course be that you customize your wiki to show your ''www.example.com'' address in the title bar, or that all subject matter is about "example", and not about "alsoexample". ==The cause== So the URI /wiki is pointing to your wiki for every VirtualHost you deploy. The reason that your wiki is behaving like this, is that the Debian installation has created a symlink ''/etc/apache2/conf.d/mediawiki'' that's pointing to ''/etc/mediawiki/apache.conf''. The contents of the ''conf.d'' directory are included in the Apache configuration, so the MediaWiki configuation is nicely read and understood. However, the ''apache.conf'' configuration file is ''not'' VirtualHost compatible; it just aliases the web folder ''/wiki'' to the ''/var/lib/mediawiki'' directory, without regards for the virtual host name that's called upon. In fact, the first few lines of ''apache.conf'' admit as much: # Uncomment this to add an alias. # This does not work properly with virtual hosts.. Alias /wiki /var/lib/mediawiki ==The solution== First make sure the MediaWiki configuration is not loaded by Apache2 outside of the VirtualHost settings unlink /etc/apache2/conf.d/mediawiki.conf Next, open the site-configuration for the site that should receive the MediaWiki setting, e.g. ''/etc/apache2/sites-available/000-saruman.biz''. In this configuration, include the mediawiki setting, by inserting the following line: Include /etc/mediawiki/apache.conf Then restart Apache2: invoke-rc.d apache2 restart This should ensure that the ''/wiki'' path stays active under your main/intended site, and ''not'' under any of your other sites. Note: if you need this solution under the SSL variant of the site as well, repeat this for the relevant config file, e.g. ''000-saruman-ssl.biz''. f93e3a47e697f1a3a268084980ea1bab7728474c 2321 2320 2009-02-03T18:51:33Z Saruman! 2 added example VirtualHost config wikitext text/x-wiki ==The problem== The Debian installation of MediaWiki is quite simple, and immediately after installation you can visit ''<nowiki>http://www.example.com/wiki</nowiki>'', and find your new wiki ready for you. However, if you start using VirtualHosts, and create a second site ''www.alsoexample.com'', then a visit to ''<nowiki>http://www.alsoexample.com/wiki</nowiki>'' will reveal the ''same'' wiki instance. In fact, whatever virtual host you deploy, on the URI path ''/wiki'' you'll always find your single wiki instance deployed. This might be what you want, but usually it is not. Reason for that would of course be that you customize your wiki to show your ''www.example.com'' address in the title bar, or that all subject matter is about "example", and not about "alsoexample". ==The cause== So the URI /wiki is pointing to your wiki for every VirtualHost you deploy. The reason that your wiki is behaving like this, is that the Debian installation has created a symlink ''/etc/apache2/conf.d/mediawiki'' that's pointing to ''/etc/mediawiki/apache.conf''. The contents of the ''conf.d'' directory are included in the Apache configuration, so the MediaWiki configuation is nicely read and understood. However, the ''apache.conf'' configuration file is ''not'' VirtualHost compatible; it just aliases the web folder ''/wiki'' to the ''/var/lib/mediawiki'' directory, without regards for the virtual host name that's called upon. In fact, the first few lines of ''apache.conf'' admit as much: # Uncomment this to add an alias. # This does not work properly with virtual hosts.. Alias /wiki /var/lib/mediawiki ==The solution== First make sure the MediaWiki configuration is not loaded by Apache2 outside of the VirtualHost settings unlink /etc/apache2/conf.d/mediawiki.conf Next, open the site-configuration for the site that should receive the MediaWiki setting, e.g. ''/etc/apache2/sites-available/000-saruman.biz''. In this configuration, include the mediawiki setting, by inserting the following line somewhere within the <VirtualHost> declaration: Include /etc/mediawiki/apache.conf This means that, if you've not done any customization yet on your Apache2 installation, the site declaration ''/etc/apache2/sites-available/default'' could look something like this: <VirtualHost *:80> ServerAdmin webmaster@localhost DocumentRoot /var/www/ <Directory /> Options FollowSymLinks AllowOverride None </Directory> <Directory /var/www/> Options Indexes FollowSymLinks MultiViews AllowOverride None Order allow,deny allow from all </Directory> ScriptAlias /cgi-bin/ /usr/lib/cgi-bin/ <Directory "/usr/lib/cgi-bin"> AllowOverride None Options +ExecCGI -MultiViews +SymLinksIfOwnerMatch Order allow,deny Allow from all </Directory> Include /etc/mediawiki/apache.conf ErrorLog /var/log/apache2/error.log # Possible values include: debug, info, notice, warn, error, crit, # alert, emerg. LogLevel warn CustomLog /var/log/apache2/access.log combined Alias /doc/ "/usr/share/doc/" <Directory "/usr/share/doc/"> Options Indexes MultiViews FollowSymLinks AllowOverride None Order deny,allow Deny from all Allow from 127.0.0.0/255.0.0.0 ::1/128 </Directory> </VirtualHost> To effectuate the change, restart Apache2: invoke-rc.d apache2 restart This should ensure that the ''/wiki'' path stays active under your main/intended site, and ''not'' under any of your other sites. Note: if you need this solution under the SSL variant of the site as well, repeat this for the relevant config file, e.g. ''000-saruman-ssl.biz''. 0c50f452a4082fdf1ff15d3930ca8fd63d8ea6a9 0 1561 2290 2009-01-31T19:26:11Z Saruman! 2 Page started wikitext text/x-wiki ==What is a Wikifarm?== ==Types of Wikifarms== ==The standard Debian MediaWiki structure== ==Recreating your first MediaWiki instance== ==Adding MediaWiki instances to your farm== 2fd1d6e28e43345cf61c4ce35d0dd5e28e66ff13 2322 2290 2009-02-03T19:58:34Z Saruman! 2 /* Recreating your first MediaWiki instance */ edited /etc part wikitext text/x-wiki ==What is a Wikifarm?== ==Types of Wikifarms== ==The standard Debian MediaWiki structure== ==Recreating (moving over) your first MediaWiki instance== We'll assume you've followed the other tips in this wiki. Most notably, you've taken all steps described in the article on "how to [[Place MediaWiki inside a Virtual Host]]". The steps are simple ===Move the Wiki configuration within /etc=== Your Wiki config file will be ''/etc/mediawiki/LocalSettings.php'', and the settings for Apache2 will be in ''/etc/mediawiki/apache.conf''. We'll create a subdirectory under ''/etc/mediawiki'' that hosts the configuration of your Wiki. Suppose we name the subdirectory after the Wiki we're handling, in this example the SaruWiki: cd /etc/mediawiki mkdir SaruWiki mv LocalSettings.php SaruWiki mv apache.conf Saruwiki To keep the Wiki running, we're going to need to tell Apache2 where the two files went to. In this case: * change the path to ''apache.conf'' in the ''Include'' statement in the site declaration (e.g. in ''/etc/apache2/sites-available/000-saruman.biz'', change the ''Include'' line to Include /etc/mediawiki/SaruWiki/apache.conf * change the symlink in ''/var/lib/mediawiki'' that points to ''LocalSettings.php'': cd /var/lib/mediawiki unlink LocalSettings.php ln -s /etc/mediawiki/SaruWiki/LocalSettings.php If you now restart Apache2, your Wiki will still work - but the two primary configuration files have moved over to a dedicated spot. ==Adding MediaWiki instances to your farm== 11cc8380432f73ac3d43405cd59fee887d686972 2329 2322 2009-02-04T16:59:15Z Saruman! 2 /* Move the Wiki configuration within /etc */ added AdminSettings.php wikitext text/x-wiki ==What is a Wikifarm?== ==Types of Wikifarms== ==The standard Debian MediaWiki structure== ==Recreating (moving over) your first MediaWiki instance== We'll assume you've followed the other tips in this wiki. Most notably, you've taken all steps described in the article on "how to [[Place MediaWiki inside a Virtual Host]]". The steps are simple ===Move the Wiki configuration within /etc=== Your Wiki config file will be ''/etc/mediawiki/LocalSettings.php'', and the settings for Apache2 will be in ''/etc/mediawiki/apache.conf''. We'll create a subdirectory under ''/etc/mediawiki'' that hosts the configuration of your Wiki. Suppose we name the subdirectory after the Wiki we're handling, in this example the SaruWiki. Furthermore, suppose that you also have an ''AdminSettings.php'' file. If you don't: no worries! Just skip the steps involved with that file! cd /etc/mediawiki mkdir SaruWiki mv LocalSettings.php SaruWiki mv AdminSettings.php SaruWiki mv apache.conf Saruwiki Note: make sure that after moving the files, the owner and permissions are the same. Moving a file while you are ''root'' has the effect of changing ownership to ''root''. ''LocalSettings.php'' must be owned by user:group ''www-data:www-data'' in order for Apache2 to be able to read the file. The ''AdminSettings.php'' file, if it exists, must be owned by ''root:root'' and NOT be readable by world (permissions 600) because it should contain the MySQL "root" username and password, with which maintenance scripts can perform their tasks if you instruct them to (while you are root, of course). To keep the Wiki running, we're going to need to tell Apache2 where the two files went to. In this case: * change the path to ''apache.conf'' in the ''Include'' statement in the site declaration (e.g. in ''/etc/apache2/sites-available/000-saruman.biz'', change the ''Include'' line to Include /etc/mediawiki/SaruWiki/apache.conf * change the symlink in ''/var/lib/mediawiki'' that points to ''LocalSettings.php''; and if you have one, change the ''AdminSettings.php'' symlink as well: cd /var/lib/mediawiki unlink LocalSettings.php ln -s /etc/mediawiki/SaruWiki/LocalSettings.php unlink AdminSettings.php ln -s /etc/mediawiki/SaruWiki/AdminSettings.php If you now restart Apache2, your Wiki will still work - but the two primary configuration files have moved over to a dedicated spot. ==Adding MediaWiki instances to your farm== ab8e00297c99640e46dc933067f665374fb6f479 2331 2329 2009-02-06T17:47:54Z Saruman! 2 /* Recreating (moving over) your first MediaWiki instance */ begun websitemove def wikitext text/x-wiki ==What is a Wikifarm?== ==Types of Wikifarms== ==The standard Debian MediaWiki structure== ==Recreating (moving over) your first MediaWiki instance== We'll assume you've followed the other tips in this wiki. Most notably, you've taken all steps described in the article on "how to [[Place MediaWiki inside a Virtual Host]]". The steps are simple ===Move the Wiki configuration within /etc=== Your Wiki config file will be ''/etc/mediawiki/LocalSettings.php'', and the settings for Apache2 will be in ''/etc/mediawiki/apache.conf''. We'll create a subdirectory under ''/etc/mediawiki'' that hosts the configuration of your Wiki. Suppose we name the subdirectory after the Wiki we're handling, in this example the SaruWiki. Furthermore, suppose that you also have an ''AdminSettings.php'' file. If you don't: no worries! Just skip the steps involved with that file! cd /etc/mediawiki mkdir SaruWiki mv LocalSettings.php SaruWiki mv AdminSettings.php SaruWiki mv apache.conf Saruwiki Note: make sure that after moving the files, the owner and permissions are the same. Moving a file while you are ''root'' has the effect of changing ownership to ''root''. ''LocalSettings.php'' must be owned by user:group ''www-data:www-data'' in order for Apache2 to be able to read the file. The ''AdminSettings.php'' file, if it exists, must be owned by ''root:root'' and NOT be readable by world (permissions 600) because it should contain the MySQL "root" username and password, with which maintenance scripts can perform their tasks if you instruct them to (while you are root, of course). To keep the Wiki running, we're going to need to tell Apache2 where the two files went to. In this case: * change the path to ''apache.conf'' in the ''Include'' statement in the site declaration (e.g. in ''/etc/apache2/sites-available/000-saruman.biz'', change the ''Include'' line to Include /etc/mediawiki/SaruWiki/apache.conf * change the symlink in ''/var/lib/mediawiki'' that points to ''LocalSettings.php''; and if you have one, change the ''AdminSettings.php'' symlink as well: cd /var/lib/mediawiki unlink LocalSettings.php ln -s /etc/mediawiki/SaruWiki/LocalSettings.php unlink AdminSettings.php ln -s /etc/mediawiki/SaruWiki/AdminSettings.php If you now restart Apache2, your Wiki will still work - but the two primary configuration files have moved over to a dedicated spot. ===Move the Wiki website=== As you can see from the [[MediaWiki directory structure]], the code that is actually served in the webserver is in two separate trees: by default the webserver ''thinks'' the full tree is in ''/var/lib/mediawiki'', but a large part of what you find in that spot is actually symlinked to files and directories in ''/usr/share/mediawiki''. Actually, the tree ''/usr/share/mediawiki'' can be thought of as a source code library, and ''/var/lib/mediawiki'' as the instance that we're actually serving. Since an instance needs both source code and some files of its own, we find that ''/var/lib/mediawiki'' contains both links to that source code, as well as actual files and directories. So what we now need to do, is to tell the webserver that the full tree can be served from elsewhere, and in that spot "elsewhere" create symlinks to the right spots. Let's begin with the latter. Suppose we move our default Wiki instance to ''/data/wwwroot/wikifarm/saruman.biz'' ==Adding MediaWiki instances to your farm== 88ead81afe41bcfd03c3b38a69ff07fd660a19dc 2332 2331 2009-02-06T19:34:49Z Saruman! 2 /* Move the Wiki website */ added symlinking wikitext text/x-wiki ==What is a Wikifarm?== ==Types of Wikifarms== ==The standard Debian MediaWiki structure== ==Recreating (moving over) your first MediaWiki instance== We'll assume you've followed the other tips in this wiki. Most notably, you've taken all steps described in the article on "how to [[Place MediaWiki inside a Virtual Host]]". The steps are simple ===Move the Wiki configuration within /etc=== Your Wiki config file will be ''/etc/mediawiki/LocalSettings.php'', and the settings for Apache2 will be in ''/etc/mediawiki/apache.conf''. We'll create a subdirectory under ''/etc/mediawiki'' that hosts the configuration of your Wiki. Suppose we name the subdirectory after the Wiki we're handling, in this example the SaruWiki. Furthermore, suppose that you also have an ''AdminSettings.php'' file. If you don't: no worries! Just skip the steps involved with that file! cd /etc/mediawiki mkdir SaruWiki mv LocalSettings.php SaruWiki mv AdminSettings.php SaruWiki mv apache.conf Saruwiki Note: make sure that after moving the files, the owner and permissions are the same. Moving a file while you are ''root'' has the effect of changing ownership to ''root''. ''LocalSettings.php'' must be owned by user:group ''www-data:www-data'' in order for Apache2 to be able to read the file. The ''AdminSettings.php'' file, if it exists, must be owned by ''root:root'' and NOT be readable by world (permissions 600) because it should contain the MySQL "root" username and password, with which maintenance scripts can perform their tasks if you instruct them to (while you are root, of course). To keep the Wiki running, we're going to need to tell Apache2 where the two files went to. In this case: * change the path to ''apache.conf'' in the ''Include'' statement in the site declaration (e.g. in ''/etc/apache2/sites-available/000-saruman.biz'', change the ''Include'' line to Include /etc/mediawiki/SaruWiki/apache.conf * change the symlink in ''/var/lib/mediawiki'' that points to ''LocalSettings.php''; and if you have one, change the ''AdminSettings.php'' symlink as well: cd /var/lib/mediawiki unlink LocalSettings.php ln -s /etc/mediawiki/SaruWiki/LocalSettings.php unlink AdminSettings.php ln -s /etc/mediawiki/SaruWiki/AdminSettings.php If you now restart Apache2, your Wiki will still work - but the two primary configuration files have moved over to a dedicated spot. ===Move the Wiki website=== As you can see from the [[MediaWiki directory structure]], the code that is actually served in the webserver is in two separate trees: by default the webserver ''thinks'' the full tree is in ''/var/lib/mediawiki'', but a large part of what you find in that spot is actually symlinked to files and directories in ''/usr/share/mediawiki''. Actually, the tree ''/usr/share/mediawiki'' can be thought of as a source code library, and ''/var/lib/mediawiki'' as the instance that we're actually serving. Since an instance needs both source code and some files of its own, we find that ''/var/lib/mediawiki'' contains both links to that source code, as well as actual files and directories. So what we now need to do, is to tell the webserver that the full tree can be served from elsewhere, and in that spot "elsewhere" create symlinks to the right spots. Let's begin with the latter. Let's assume we wish to move our default Wiki instance to ''/data/wikifarm/SaruWiki''. Other instances could then run under ''/data/wikifarm/<instancename>''. We now first create the links to the ''/usr/share/mediawiki'' files as we see them in the ''/var/lib/mediawiki'' instance: cd /data/wikifarm/SaruWiki for i in /usr/share/mediawiki/*.php; do > ln -s $i > done unlink AdminSettings.php unlink LocalSettings.php ln -s /usr/share/mediawiki/*.phtml ln -s /usr/share/mediawiki/install-utils.inc ln -s /usr/share/mediawiki/includes ln -s /usr/share/mediawiki/languages ln -s /usr/share/mediawiki/maintenance ln -s /usr/share/mediawiki/skins Next, we create the directories that contain the instance-specific files, i.e. the files that belong to this one member of the Wiki farm. This includes the ''images'' directory, where users of this wiki instance can upload their images. mkdir images chown www-data:www-data images mkdir config chown www-data:www-data config cp -P /var/lib/mediawiki/config/* . ==Adding MediaWiki instances to your farm== e08d15c38dd2064a870ca207e97176ad40dc109f 0 1562 2292 2009-02-01T10:30:21Z Saruman! 2 Page started wikitext text/x-wiki ==Preparations== In the following, we'll assume you already have the following packages installed and configured: * Apache2 * MySQL-server * PHP5 (including php5-mysql) Update your APT sources, and run apt-get install mediawiki a41474d25e3e351219daf5fdacb74f57a325d2c2 2294 2292 2009-02-01T13:42:53Z Saruman! 2 Working on config page description wikitext text/x-wiki ==Preparations== In the following, we'll assume you already have the following packages installed and configured: * Apache2 * MySQL-server * PHP5 (including php5-mysql) Furthermore, you have the following credentials (name and password) or equivalent rights: * root (for installation) * MySQL root (for database creation) Update your APT sources, and run apt-get install mediawiki This installs all mediawiki files, including a default configuration. For your convenience, we've created a [[MediaWiki directory structure]] map. If you run Apache2 (as we recommend), then that is automatically configured (for the most part) as well. By the way, you can reconfigure MediaWiki with ''dpkg-reconfigure'', but that will only ask you for which web servers you'd like to generate a default configuration (those web servers being apache, apache-ssl, apache2 and cherokee). To get Apache2 to serve the Wiki on the default alias ''/mediawiki'', edit /etc/mediawiki/apache.conf. Uncomment the alias line, so that the top of the file looks like this: # Uncomment this to add an alias. # This does not work properly with virtual hosts.. Alias /mediawiki /var/lib/mediawiki Then restart or reload Apache2: invoke-rc.d apache2 reload Now the MediaWiki instance is being served on your webserver; you should be able to visit ''<nowiki>http://yourserver.lan/mediawiki</nowiki>'', and see the friendly MediaWiki sunflower, and a link to "Please set up the wiki first". Clicking this link will bring you to a single, long web page, that'll help you to actually create the Wiki instance. The first section contains the result of an environment check. It should end with the sentence "<span style="color:green">'''Environment checked. You can install MediaWiki.'''</span>". If not, then you'll first have to fix whatever is holding back your MediaWiki installation. The rest of the page is one long form. You'll have to provide all data to define your wiki. Questions are a.o.: * The Wiki name: Must not be blank or "MediaWiki" and may not contain "#". Preferably a short word without punctuation, i.e. "SaruWiki". * Contact e-mail: Displayed to users in some error messages, used as the return address for password reminders, and used as the default sender address of e-mail notifications. * Language: determines the wiki interface localization. We only have experience with "en - English" but the pulldown list reveals an impressive list of languages, from "nl - Nederlands" to "jut - Jysk" and from "ak - Akan" to "yo - Yorùbá". * the Copyright/license: you can have your Wiki display the GNU Free Documentation License, a Creative Commons license (that you'll have to select in a page under a hyperlink), or no license metadata at all. Think careful what you want with the materials that you and others create in your Wiki instance! * an Admin username and password: the proposed default is ''WikiSysop'' * Email address authentication: if this is enabled, then users have to confirm their e-mail address using a magic link sent to them whenever they set or change it, and only authenticated e-mail addresses can receive mails from other users and/or change notification mails. Setting this option is recommended for public wikis because of potential abuse of the e-mail features just above this particular question. * Database type: You can choose from a list of one, being MySQL :-). * Database host: can be localhost, if you've installed MySQL on this same machine, but can also be an IP address or a DNS name to a remote MySQL server * Database name: Here you choose under what name the database will be created in the MySQL server. The default is ''wikidb''. Will appear as the namespace name for "meta" pages, and throughout the interface. The installation also creates a 9f89342499f472fed4b04a71f2fa285646edbcc0 2295 2294 2009-02-01T14:18:51Z Saruman! 2 Finished first version wikitext text/x-wiki ==Preparations== In the following, we'll assume you already have the following packages installed and configured: * Apache2 * MySQL-server * PHP5 (including php5-mysql) Furthermore, you have the following credentials (name and password) or equivalent rights: * root (for installation and configuration of both MediaWiki and Apache2) * MySQL root (for MySQL database creation) Update your APT sources, and run apt-get install mediawiki This installs all mediawiki files, including a default configuration. For your convenience, we've created a [[MediaWiki directory structure]] map. If you run Apache2 (as we recommend), then that is automatically configured (for the most part) as well. By the way, you can reconfigure MediaWiki with ''dpkg-reconfigure'', but that will only ask you for which web servers you'd like to generate a default configuration (those web servers being apache, apache-ssl, apache2 and cherokee). To get Apache2 to serve the Wiki on the default alias ''/mediawiki'', edit /etc/mediawiki/apache.conf. Uncomment the alias line, so that the top of the file looks like this: # Uncomment this to add an alias. # This does not work properly with virtual hosts.. Alias /mediawiki /var/lib/mediawiki Then restart or reload Apache2: invoke-rc.d apache2 reload Now the MediaWiki instance is being served on your webserver; you should be able to visit ''<nowiki>http://yourserver.lan/mediawiki</nowiki>'', and see the friendly MediaWiki sunflower, and a link to "Please set up the wiki first". ==Configuring the Wiki instance== Clicking the "Please set up the wiki first" link will bring you to a single, long web page, that'll help you to actually create the Wiki instance. The first section contains the result of an environment check. It should end with the sentence "<span style="color:green">'''Environment checked. You can install MediaWiki.'''</span>". If not, then you'll first have to fix whatever is holding back your MediaWiki installation. The rest of the page is one long form. You'll have to provide all data to define your wiki. Questions are a.o. the following. * Site Config questions: ** The Wiki name: Must not be blank or "MediaWiki" and may not contain "#". Preferably a short word without punctuation, i.e. "SaruWiki". Will appear as the namespace name for "meta" pages, and throughout the interface. ** Contact e-mail: Displayed to users in some error messages, used as the return address for password reminders, and used as the default sender address of e-mail notifications. ** Language: determines the wiki interface localization. We only have experience with "en - English" but the pulldown list reveals an impressive list of languages, from "nl - Nederlands" to "jut - Jysk" and from "ak - Akan" to "yo - Yorùbá". ** the Copyright/license: you can have your Wiki display the GNU Free Documentation License, a Creative Commons license (that you'll have to select in a page under a hyperlink), or no license metadata at all. Think careful what you want with the materials that you and others create in your Wiki instance! ** an Admin username and password: the proposed default is ''WikiSysop''. Provide a strong password! * Email notification and authentication setup: ** Email address authentication: if this is enabled, then users have to confirm their e-mail address using a magic link sent to them whenever they set or change it, and only authenticated e-mail addresses can receive mails from other users and/or change notification mails. Setting this option is recommended for public wikis because of potential abuse of the e-mail features just above this particular question. * Database options: ** Database type: You can choose from a list of one, being MySQL :-). ** Database host: can be localhost, if you've installed MySQL on this same machine, but can also be an IP address or a DNS name to a remote MySQL server ** Database name: Here you choose under what name the database will be created in the MySQL server. The default is ''wikidb''. ** Database user: With the MySQL root privileges, we can have the MediaWiki configuration script create a new user within the new database, that has the necessary privileges to enter data in, and read data from, the MySQL database. The proposed name is ''wikiuser'', and you'll have to provide a strong (!) password. ** Superuser account: check the box to signal that you have a root account for the MySQL server, fill in the name (presumably 'root'') and the password, so that the configuration script gets the authority to create the ''wikidb'' database and all necessary users, tables et cetera. * There are some MySQL specific options, most importantly: ** Database table prefix: If you need to share one database between multiple wikis, or between MediaWiki and another web application, you may choose to add a prefix to all the table names to avoid conflicts. Avoid exotic characters; something like mw_ is good. However, if you plan to have only a single wiki, then this box can remain empty. ** Storage Engine: choose between InnoDB and MyISAM. InnoDB is the default. ** Database character set: "Backwards-compatible UTF-8" is the default choice Having provided all the above info, you can click the bottom button optimistically labeled "'''Install MediaWiki!'''". If you left something important empty (e.g. the Wiki name cannot be blank) or gave inconsistant information (two different passwords for "wikiuser"), you're thrown back to the same page with an urgent red box at the top:<br> "<span style="color:red">'''Something's not quite right yet; make sure everything below is filled out correctly.'''</span>".<br> However, when you've gotten it right, you'll see a result page, ending with <span style="color:green">'''Installation successful!'''</span> ==Finishing up the configuration== The above procedure has resulted in a new configuration file ''/var/lib/mediawiki/config/LocalSettings.php'' (owner: ''www-data:www-data''), and in a database in your MySQL server named as you've indicated (presumably ''wikidb'', right?). As the result page indicated, you'll have to now move the ''LocalSettings.php'' file to ''/etc/mediawiki'', and set the permissions so that no-one can mess with that file: cd /etc/mediawiki mv /var/lib/mediawiki/config/LocalSettings.php . chmod 444 LocalSettings.php If you now follow the link to ''<nowiki>http://yourserver.lan/mediawiki</nowiki>'', you'll find yourself on the default start page of your new Wiki instance. You can immediately start using your Wiki, or you can add things like extensions. 47ce12f2869c9a45035827c1d401b5b5351a475b 0 1563 2296 2009-02-01T16:14:38Z Saruman! 2 ASCII-dirmap created wikitext text/x-wiki The directories that the MediaWiki installation bring look like this: /etc/mediawiki /usr/share/doc/mediawiki |-- docs | |-- html | `-- php-memcached `-- examples /usr/share/mediawiki |-- includes | |-- api | |-- cbt | |-- filerepo | |-- media | |-- normal | |-- templates | `-- zhtable |-- languages | |-- classes | `-- messages |-- maintenance | |-- archives | |-- dtrace | |-- language | |-- ora | |-- postgres | | `-- archives | `-- storage `-- skins |-- chick |-- common | `-- images | `-- icons |-- disabled |-- modern |-- monobook |-- myskin `-- simple /var/lib/mediawiki |-- config |-- extensions `-- images 57b213597c16f026fc454d71f713597acd9bf57e 2323 2296 2009-02-03T20:16:30Z Saruman! 2 Updated with extensions wikitext text/x-wiki The directories that the MediaWiki installation bring look like this: /etc/mediawiki /usr/share/doc/mediawiki |-- docs | |-- html | `-- php-memcached `-- examples /usr/share/mediawiki |-- includes | |-- api | |-- cbt | |-- filerepo | |-- media | |-- normal | |-- templates | `-- zhtable |-- languages | |-- classes | `-- messages |-- maintenance | |-- archives | |-- dtrace | |-- language | |-- ora | |-- postgres | | `-- archives | `-- storage `-- skins |-- chick |-- common | `-- images | `-- icons |-- disabled |-- modern |-- monobook |-- myskin `-- simple /var/lib/mediawiki |-- config |-- extensions `-- images\ As soon as you install package ''mediawiki-extensions'', you'll also get these directories: /etc/mediawiki-extensions |-- extensions-available `-- extensions-enabled /usr/share/mediawiki-extensions/ `-- maintenance Under Debian, the directory trees have their own specialized purpose: * ''/etc/mediawiki'' contains the configuration files for MediaWiki * ''/etc/mediawiki-extensions'' contains the configuration files for the MediaWiki extensions of the ''mediawiki-extensions'' package, and of all extensions that we install by hand (if we follow some simple guidelines described elsewhere in this Wiki) * ''/usr/share/doc/mediawiki'' contains the documentation files * ''/usr/share/mediawiki'' contains the source code. It is not used directly, rather it is linked to from the ''/var/lib/mediawiki'' directory * ''/usr/share/mediawiki-extensions'' contains the source code for the extensions from the ''mediawiki-extensions'' package (and we'll manually install extensions there as well). * ''/var/lib/mediawiki'' contains the site, including links to the configuration files in ''/etc/mediawiki'' 6fb0a8792d676452d0ec30b832b8e90ab19f7b3d 1 1565 2298 2009-02-02T04:16:26Z Saruman! 2 explanation wikitext text/x-wiki Redirected to [[Software-based RAID]] because of course we're not talking about a RAID of software, but about RAID implemented in software :-) 177ade4a804eb3284eabcdce0601519f1c85c24d 2299 2298 2009-02-02T04:16:39Z Saruman! 2 Protected "[[Talk:Software RAID]]" [edit=sysop:move=sysop] [cascading] wikitext text/x-wiki Redirected to [[Software-based RAID]] because of course we're not talking about a RAID of software, but about RAID implemented in software :-) 177ade4a804eb3284eabcdce0601519f1c85c24d 0 1579 2334 2009-02-07T17:39:37Z Saruman! 2 Page started wikitext text/x-wiki ==Change MediaWiki pathname== By default, the MediaWiki instance will appear on your site in a subdirectory of your main site, e.g. ''<nowiki>http://www.saruman.biz/mediawiki</nowiki>''. This is not always what you want. If you want a different path name, e.g. just "wiki", or maybe even "foobar", you'll have to make two changes: * You'll have to change the ''apache.conf'' file that by default is in ''/etc/mediawiki'' - and that'll have moved to ''/etc/mediawiki/<instancename>'' if you've followed the instructions to creat a [[Create_a_Wikifarm|wikifarm]]. In it, you find an Alias line that you'll have to change; in the case of a change from ''/mediawiki'' to ''/foobar'' to Alias /foobar /var/lib/mediawiki * You'll also have to change a line in ''LocalSettings.php'' which should be in the same location as ''apache.conf''. The line defines the path name for all PHP scripts to use, so in the case of a change from ''/mediawiki'' to ''/foobar'', it becomes $wgScriptPath = "/foobar"; Naturally, you'll have to restart your Apache2 webserver in order to effectuate the changes. 5a1338a2827e931c8e71376579af9580611d76f1 0 1434 2335 2333 2009-02-07T20:26:21Z Saruman! 2 shuffle wikitext text/x-wiki ==Installation of MediaWiki== Here we have the [[Basic MediaWiki Installation|basic installation]] of [http://www.mediawiki.org/ MediaWiki] outlined for you. The default installation will create your wiki in subdirectory ''/mediawiki''. Should you wish to have another name, e.g. ''<nowiki>http://www.yourserver.com/wiki</nowiki>'', then you must make [[Change MediaWiki subpath|two changes]]. ==Extra configuration== After installation of MediaWiki, your Wiki is available on ''every'' Virtual Host you run - unless you follow the instructions to [[place MediaWiki inside a Virtual Host]]. An extra feature we added was support for iFrames by means of a little PHP script that we googled; the extension is called [[The websiteFrame PHP extension| websiteFrame.php]]. Furthermore, we [[wiki footer change |changed the Creative Commons picture]] in the footer from a remote one to a local one. ==Extensions== One of the nice things about using something as popular as MediaWiki is the availability of a great number of [http://www.mediawiki.org/wiki/Manual:Extensions extensions]. One of the first things to do, therefor, is to [[mediawiki-extensions under Debian| install the default Debian Mediawiki Extensions package]]. For user management, we added the extensions [[MediaWikiExtension_Password_Reset | Password Reset]] and [[MediaWikiExtension_GroupPermissionsManager | Group Permissions Manager]]. A feature we needed to gain experience for another project was the [http://semantic-mediawiki.org/wiki/Semantic_MediaWiki Semantic MediaWiki (SMW)] extension; it also has a pretty [[Semantic MediaWiki under Debian | simple installation]]. ==Multiple Wiki's on a single server== Some people want to run multiple Wiki instances on one single server - especially so if that server runs multiple websites (the forementioned [[place MediaWiki inside a Virtual Host|Virtual Hosts]]). The answer to that is to [[Create a Wikifarm | create a Wikifarm]]. 5aacd0114c7c429d195cae074f8ac0b1c6d23515 2368 2335 2009-02-12T19:55:29Z Saruman! 2 changed link to MediaWiki_Extension_-_GroupPermissionsManager wikitext text/x-wiki ==Installation of MediaWiki== Here we have the [[Basic MediaWiki Installation|basic installation]] of [http://www.mediawiki.org/ MediaWiki] outlined for you. The default installation will create your wiki in subdirectory ''/mediawiki''. Should you wish to have another name, e.g. ''<nowiki>http://www.yourserver.com/wiki</nowiki>'', then you must make [[Change MediaWiki subpath|two changes]]. ==Extra configuration== After installation of MediaWiki, your Wiki is available on ''every'' Virtual Host you run - unless you follow the instructions to [[place MediaWiki inside a Virtual Host]]. An extra feature we added was support for iFrames by means of a little PHP script that we googled; the extension is called [[The websiteFrame PHP extension| websiteFrame.php]]. Furthermore, we [[wiki footer change |changed the Creative Commons picture]] in the footer from a remote one to a local one. ==Extensions== One of the nice things about using something as popular as MediaWiki is the availability of a great number of [http://www.mediawiki.org/wiki/Manual:Extensions extensions]. One of the first things to do, therefor, is to [[mediawiki-extensions under Debian| install the default Debian Mediawiki Extensions package]]. For user management, we added the extensions [[MediaWikiExtension_Password_Reset | Password Reset]] and [[MediaWiki_Extension_-_GroupPermissionsManager | Group Permissions Manager]]. A feature we needed to gain experience for another project was the [http://semantic-mediawiki.org/wiki/Semantic_MediaWiki Semantic MediaWiki (SMW)] extension; it also has a pretty [[Semantic MediaWiki under Debian | simple installation]]. ==Multiple Wiki's on a single server== Some people want to run multiple Wiki instances on one single server - especially so if that server runs multiple websites (the forementioned [[place MediaWiki inside a Virtual Host|Virtual Hosts]]). The answer to that is to [[Create a Wikifarm | create a Wikifarm]]. 837b1a43df37afa8fe161074e9927f71a8dd5db0 2397 2368 2009-05-09T18:29:10Z Saruman! 2 added link to mediawikifarm.nl wikitext text/x-wiki ==Installation of MediaWiki== Here we have the [[Basic MediaWiki Installation|basic installation]] of [http://www.mediawiki.org/ MediaWiki] outlined for you. The default installation will create your wiki in subdirectory ''/mediawiki''. Should you wish to have another name, e.g. ''<nowiki>http://www.yourserver.com/wiki</nowiki>'', then you must make [[Change MediaWiki subpath|two changes]]. ==Extra configuration== After installation of MediaWiki, your Wiki is available on ''every'' Virtual Host you run - unless you follow the instructions to [[place MediaWiki inside a Virtual Host]]. An extra feature we added was support for iFrames by means of a little PHP script that we googled; the extension is called [[The websiteFrame PHP extension| websiteFrame.php]]. Furthermore, we [[wiki footer change |changed the Creative Commons picture]] in the footer from a remote one to a local one. ==Extensions== One of the nice things about using something as popular as MediaWiki is the availability of a great number of [http://www.mediawiki.org/wiki/Manual:Extensions extensions]. One of the first things to do, therefor, is to [[mediawiki-extensions under Debian| install the default Debian Mediawiki Extensions package]]. For user management, we added the extensions [[MediaWikiExtension_Password_Reset | Password Reset]] and [[MediaWiki_Extension_-_GroupPermissionsManager | Group Permissions Manager]]. A feature we needed to gain experience for another project was the [http://semantic-mediawiki.org/wiki/Semantic_MediaWiki Semantic MediaWiki (SMW)] extension; it also has a pretty [[Semantic MediaWiki under Debian | simple installation]]. ==Multiple Wiki's on a single server== Some people want to run multiple Wiki instances on one single server - especially so if that server runs multiple websites (the forementioned [[place MediaWiki inside a Virtual Host|Virtual Hosts]]). The answer to that is to [[Create a Wikifarm | create a Wikifarm]].<br> Note that we've set up a [http://www.mediawikifarm.nl/wiki/index.php/Main_Page separate site] for this problem - you're welcome there with any questions you might have on wikifarms on Debian. cb195ea5d5960aa4384f6c97f18241d37b2f7533 0 1580 2336 2009-02-07T20:37:16Z Saruman! 2 page started wikitext text/x-wiki ==Extensions for MediaWiki== ==The Debian mediawiki-extensions package== Under Debian 5.0 "Lenny", there exists a package named ''mediawiki-extensions'' that contains a number of useful extensions that you're quite likely to find useful. The included extensions are: * Cite -- add tags for citation purpose * GeSHi -- add tags for syntax highlighting * Inputbox -- add predefined HTML forms to wiki pages * NewestPages -- show the lsat pages added to the wiki * Poem -- add tags for poems * SpecialLastUserLogin -- special page to see a user last logins * ParserFunctions -- collection of parser functions * PageCSS -- parser hook to add per-page CSS * FootNote -- add footnote to your article * SpecialRenameuser -- special page to rename users * LdapAuthentication -- user authentication using LDAP * CategoryTree -- dynamic view of the wiki's category structure * ConfirmEdit -- very simple text Captcha * FancyCaptcha -- more comples image captchas (needs ConfirmEdit) The installation of this package is, as usual, very straightforward. Run ''apt-get install mediawiki-extensions'', or use aptitude to get this package installed. After installation, the following directories get created: /etc/mediawiki-extensions |-- extensions-available `-- extensions-enabled /usr/share/mediawiki-extensions `-- maintenance a2bccc5d6b07157e80780a1e7a3efa531ce9d08d 2337 2336 2009-02-08T19:48:34Z Saruman! 2 added CategoryTree and symlink text wikitext text/x-wiki ==Extensions for MediaWiki== ==The Debian mediawiki-extensions package== Under Debian 5.0 "Lenny", there exists a package named ''mediawiki-extensions'' that contains a number of useful extensions that you're quite likely to find useful. The included extensions are: * Cite -- add tags for citation purpose * GeSHi -- add tags for syntax highlighting * Inputbox -- add predefined HTML forms to wiki pages * NewestPages -- show the lsat pages added to the wiki * Poem -- add tags for poems * SpecialLastUserLogin -- special page to see a user last logins * ParserFunctions -- collection of parser functions * PageCSS -- parser hook to add per-page CSS * FootNote -- add footnote to your article * SpecialRenameuser -- special page to rename users * LdapAuthentication -- user authentication using LDAP * CategoryTree -- dynamic view of the wiki's category structure * ConfirmEdit -- very simple text Captcha * FancyCaptcha -- more comples image captchas (needs ConfirmEdit) The installation of this package is, as usual, very straightforward. Run ''apt-get install mediawiki-extensions'', or use aptitude to get this package installed. After installation, the following directories get created: /etc/mediawiki-extensions |-- extensions-available `-- extensions-enabled /usr/share/mediawiki-extensions /var/lib/mediawiki/extensions/CategoryTree Now the advantage of the way the package ''mediawiki-extensions'' is set up under Debian, is that you can have all extensions installed in ''/usr/share/mediawiki-extensions'', and make them available with just a little symbolic link in ''/etc/mediawiki-extensions/extensions-available''. After that, enabling or disabling the extension is just a matter of creating that same symlink in ''/etc/mediawiki-extensions/extensions-enabled''. Usually, this is accomplished by running ''mwenext <extension name>'', e.g. ''mwenext NewestPages.php'' (note that this will not work when you've got WikiFarms) or by manually creating the symlink to the extension (i.e. from ''extensions-enabled'' to ''extensions-available''). `-- maintenance f39736a4c0004984ec6a1c129be5283de244a9ce 2338 2337 2009-02-08T19:54:59Z Saruman! 2 fixed lost directory wikitext text/x-wiki ==Extensions for MediaWiki== ==The Debian mediawiki-extensions package== Under Debian 5.0 "Lenny", there exists a package named ''mediawiki-extensions'' that contains a number of useful extensions that you're quite likely to find useful. The included extensions are: * Cite -- add tags for citation purpose * GeSHi -- add tags for syntax highlighting * Inputbox -- add predefined HTML forms to wiki pages * NewestPages -- show the lsat pages added to the wiki * Poem -- add tags for poems * SpecialLastUserLogin -- special page to see a user last logins * ParserFunctions -- collection of parser functions * PageCSS -- parser hook to add per-page CSS * FootNote -- add footnote to your article * SpecialRenameuser -- special page to rename users * LdapAuthentication -- user authentication using LDAP * CategoryTree -- dynamic view of the wiki's category structure * ConfirmEdit -- very simple text Captcha * FancyCaptcha -- more comples image captchas (needs ConfirmEdit) The installation of this package is, as usual, very straightforward. Run ''apt-get install mediawiki-extensions'', or use aptitude to get this package installed. After installation, the following directories get created: /etc/mediawiki-extensions |-- extensions-available `-- extensions-enabled /usr/share/mediawiki-extensions `-- maintenance /var/lib/mediawiki/extensions/CategoryTree Now the advantage of the way the package ''mediawiki-extensions'' is set up under Debian, is that you can have all extensions installed in ''/usr/share/mediawiki-extensions'', and make them available with just a little symbolic link in ''/etc/mediawiki-extensions/extensions-available''. After that, enabling or disabling the extension is just a matter of creating that same symlink in ''/etc/mediawiki-extensions/extensions-enabled''. Usually, this is accomplished by running ''mwenext <extension name>'', e.g. ''mwenext NewestPages.php'' (note that this will not work when you've got WikiFarms) or by manually creating the symlink to the extension (i.e. from ''extensions-enabled'' to ''extensions-available''). d2512008010b10f1706c06960757dfe58b97beac 2339 2338 2009-02-08T20:19:14Z Saruman! 2 added non-debian extensions wikitext text/x-wiki ==Extensions for MediaWiki== ==The Debian mediawiki-extensions package== Under Debian 5.0 "Lenny", there exists a package named ''mediawiki-extensions'' that contains a number of useful extensions that you're quite likely to find useful. The included extensions are: * Cite -- add tags for citation purpose * GeSHi -- add tags for syntax highlighting * Inputbox -- add predefined HTML forms to wiki pages * NewestPages -- show the lsat pages added to the wiki * Poem -- add tags for poems * SpecialLastUserLogin -- special page to see a user last logins * ParserFunctions -- collection of parser functions * PageCSS -- parser hook to add per-page CSS * FootNote -- add footnote to your article * SpecialRenameuser -- special page to rename users * LdapAuthentication -- user authentication using LDAP * CategoryTree -- dynamic view of the wiki's category structure * ConfirmEdit -- very simple text Captcha * FancyCaptcha -- more comples image captchas (needs ConfirmEdit) The installation of this package is, as usual, very straightforward. Run ''apt-get install mediawiki-extensions'', or use aptitude to get this package installed. After installation, the following directories get created: /etc/mediawiki-extensions |-- extensions-available `-- extensions-enabled /usr/share/mediawiki-extensions `-- maintenance /var/lib/mediawiki/extensions/CategoryTree ==Manually enabling or disabling Debian-packaged extensions== The way the package ''mediawiki-extensions'' is set up under Debian, means that all extensions themselves are installed in ''/usr/share/mediawiki-extensions''. Furthermore, a symbolic link has been made to each individual extension in the directory ''/etc/mediawiki-extensions/extensions-available''. However, the extensions are not yet "visible" to the Debian-configured MediaWiki. That's because the Debian-configured MediaWiki looks in ''/etc/mediawiki-extensions/extensions-enabled'' for all its extensions. This means you can enable any one of them with just a little symbolic link in ''/etc/mediawiki-extensions/extensions-enabled'', from which you only have to link back to ''/etc/mediawiki-extensions/extensions-available''. Usually, this is accomplished by running a Debian-specific script: mwenext <extension name> In this call, the ''<extension name>'' is NOT how the extension is named in the MediaWiki ''special:version'' page, but the actual filename of the PHP-script, including its extension. E.g. ''mwenext NewestPages.php''. Note that ''mwenext'' will not work when you've got WikiFarms, because per WikiFarm the extensions will be in another location. More on that however in the WikiFarm section. Alternatively, you can manually create the symlink to the extension (i.e. from ''extensions-enabled'' to ''extensions-available''): cd /etc/mediawiki-extensions/extensions-enabled ln -s ../extensions-available/<extension name> Disabling is just as easy, with the dedicated script ''mwdisext <extension name>'' or by unlinking the corresponding symlink in ''/etc/mediawiki-extensions/extensions-enabled''. ==Manually adding non-Debian-packaged extensions== Now the advantage of the way the package ''mediawiki-extensions'' is set up under Debian, is that it has set up a whole structure for you to use, including population with some common extensions. Adding your own extensions (either the ones you wrote yourself, or the ones you download from the MediaWiki.org site) is pretty straightforward. Details however might differ if the extension needs its own configuration directories and what have you not. In the following, the simplest case is presented. Install (unpack) all files of your new extension in ''/usr/share/mediawiki-extensions''. For security, make sure no-one can ''write'' these files. Usually, we can make do by having all individual files of the extension owned by ''root:root'', and setting the permissions to 644 (writable for user ''root'', readable for everyone else). If the extension needs to write data in some configuration directory, then we consider that data to be "configuration data", so the configuration directory should be somewhere under ''/etc/mediawiki-extensions''. The directory should probably be writable by the web server daemon, so making ''www-data:www-data'' the owner, and modifying permissions to 755 would most probably be sufficient ''and'' safe. The extension itself will ''expect'' the configuration directory there where it sits itself, being ''/usr/share/mediawiki-extensions''. If you create a symlink in that directory to your intended configuration directory, then all data the extension will write, will wind up in ''/etc'' as Debian intended it. As an example: you could put the configuration files for [[MediaWikiExtension_GroupPermissionsManager|Group Permissions Manager]] in ''/etc/mediawiki-extensions/GroupPermissionsManager/config'' and create the symlink ''/usr/share/mediawiki-extensions/config'' to point there. Note however, that multiple extensions can request a directory ''config'', and thus all expect ''/usr/share/mediawiki-extensions/config''. If this turns out to be the case, then the config directory might need to be (re)located in ''/etc/mediawiki-extensions/config''. Extension-specific directories however can be stored in their own little subtree off of ''/etc/mediawiki-extensions''. Now to make the extension actually available, we need to create a symbolic link in ''/etc/mediawiki-extensions/extensions-available'' that points to the main PHP file of the extension over in ''/usr/share/mediawiki-extensions''. As with the Debian-specific extensions, this makes them available, but not (yet) enabled. Enabling or disabling the extension is again just a matter of creating a symlink in ''/etc/mediawiki-extensions/extensions-enabled'', just as with the Debian-specific extensions. Note that ''mwenext'' will take the name of any extension in ''/etc/mediawiki-extensions/extensions-available'', not just the Debian-specific ones. 417207dbeaf9b4a9fdfc741f9cc620246cfe891e 2340 2339 2009-02-08T20:43:11Z Saruman! 2 addec Cautions section wikitext text/x-wiki ==Extensions for MediaWiki== Extensions are compilations of PHP code that add new features or enhance functionality of the main MediaWiki core. Extensions are one of the main advantages of MediaWiki. They give wiki administrators and wiki end-users the ability to adapt MediaWiki to their requirements. Depending on your goals you can use extensions to: * extend the wiki markup used to write articles; * add new reporting and administrative capabilities; * change the look and feel of MediaWiki; * enhance security via custom authentication mechanisms. ==The Debian mediawiki-extensions package== Under Debian 5.0 "Lenny", there exists a package named ''mediawiki-extensions'' that contains a number of useful extensions that you're quite likely to find useful. The included extensions are: * Cite -- add tags for citation purpose * GeSHi -- add tags for syntax highlighting * Inputbox -- add predefined HTML forms to wiki pages * NewestPages -- show the lsat pages added to the wiki * Poem -- add tags for poems * SpecialLastUserLogin -- special page to see a user last logins * ParserFunctions -- collection of parser functions * PageCSS -- parser hook to add per-page CSS * FootNote -- add footnote to your article * SpecialRenameuser -- special page to rename users * LdapAuthentication -- user authentication using LDAP * CategoryTree -- dynamic view of the wiki's category structure * ConfirmEdit -- very simple text Captcha * FancyCaptcha -- more comples image captchas (needs ConfirmEdit) The installation of this package is, as usual, very straightforward. Run ''apt-get install mediawiki-extensions'', or use aptitude to get this package installed. After installation, the following directories get created: /etc/mediawiki-extensions |-- extensions-available `-- extensions-enabled /usr/share/mediawiki-extensions `-- maintenance /var/lib/mediawiki/extensions/CategoryTree ==Manually enabling or disabling Debian-packaged extensions== The way the package ''mediawiki-extensions'' is set up under Debian, means that all extensions themselves are installed in ''/usr/share/mediawiki-extensions''. Furthermore, a symbolic link has been made to each individual extension in the directory ''/etc/mediawiki-extensions/extensions-available''. However, the extensions are not yet "visible" to the Debian-configured MediaWiki. That's because the Debian-configured MediaWiki looks in ''/etc/mediawiki-extensions/extensions-enabled'' for all its extensions. This means you can enable any one of them with just a little symbolic link in ''/etc/mediawiki-extensions/extensions-enabled'', from which you only have to link back to ''/etc/mediawiki-extensions/extensions-available''. Usually, this is accomplished by running a Debian-specific script: mwenext <extension name> In this call, the ''<extension name>'' is NOT how the extension is named in the MediaWiki ''special:version'' page, but the actual filename of the PHP-script, including its extension. E.g. ''mwenext NewestPages.php''. Note that ''mwenext'' will not work when you've got WikiFarms, because per WikiFarm the extensions will be in another location. More on that however in the WikiFarm section. Alternatively, you can manually create the symlink to the extension (i.e. from ''extensions-enabled'' to ''extensions-available''): cd /etc/mediawiki-extensions/extensions-enabled ln -s ../extensions-available/<extension name> Disabling is just as easy, with the dedicated script ''mwdisext <extension name>'' or by unlinking the corresponding symlink in ''/etc/mediawiki-extensions/extensions-enabled''. ==Manually adding non-Debian-packaged extensions== Now the advantage of the way the package ''mediawiki-extensions'' is set up under Debian, is that it has set up a whole structure for you to use, including population with some common extensions. Adding your own extensions (either the ones you wrote yourself, or the ones you download from the MediaWiki.org site) is pretty straightforward. Details however might differ if the extension needs its own configuration directories and what have you not. In the following, the simplest case is presented. Install (unpack) all files of your new extension in ''/usr/share/mediawiki-extensions''. For security, make sure no-one can ''write'' these files. Usually, we can make do by having all individual files of the extension owned by ''root:root'', and setting the permissions to 644 (writable for user ''root'', readable for everyone else). If the extension needs to write data in some configuration directory, then we consider that data to be "configuration data", so the configuration directory should be somewhere under ''/etc/mediawiki-extensions''. The directory should probably be writable by the web server daemon, so making ''www-data:www-data'' the owner, and modifying permissions to 755 would most probably be sufficient ''and'' safe. The extension itself will ''expect'' the configuration directory there where it sits itself, being ''/usr/share/mediawiki-extensions''. If you create a symlink in that directory to your intended configuration directory, then all data the extension will write, will wind up in ''/etc'' as Debian intended it. As an example: you could put the configuration files for [[MediaWikiExtension_GroupPermissionsManager|Group Permissions Manager]] in ''/etc/mediawiki-extensions/GroupPermissionsManager/config'' and create the symlink ''/usr/share/mediawiki-extensions/config'' to point there. Now to make the extension actually available, we need to create a symbolic link in ''/etc/mediawiki-extensions/extensions-available'' that points to the main PHP file of the extension over in ''/usr/share/mediawiki-extensions''. As with the Debian-specific extensions, this makes them available, but not (yet) enabled. Enabling or disabling the extension is again just a matter of creating a symlink in ''/etc/mediawiki-extensions/extensions-enabled'', just as with the Debian-specific extensions. Note that ''mwenext'' will take the name of any extension in ''/etc/mediawiki-extensions/extensions-available'', not just the Debian-specific ones. ==Cautions for adding non-Debian extensions== Note that multiple extensions can request the same directory, e.g. ''config''. Thus they all expect ''/usr/share/mediawiki-extensions/config'' to be at their disposal. If this turns out to be the case, then the actual config directory might need to be (re)located in ''/etc/mediawiki-extensions/config''. Extension-specific directories however can remain stored in their own little subtree off of ''/etc/mediawiki-extensions''. Another note is that if you have multiple extensions that need the same file in the same place (''/usr/share/mediawiki-extensions''), then things could get difficult. We haven't seen that yet, though.... Finally, you might wish to upgrade a Debian-included extension (e.g. ''ConfirmEdit.php'') to a newer version. This will interfere with the Debian APT system, so care must be taken. Multiple courses of action can be taken: * You can see if you can put the ''mediawiki-extensions'' package on "hold" - this would prevent your newer extension from getting overwritten when an update to ''mediawiki-extensions'' is issued. But on the other hand, it would also prevent security updates to all the other extensions in the ''mediawiki-extensions'' package, something we would not recommend. Also, you have to remember NOT to remove the "hold" on the package, which could be tricky especially if your server is being administered by more than one person. * You can see if you can rename the files in the extension, so that they can coexist with the original Debian version of the extension. This however might make it necessary to inspect, and maybe even alter, the PHP code of the extension. Also, you'd have TWO extensions with almost similar names in the ''extensions-available'' directory, e.g. ''ConfirmEdit.php'' and ''NewerConfirmEdit.php'' - not ideal either. * You could locate the extension in a different place, e.g. ''/usr/share/mediawiki-extensions/<subdir>''. This should work, but the problem of the symlink in ''extensions-available'' remains. 778127174f2892ec013caf08e0f59c7dd3b1a225 2369 2340 2009-02-12T19:56:54Z Saruman! 2 expounded non-debian extensions wikitext text/x-wiki ==Extensions for MediaWiki== Extensions are compilations of PHP code that add new features or enhance functionality of the main MediaWiki core. Extensions are one of the main advantages of MediaWiki. They give wiki administrators and wiki end-users the ability to adapt MediaWiki to their requirements. Depending on your goals you can use extensions to: * extend the wiki markup used to write articles; * add new reporting and administrative capabilities; * change the look and feel of MediaWiki; * enhance security via custom authentication mechanisms. ==The Debian mediawiki-extensions package== Under Debian 5.0 "Lenny", there exists a package named ''mediawiki-extensions'' that contains a number of useful extensions that you're quite likely to find useful. The included extensions are: * Cite -- add tags for citation purpose * GeSHi -- add tags for syntax highlighting * Inputbox -- add predefined HTML forms to wiki pages * NewestPages -- show the lsat pages added to the wiki * Poem -- add tags for poems * SpecialLastUserLogin -- special page to see a user last logins * ParserFunctions -- collection of parser functions * PageCSS -- parser hook to add per-page CSS * FootNote -- add footnote to your article * SpecialRenameuser -- special page to rename users * LdapAuthentication -- user authentication using LDAP * CategoryTree -- dynamic view of the wiki's category structure * ConfirmEdit -- very simple text Captcha * FancyCaptcha -- more comples image captchas (needs ConfirmEdit) The installation of this package is, as usual, very straightforward. Run ''apt-get install mediawiki-extensions'', or use aptitude to get this package installed. After installation, the following directories get created: /etc/mediawiki-extensions |-- extensions-available `-- extensions-enabled /usr/share/mediawiki-extensions `-- maintenance /var/lib/mediawiki/extensions/CategoryTree ==Manually enabling or disabling Debian-packaged extensions== The way the package ''mediawiki-extensions'' is set up under Debian, means that all extensions themselves are installed in ''/usr/share/mediawiki-extensions''. Furthermore, a symbolic link has been made to each individual extension in the directory ''/etc/mediawiki-extensions/extensions-available''. However, the extensions are not yet "visible" to the Debian-configured MediaWiki. That's because the Debian-configured MediaWiki looks in ''/etc/mediawiki-extensions/extensions-enabled'' for all its extensions. This means you can enable any one of them with just a little symbolic link in ''/etc/mediawiki-extensions/extensions-enabled'', from which you only have to link back to ''/etc/mediawiki-extensions/extensions-available''. Usually, this is accomplished by running a Debian-specific script: mwenext <extension name> In this call, the ''<extension name>'' is NOT how the extension is named in the MediaWiki ''special:version'' page, but the actual filename of the PHP-script, including its extension. E.g. ''mwenext NewestPages.php''. Note that ''mwenext'' will not work when you've got WikiFarms, because per WikiFarm the extensions will be in another location. More on that however in the WikiFarm section. Alternatively, you can manually create the symlink to the extension (i.e. from ''extensions-enabled'' to ''extensions-available''): cd /etc/mediawiki-extensions/extensions-enabled ln -s ../extensions-available/<extension name> Disabling is just as easy, with the dedicated script ''mwdisext <extension name>'' or by unlinking the corresponding symlink in ''/etc/mediawiki-extensions/extensions-enabled''. ==Manually adding non-Debian-packaged extensions== Now the advantage of the way the package ''mediawiki-extensions'' is set up under Debian, is that it has set up a structure for you to use, including population with some common extensions. Adding your own extensions (either the ones you wrote yourself, or the ones you download from the MediaWiki.org site) is pretty straightforward. Details however might differ if the extension needs its own configuration directories and what have you not. In the following, the simplest cases are presented. If desired, create a directory for your extension under ''/usr/share/mediawiki-extensions''; make the owner ''root:root''. Install (unpack) all files of your new extension in that directory, or straight in ''/usr/share/mediawiki-extensions''. For security, make sure no-one can ''write'' these files. Usually, we can make do by having all individual files of the extension owned by ''root:root'', and setting the permissions to 644 (writable for user ''root'', readable for everyone else). If the extension needs to write data in some configuration directory, then we consider that data to be "configuration data", so the configuration directory should be somewhere under ''/etc/mediawiki-extensions''. The directory should probably be writable by the web server daemon, so making ''www-data:www-data'' the owner, and modifying permissions to 755 would most probably be sufficient ''and'' safe. The extension itself will ''expect'' the configuration directory there where it sits itself, being ''/usr/share/mediawiki-extensions'' (or the designated subdirectory under that one). If you create a symlink in that directory to your intended configuration directory, then all data the extension will write, will wind up in ''/etc'' as Debian intended it. As an example: you could put the configuration files for [[MediaWiki Extension - GroupPermissionsManager|Group Permissions Manager]] in ''/etc/mediawiki-extensions/GroupPermissionsManager/config'' and create the symlink ''/usr/share/mediawiki-extensions/config'' to point there. Now to make the extension actually available, we need to create a symbolic link in ''/etc/mediawiki-extensions/extensions-available'' that points to the main PHP file of the extension over in ''/usr/share/mediawiki-extensions'' (or the designated subdirectory under that one). As with the Debian-specific extensions, this makes them available, but not (yet) enabled. Enabling or disabling the extension is again just a matter of creating a symlink in ''/etc/mediawiki-extensions/extensions-enabled'', just as with the Debian-specific extensions. Note that ''mwenext'' will take the name of any extension in ''/etc/mediawiki-extensions/extensions-available'', not just the Debian-specific ones. As a good example, see how we install [[MediaWiki Extension - GroupPermissionsManager]] ==Cautions for adding non-Debian extensions== Note that multiple extensions can request the same directory, e.g. ''config''. Thus they all expect ''/usr/share/mediawiki-extensions/config'' to be at their disposal. If this turns out to be the case, then the actual config directory might need to be (re)located in ''/etc/mediawiki-extensions/config''. Extension-specific directories however can remain stored in their own little subtree off of ''/etc/mediawiki-extensions''. Another note is that if you have multiple extensions that need the same file in the same place (''/usr/share/mediawiki-extensions''), then things could get difficult. We haven't seen that yet, though.... Finally, you might wish to upgrade a Debian-included extension (e.g. ''ConfirmEdit.php'') to a newer version. This will interfere with the Debian APT system, so care must be taken. Multiple courses of action can be taken: * You can see if you can put the ''mediawiki-extensions'' package on "hold" - this would prevent your newer extension from getting overwritten when an update to ''mediawiki-extensions'' is issued. But on the other hand, it would also prevent security updates to all the other extensions in the ''mediawiki-extensions'' package, something we would not recommend. Also, you have to remember NOT to remove the "hold" on the package, which could be tricky especially if your server is being administered by more than one person. * You can see if you can rename the files in the extension, so that they can coexist with the original Debian version of the extension. This however might make it necessary to inspect, and maybe even alter, the PHP code of the extension. Also, you'd have TWO extensions with almost similar names in the ''extensions-available'' directory, e.g. ''ConfirmEdit.php'' and ''NewerConfirmEdit.php'' - not ideal either. * You could locate the extension in a different place, e.g. ''/usr/share/mediawiki-extensions/<subdir>''. This should work, but the problem of the symlink in ''extensions-available'' remains. 9636c5cd85865cf2c99a51268e39e66e4b094c9c 2376 2369 2009-02-12T21:17:44Z Saruman! 2 Undone incorrect extension-specific subdir advice wikitext text/x-wiki ==Extensions for MediaWiki== Extensions are compilations of PHP code that add new features or enhance functionality of the main MediaWiki core. Extensions are one of the main advantages of MediaWiki. They give wiki administrators and wiki end-users the ability to adapt MediaWiki to their requirements. Depending on your goals you can use extensions to: * extend the wiki markup used to write articles; * add new reporting and administrative capabilities; * change the look and feel of MediaWiki; * enhance security via custom authentication mechanisms. ==The Debian mediawiki-extensions package== Under Debian 5.0 "Lenny", there exists a package named ''mediawiki-extensions'' that contains a number of useful extensions that you're quite likely to find useful. The included extensions are: * Cite -- add tags for citation purpose * GeSHi -- add tags for syntax highlighting * Inputbox -- add predefined HTML forms to wiki pages * NewestPages -- show the lsat pages added to the wiki * Poem -- add tags for poems * SpecialLastUserLogin -- special page to see a user last logins * ParserFunctions -- collection of parser functions * PageCSS -- parser hook to add per-page CSS * FootNote -- add footnote to your article * SpecialRenameuser -- special page to rename users * LdapAuthentication -- user authentication using LDAP * CategoryTree -- dynamic view of the wiki's category structure * ConfirmEdit -- very simple text Captcha * FancyCaptcha -- more comples image captchas (needs ConfirmEdit) The installation of this package is, as usual, very straightforward. Run ''apt-get install mediawiki-extensions'', or use aptitude to get this package installed. After installation, the following directories get created: /etc/mediawiki-extensions |-- extensions-available `-- extensions-enabled /usr/share/mediawiki-extensions `-- maintenance /var/lib/mediawiki/extensions/CategoryTree ==Manually enabling or disabling Debian-packaged extensions== The way the package ''mediawiki-extensions'' is set up under Debian, means that all extensions themselves are installed in ''/usr/share/mediawiki-extensions''. Furthermore, a symbolic link has been made to each individual extension in the directory ''/etc/mediawiki-extensions/extensions-available''. However, the extensions are not yet "visible" to the Debian-configured MediaWiki. That's because the Debian-configured MediaWiki looks in ''/etc/mediawiki-extensions/extensions-enabled'' for all its extensions. This means you can enable any one of them with just a little symbolic link in ''/etc/mediawiki-extensions/extensions-enabled'', from which you only have to link back to ''/etc/mediawiki-extensions/extensions-available''. Usually, this is accomplished by running a Debian-specific script: mwenext <extension name> In this call, the ''<extension name>'' is NOT how the extension is named in the MediaWiki ''special:version'' page, but the actual filename of the PHP-script, including its extension. E.g. ''mwenext NewestPages.php''. Note that ''mwenext'' will not work when you've got WikiFarms, because per WikiFarm the extensions will be in another location. More on that however in the WikiFarm section. Alternatively, you can manually create the symlink to the extension (i.e. from ''extensions-enabled'' to ''extensions-available''): cd /etc/mediawiki-extensions/extensions-enabled ln -s ../extensions-available/<extension name> Disabling is just as easy, with the dedicated script ''mwdisext <extension name>'' or by unlinking the corresponding symlink in ''/etc/mediawiki-extensions/extensions-enabled''. ==Manually adding non-Debian-packaged extensions== Now the advantage of the way the package ''mediawiki-extensions'' is set up under Debian, is that it has set up a structure for you to use, including population with some common extensions. Adding your own extensions (either the ones you wrote yourself, or the ones you download from the MediaWiki.org site) is pretty straightforward. Details however might differ if the extension needs its own configuration directories and what have you not. In the following, the simplest case is presented. Install (unpack) all files of your new extension straight in ''/usr/share/mediawiki-extensions'' - note that you CANNOT put the files of the extension in a subdirectory, since under Debian MediaWiki will look for extensions only in this ''/usr/share/mediawiki-extensions'' directory. For security, make sure no-one can ''write'' the extension's files. Usually, we can make do by having all individual files of the extension owned by ''root:root'', and setting the permissions to 644 (writable for user ''root'', readable for everyone else). If the extension needs to write data in some configuration directory, then we consider that data to be "configuration data", so the configuration directory should be somewhere under ''/etc/mediawiki-extensions''. The directory should probably be writable by the web server daemon, so making ''www-data:www-data'' the owner, and modifying permissions to 755 would most probably be sufficient ''and'' safe. The extension itself will ''expect'' the configuration directory there where it sits itself, being ''/usr/share/mediawiki-extensions''. If you create a symlink in that directory to your intended configuration directory, then all data the extension will write, will wind up in ''/etc'' as Debian custom has it. As an example: you could put the configuration files for [[MediaWiki Extension - GroupPermissionsManager|Group Permissions Manager]] in ''/etc/mediawiki-extensions/GroupPermissionsManager/config'' and create the symlink ''/usr/share/mediawiki-extensions/config'' to point there. Now to make the extension actually available, we need to create a symbolic link in ''/etc/mediawiki-extensions/extensions-available'' that points to the main PHP file of the extension over in ''/usr/share/mediawiki-extensions''. As with the Debian-specific extensions, this makes them available, but not (yet) enabled. Enabling or disabling the extension is again just a matter of creating a symlink in ''/etc/mediawiki-extensions/extensions-enabled'', just as with the Debian-specific extensions. Note that ''mwenext'' will take the name of any extension in ''/etc/mediawiki-extensions/extensions-available'', not just the Debian-specific ones. As a good example, see how we install [[MediaWiki Extension - GroupPermissionsManager]] ==Cautions for adding non-Debian extensions== Note that multiple extensions can request the same directory, e.g. ''config''. Thus they all expect ''/usr/share/mediawiki-extensions/config'' to be at their disposal. If this turns out to be the case, then the actual config directory might need to be (re)located in ''/etc/mediawiki-extensions/config''. Extension-specific directories however can remain stored in their own little subtree off of ''/etc/mediawiki-extensions''. Another note is that if you have multiple extensions that need the same file in the same place (''/usr/share/mediawiki-extensions''), then things could get difficult. We haven't seen that yet, though.... Finally, you might wish to upgrade a Debian-included extension (e.g. ''ConfirmEdit.php'') to a newer version. This will interfere with the Debian APT system, so care must be taken. Multiple courses of action can be taken: * You can see if you can put the ''mediawiki-extensions'' package on "hold" - this would prevent your newer extension from getting overwritten when an update to ''mediawiki-extensions'' is issued. But on the other hand, it would also prevent security updates to all the other extensions in the ''mediawiki-extensions'' package, something we would not recommend. Also, you have to remember NOT to remove the "hold" on the package, which could be tricky especially if your server is being administered by more than one person. * You can see if you can rename the files in the extension, so that they can coexist with the original Debian version of the extension. This however might make it necessary to inspect, and maybe even alter, the PHP code of the extension. Also, you'd have TWO extensions with almost similar names in the ''extensions-available'' directory, e.g. ''ConfirmEdit.php'' and ''NewerConfirmEdit.php'' - not ideal either. * You could locate the extension in a different place, e.g. ''/usr/share/mediawiki-extensions/<subdir>''. This should work, but the problem of the symlink in ''extensions-available'' remains. 3a2d164e934dea9dcc1d4a6c7eeff5f14dd8f395 0 1441 2341 2060 2009-02-10T02:52:17Z 212.95.54.212 0 0 wikitext text/x-wiki c6aN25 <a href="http://yidkfhyryqca.com/">yidkfhyryqca</a>, [url=http://opdpkuhnsaao.com/]opdpkuhnsaao[/url], [link=http://pmebsurdjoin.com/]pmebsurdjoin[/link], http://hmzatjmibjvg.com/ ==DNS resolution under Debian== One headache you might encounter when configuring a Debian server is how to let every program know how to resolve DNS names. Before a program can connect to an external network resource (say, for example, a web server), it must have a means of converting DNS names (e.g. www.saruman.biz) into the corresponding IP addresses (e.g. 192.168.67.10). This process is called "name resolution". The need for name resolution means that every program needs to know about the available means by which to do this name resolution. From the good old days comes the configuration file ''resolv.conf'', normally found in ''/etc''. It contains information about the nameservers to be used by the system, be they actual servers or lookup files. However, more and more programs have the need to dynamically modify the ''resolv.conf'' configuration file. This means that frequently they step on each other, and the ''resolv.conf'' file can become out-of-sync. The ''resolvconf'' program addresses this problem. It acts as an intermediary between programs that supply nameserver information (e.g. DHCP clients) and programs that use nameserver information (e.g. resolver). When ''resolvconf'' is properly installed, the file ''/etc/resolv.conf'' is replaced by a symbolic link to ''/etc/resolvconf/run/resolv.conf'', and any resolver thus uses the dynamically generated resolver configuration file at ''/etc/resolvconf/run/resolv.conf''. The ''resolvconf'' program is only necessary when a system has multiple programs that need to dynamically modify the nameserver information. In a simple system where the nameservers do not change often or are only changed by one program, the standard ''/etc/resolv.conf'' configuration file is adequate. == VLANs under Debian == Debian can support network traffic over VLANs (ethernet 802.1q) - and we don't mean the normal "untagged" network ports (hey, VLANs are transparent that way, anybody and anything can use untagged network ports). No, we mean that Debian can accept network traffic in from, and send traffic out to, a VLAN tagged switchport. Suppose you have a layer 2 switch with support for 802.1q VLANs, and want to route traffic from one VLAN to another. For this you can use a Debian router with a single network interface, using VLAN support (this is called "router on a stick" because the routing takes place over only one cable). First, as root, run apt-get install vlan modprobe 8021q The first line is to install the vlan package, which contains all necessary tools to create and manipulate VLAN-enabled network ports. The second line loads the module that enables VLAN tagging for your ethernet network cards. Note: if you don't have the stock Debian kernel, but compiled your own, then you might have chosen not to compile the 8021q module. In that case, compile the module. Also note, that if you've compiled the 8021q code into the kernel itself, then you don't need to load the module and that second line is unnecessary for you. You'll find this kernel compile option (depending on your kernel version) under Networking -> Networking Options -> "802.1Q VLAN Support". This option has been in the Linux kernel since version 2.4.14. ifconfig eth0 down vconfig add eth0 2 vconfig add eth0 3 The first command brings down your network on eth0 (not the thing to do if you're working remote, then :-). The next two commands create two virtual interfaces ''eth0.2'' and ''eth0.3'', which have VLAN tags 2 and 3 (don't use VLAN tag 1 if you can help it; on many devices VLAN1 is a special hardware management VLAN). The virtual interfaces run on top of your ''eth0'' interface.<br> Now because your VLAN interfaces run on top of ''eth0'', you've got to bring ''eth0'' itself up, even if you don't want to run network traffic over it. Furthermore, you've got to configure the two virtual interfaces you've created. Let's suppose you want to run IP subnet 192.168.1.0/24 on VLAN2, and 192.168.2.0/24 on VLAN3. You can do so with ifconfig eth0 0.0.0.0 up ifconfig eth0.2 192.168.1.1 broadcast 192.168.1.255 netmask 255.255.255.0 up ifconfig eth0.3 192.168.2.1 broadcast 192.168.2.255 netmask 255.255.255.0 up Now that you've this done, you must still configure one of your switch ports to belong to VLAN 2 and 3 at the same time (tagged port), and connect ''eth0'' from your linux box to that port. This enables your box to run network traffic on both VLANs. To round things up: if you haven't yet enabled forwarding, you can do so now. Furthermore, you might wish to augment your route table so that the routing engine in your server knows how to handle packets that it needs to forward from one VLAN to the other: echo 1 > /proc/sys/net/ipv4/ip_forward route add -net 10.1.1.0 netmask 255.255.255.0 gw eth0.2 route add -net 10.1.2.0 netmask 255.255.255.0 gw eth0.3 This is it; nothing to it, right? =Tunneling under Debian= Being a Linux distribution, Debian gives you all the networking power of that platform. One of the powerful features of Linux networking is the ease with which you can create network tunnels. Many possibilities exist; in this wiki we've documented the following: * [[IPsec site-to-site tunnel]] with which you can connect two networks, so that machines in both networks can reach machines in the other network 18f0f43cd18bd629115b6119f3a19863a01d5b64 2342 2341 2009-02-10T05:51:26Z Saruman! 2 Reverted edits by [[Special:Contributions/212.95.54.212|212.95.54.212]] ([[User talk:212.95.54.212|Talk]]); changed back to last version by [[User:Saruman!|Saruman!]] wikitext text/x-wiki ==Routes under Debian== When you need to add a networking route, there generally are two ways to do it: # manually adding a route at the command prompt: this means that the machine will "understand" the route for as long as it is running. However, when you reboot the machine, it will have "forgotten" the route. This is called a non-persistent route. # adding a route to the networking configuration files, so that it will be in place regardless of reboots or network restarts. This is called a persistent route. ===Manipulating non-persistent routes=== From the days of yore, the venerable ''route'' command enables us to view, add, change and delete routes. Its most known use is for printing the current routing table: #route -n Kernel IP routing table Destination Gateway Genmask Flags Metric Ref Use Iface 192.168.70.0 212.214.172.50 255.255.255.0 UG 0 0 0 eth1 192.168.67.0 * 255.255.255.0 U 0 0 0 eth0 212.214.172.0 * 255.255.255.0 U 0 0 0 eth1 default 212.214.172.1 0.0.0.0 UG 0 0 0 eth1 The addition of -n makes sure the ''route'' command does not try to substitute DNS names for IP addresses it knows. The second most used incarnation of ''route'' lies in the addition of a route, as has happened in the previous example. The route was added to the routing table using something like this: #route add -net 192.168.70.0 netmask 255.255.255.0 gw 212.214.172.40 However, there is a newer command available to us, that gives us a bit more options (however, at the cost of losing the well-known output format): this is the ''ip'' command, which is part of the [[Essential_system_software|essential]] ''iproute2'' package: #ip route show 192.168.70.0/24 via 212.214.172.50 dev eth1 src 192.168.67.10 192.168.67.0/24 dev eth0 proto kernel scope link src 192.168.67.10 212.214.172.0/24 dev eth1 proto kernel scope link src 212.214.172.50 default via 212.214.172.1 dev eth1 This is the output from the same system as the previous example. However, we see something interesting here: "ip" is capable of adding extra information to the route, like the first line shows (it's using "via"). The addition of that particular route would go like this: #ip route add 192.168.70.0/24 via 212.214.172.50 src 192.168.67.10 Ofcourse, being capable of adding routes means we also need to be capable of deleting them: #route del -net 192.168.70.0 netmask 255.255.255.0 #ip route del 192.168.70.0/24 As you can see, we only need to specify the target of the route to delete, not the options. ===Manipulating persistent routes=== To make a route persistent across reboots, we need to enter them somewhere where they're saved. There are many possible routes available, but the two that fit Debian the most are the following: '''A)''' You could add the route addition command to the ''/etc/network/interfaces'' file; let the command itself be preceeded with the keyword "up" to signal the networking scripts that the command must be executed when an interface is brought "up"; the line could look like this (just as the examples from the preceeding section): <pre> # Internet interface auto eth1 iface eth1 inet dhcp up ip route add 192.168.70.0/24 via 212.214.172.50 src 192.168.67.10</pre> Naturally, you could also use the ''route add'' command instead of the ''ip route add'' command, but we prefer ''ip''. Note: it matters --where-- in the ''interfaces'' file you put this line: it should be put in the same stanza as the interface it operates on. In this example, the external interface of the server is 212.214.172.50, which belongs with interface ''eth1''. Therefore, the "up" line appears in the stanza for ''eth1''. '''B)''' You could create a script that sets the route(s), and put it in the directory ''/etc/network/if-up.d''. Since all scripts that reside there get called when any interface goes "up", your route setting script would be called when ''any'' interface comes up, including ''lo''. This in turn means that a script for setting a route that belongs with a particular interface, should check on invocation which is the interface that goes up. At this moment in time, we don't employ any such script, so no example here, but if you look at the existing scripts in ''/etc/network/if-up.d'' you'll see how other programmers have done this. ==DNS resolution under Debian== One headache you might encounter when configuring a Debian server is how to let every program know how to resolve DNS names. Before a program can connect to an external network resource (say, for example, a web server), it must have a means of converting DNS names (e.g. www.saruman.biz) into the corresponding IP addresses (e.g. 192.168.67.10). This process is called "name resolution". The need for name resolution means that every program needs to know about the available means by which to do this name resolution. From the good old days comes the configuration file ''resolv.conf'', normally found in ''/etc''. It contains information about the nameservers to be used by the system, be they actual servers or lookup files. However, more and more programs have the need to dynamically modify the ''resolv.conf'' configuration file. This means that frequently they step on each other, and the ''resolv.conf'' file can become out-of-sync. The ''resolvconf'' program addresses this problem. It acts as an intermediary between programs that supply nameserver information (e.g. DHCP clients) and programs that use nameserver information (e.g. resolver). When ''resolvconf'' is properly installed, the file ''/etc/resolv.conf'' is replaced by a symbolic link to ''/etc/resolvconf/run/resolv.conf'', and any resolver thus uses the dynamically generated resolver configuration file at ''/etc/resolvconf/run/resolv.conf''. The ''resolvconf'' program is only necessary when a system has multiple programs that need to dynamically modify the nameserver information. In a simple system where the nameservers do not change often or are only changed by one program, the standard ''/etc/resolv.conf'' configuration file is adequate. == VLANs under Debian == Debian can support network traffic over VLANs (ethernet 802.1q) - and we don't mean the normal "untagged" network ports (hey, VLANs are transparent that way, anybody and anything can use untagged network ports). No, we mean that Debian can accept network traffic in from, and send traffic out to, a VLAN tagged switchport. Suppose you have a layer 2 switch with support for 802.1q VLANs, and want to route traffic from one VLAN to another. For this you can use a Debian router with a single network interface, using VLAN support (this is called "router on a stick" because the routing takes place over only one cable). First, as root, run apt-get install vlan modprobe 8021q The first line is to install the vlan package, which contains all necessary tools to create and manipulate VLAN-enabled network ports. The second line loads the module that enables VLAN tagging for your ethernet network cards. Note: if you don't have the stock Debian kernel, but compiled your own, then you might have chosen not to compile the 8021q module. In that case, compile the module. Also note, that if you've compiled the 8021q code into the kernel itself, then you don't need to load the module and that second line is unnecessary for you. You'll find this kernel compile option (depending on your kernel version) under Networking -> Networking Options -> "802.1Q VLAN Support". This option has been in the Linux kernel since version 2.4.14. ifconfig eth0 down vconfig add eth0 2 vconfig add eth0 3 The first command brings down your network on eth0 (not the thing to do if you're working remote, then :-). The next two commands create two virtual interfaces ''eth0.2'' and ''eth0.3'', which have VLAN tags 2 and 3 (don't use VLAN tag 1 if you can help it; on many devices VLAN1 is a special hardware management VLAN). The virtual interfaces run on top of your ''eth0'' interface.<br> Now because your VLAN interfaces run on top of ''eth0'', you've got to bring ''eth0'' itself up, even if you don't want to run network traffic over it. Furthermore, you've got to configure the two virtual interfaces you've created. Let's suppose you want to run IP subnet 192.168.1.0/24 on VLAN2, and 192.168.2.0/24 on VLAN3. You can do so with ifconfig eth0 0.0.0.0 up ifconfig eth0.2 192.168.1.1 broadcast 192.168.1.255 netmask 255.255.255.0 up ifconfig eth0.3 192.168.2.1 broadcast 192.168.2.255 netmask 255.255.255.0 up Now that you've this done, you must still configure one of your switch ports to belong to VLAN 2 and 3 at the same time (tagged port), and connect ''eth0'' from your linux box to that port. This enables your box to run network traffic on both VLANs. To round things up: if you haven't yet enabled forwarding, you can do so now. Furthermore, you might wish to augment your route table so that the routing engine in your server knows how to handle packets that it needs to forward from one VLAN to the other: echo 1 > /proc/sys/net/ipv4/ip_forward route add -net 10.1.1.0 netmask 255.255.255.0 gw eth0.2 route add -net 10.1.2.0 netmask 255.255.255.0 gw eth0.3 This is it; nothing to it, right? =Tunneling under Debian= Being a Linux distribution, Debian gives you all the networking power of that platform. One of the powerful features of Linux networking is the ease with which you can create network tunnels. Many possibilities exist; in this wiki we've documented the following: * [[IPsec site-to-site tunnel]] with which you can connect two networks, so that machines in both networks can reach machines in the other network fbb1f6124f455aaf51277de1963ac0019da1741f 2372 2342 2009-02-12T20:56:23Z 83.233.30.77 0 /* Routes under Debian */ wikitext text/x-wiki http://hyves.mn/dsee/bee-pollen.html bee pollen http://hyves.mn/dsee/bee-brooch.html bee brooch http://hyves.mn/dsee/bedwetting-diapers.html bedwetting diapers http://hyves.mn/dsee/bedroom-furniture-stores.html bedroom furniture stores http://hyves.mn/dsee/bedroom-furniture-store.html bedroom furniture store http://hyves.mn/dsee/bedroom-furniture-set.html bedroom furniture set http://hyves.mn/dsee/bedroom-furniture-sale.html bedroom furniture sale http://hyves.mn/dsee/bedroom-furniture-modern.html bedroom furniture modern http://hyves.mn/dsee/bedroom-furniture-contemporary.html bedroom furniture contemporary http://hyves.mn/dsee/bedding-ralph-lauren.html bedding ralph lauren http://hyves.mn/dsee/bed-sizes.html bed sizes http://hyves.mn/dsee/bed-frame.html bed frame http://hyves.mn/dsee/bed-bath-beyond-wedding-registry.html bed bath beyond wedding registry http://hyves.mn/dsee/bed.html bed http://hyves.mn/dsee/becks-beer.html becks beer http://hyves.mn/dsee/beckman.html beckman http://hyves.mn/dsee/because-i-got-high.html because i got high http://hyves.mn/dsee/bebo-layouts.html bebo layouts http://hyves.mn/dsee/beaverhunt.html beaverhunt http://hyves.mn/dsee/beauty-tips.html beauty tips ==DNS resolution under Debian== One headache you might encounter when configuring a Debian server is how to let every program know how to resolve DNS names. Before a program can connect to an external network resource (say, for example, a web server), it must have a means of converting DNS names (e.g. www.saruman.biz) into the corresponding IP addresses (e.g. 192.168.67.10). This process is called "name resolution". The need for name resolution means that every program needs to know about the available means by which to do this name resolution. From the good old days comes the configuration file ''resolv.conf'', normally found in ''/etc''. It contains information about the nameservers to be used by the system, be they actual servers or lookup files. However, more and more programs have the need to dynamically modify the ''resolv.conf'' configuration file. This means that frequently they step on each other, and the ''resolv.conf'' file can become out-of-sync. The ''resolvconf'' program addresses this problem. It acts as an intermediary between programs that supply nameserver information (e.g. DHCP clients) and programs that use nameserver information (e.g. resolver). When ''resolvconf'' is properly installed, the file ''/etc/resolv.conf'' is replaced by a symbolic link to ''/etc/resolvconf/run/resolv.conf'', and any resolver thus uses the dynamically generated resolver configuration file at ''/etc/resolvconf/run/resolv.conf''. The ''resolvconf'' program is only necessary when a system has multiple programs that need to dynamically modify the nameserver information. In a simple system where the nameservers do not change often or are only changed by one program, the standard ''/etc/resolv.conf'' configuration file is adequate. == VLANs under Debian == Debian can support network traffic over VLANs (ethernet 802.1q) - and we don't mean the normal "untagged" network ports (hey, VLANs are transparent that way, anybody and anything can use untagged network ports). No, we mean that Debian can accept network traffic in from, and send traffic out to, a VLAN tagged switchport. Suppose you have a layer 2 switch with support for 802.1q VLANs, and want to route traffic from one VLAN to another. For this you can use a Debian router with a single network interface, using VLAN support (this is called "router on a stick" because the routing takes place over only one cable). First, as root, run apt-get install vlan modprobe 8021q The first line is to install the vlan package, which contains all necessary tools to create and manipulate VLAN-enabled network ports. The second line loads the module that enables VLAN tagging for your ethernet network cards. Note: if you don't have the stock Debian kernel, but compiled your own, then you might have chosen not to compile the 8021q module. In that case, compile the module. Also note, that if you've compiled the 8021q code into the kernel itself, then you don't need to load the module and that second line is unnecessary for you. You'll find this kernel compile option (depending on your kernel version) under Networking -> Networking Options -> "802.1Q VLAN Support". This option has been in the Linux kernel since version 2.4.14. ifconfig eth0 down vconfig add eth0 2 vconfig add eth0 3 The first command brings down your network on eth0 (not the thing to do if you're working remote, then :-). The next two commands create two virtual interfaces ''eth0.2'' and ''eth0.3'', which have VLAN tags 2 and 3 (don't use VLAN tag 1 if you can help it; on many devices VLAN1 is a special hardware management VLAN). The virtual interfaces run on top of your ''eth0'' interface.<br> Now because your VLAN interfaces run on top of ''eth0'', you've got to bring ''eth0'' itself up, even if you don't want to run network traffic over it. Furthermore, you've got to configure the two virtual interfaces you've created. Let's suppose you want to run IP subnet 192.168.1.0/24 on VLAN2, and 192.168.2.0/24 on VLAN3. You can do so with ifconfig eth0 0.0.0.0 up ifconfig eth0.2 192.168.1.1 broadcast 192.168.1.255 netmask 255.255.255.0 up ifconfig eth0.3 192.168.2.1 broadcast 192.168.2.255 netmask 255.255.255.0 up Now that you've this done, you must still configure one of your switch ports to belong to VLAN 2 and 3 at the same time (tagged port), and connect ''eth0'' from your linux box to that port. This enables your box to run network traffic on both VLANs. To round things up: if you haven't yet enabled forwarding, you can do so now. Furthermore, you might wish to augment your route table so that the routing engine in your server knows how to handle packets that it needs to forward from one VLAN to the other: echo 1 > /proc/sys/net/ipv4/ip_forward route add -net 10.1.1.0 netmask 255.255.255.0 gw eth0.2 route add -net 10.1.2.0 netmask 255.255.255.0 gw eth0.3 This is it; nothing to it, right? =Tunneling under Debian= Being a Linux distribution, Debian gives you all the networking power of that platform. One of the powerful features of Linux networking is the ease with which you can create network tunnels. Many possibilities exist; in this wiki we've documented the following: * [[IPsec site-to-site tunnel]] with which you can connect two networks, so that machines in both networks can reach machines in the other network 2b82ce144caa49f76cdc33e49d90e70d64bf6958 2373 2372 2009-02-12T21:06:44Z Saruman! 2 Reverted edits by [[Special:Contributions/83.233.30.77|83.233.30.77]] ([[User talk:83.233.30.77|Talk]]); changed back to last version by [[User:Saruman!|Saruman!]] wikitext text/x-wiki ==Routes under Debian== When you need to add a networking route, there generally are two ways to do it: # manually adding a route at the command prompt: this means that the machine will "understand" the route for as long as it is running. However, when you reboot the machine, it will have "forgotten" the route. This is called a non-persistent route. # adding a route to the networking configuration files, so that it will be in place regardless of reboots or network restarts. This is called a persistent route. ===Manipulating non-persistent routes=== From the days of yore, the venerable ''route'' command enables us to view, add, change and delete routes. Its most known use is for printing the current routing table: #route -n Kernel IP routing table Destination Gateway Genmask Flags Metric Ref Use Iface 192.168.70.0 212.214.172.50 255.255.255.0 UG 0 0 0 eth1 192.168.67.0 * 255.255.255.0 U 0 0 0 eth0 212.214.172.0 * 255.255.255.0 U 0 0 0 eth1 default 212.214.172.1 0.0.0.0 UG 0 0 0 eth1 The addition of -n makes sure the ''route'' command does not try to substitute DNS names for IP addresses it knows. The second most used incarnation of ''route'' lies in the addition of a route, as has happened in the previous example. The route was added to the routing table using something like this: #route add -net 192.168.70.0 netmask 255.255.255.0 gw 212.214.172.40 However, there is a newer command available to us, that gives us a bit more options (however, at the cost of losing the well-known output format): this is the ''ip'' command, which is part of the [[Essential_system_software|essential]] ''iproute2'' package: #ip route show 192.168.70.0/24 via 212.214.172.50 dev eth1 src 192.168.67.10 192.168.67.0/24 dev eth0 proto kernel scope link src 192.168.67.10 212.214.172.0/24 dev eth1 proto kernel scope link src 212.214.172.50 default via 212.214.172.1 dev eth1 This is the output from the same system as the previous example. However, we see something interesting here: "ip" is capable of adding extra information to the route, like the first line shows (it's using "via"). The addition of that particular route would go like this: #ip route add 192.168.70.0/24 via 212.214.172.50 src 192.168.67.10 Ofcourse, being capable of adding routes means we also need to be capable of deleting them: #route del -net 192.168.70.0 netmask 255.255.255.0 #ip route del 192.168.70.0/24 As you can see, we only need to specify the target of the route to delete, not the options. ===Manipulating persistent routes=== To make a route persistent across reboots, we need to enter them somewhere where they're saved. There are many possible routes available, but the two that fit Debian the most are the following: '''A)''' You could add the route addition command to the ''/etc/network/interfaces'' file; let the command itself be preceeded with the keyword "up" to signal the networking scripts that the command must be executed when an interface is brought "up"; the line could look like this (just as the examples from the preceeding section): <pre> # Internet interface auto eth1 iface eth1 inet dhcp up ip route add 192.168.70.0/24 via 212.214.172.50 src 192.168.67.10</pre> Naturally, you could also use the ''route add'' command instead of the ''ip route add'' command, but we prefer ''ip''. Note: it matters --where-- in the ''interfaces'' file you put this line: it should be put in the same stanza as the interface it operates on. In this example, the external interface of the server is 212.214.172.50, which belongs with interface ''eth1''. Therefore, the "up" line appears in the stanza for ''eth1''. '''B)''' You could create a script that sets the route(s), and put it in the directory ''/etc/network/if-up.d''. Since all scripts that reside there get called when any interface goes "up", your route setting script would be called when ''any'' interface comes up, including ''lo''. This in turn means that a script for setting a route that belongs with a particular interface, should check on invocation which is the interface that goes up. At this moment in time, we don't employ any such script, so no example here, but if you look at the existing scripts in ''/etc/network/if-up.d'' you'll see how other programmers have done this. ==DNS resolution under Debian== One headache you might encounter when configuring a Debian server is how to let every program know how to resolve DNS names. Before a program can connect to an external network resource (say, for example, a web server), it must have a means of converting DNS names (e.g. www.saruman.biz) into the corresponding IP addresses (e.g. 192.168.67.10). This process is called "name resolution". The need for name resolution means that every program needs to know about the available means by which to do this name resolution. From the good old days comes the configuration file ''resolv.conf'', normally found in ''/etc''. It contains information about the nameservers to be used by the system, be they actual servers or lookup files. However, more and more programs have the need to dynamically modify the ''resolv.conf'' configuration file. This means that frequently they step on each other, and the ''resolv.conf'' file can become out-of-sync. The ''resolvconf'' program addresses this problem. It acts as an intermediary between programs that supply nameserver information (e.g. DHCP clients) and programs that use nameserver information (e.g. resolver). When ''resolvconf'' is properly installed, the file ''/etc/resolv.conf'' is replaced by a symbolic link to ''/etc/resolvconf/run/resolv.conf'', and any resolver thus uses the dynamically generated resolver configuration file at ''/etc/resolvconf/run/resolv.conf''. The ''resolvconf'' program is only necessary when a system has multiple programs that need to dynamically modify the nameserver information. In a simple system where the nameservers do not change often or are only changed by one program, the standard ''/etc/resolv.conf'' configuration file is adequate. == VLANs under Debian == Debian can support network traffic over VLANs (ethernet 802.1q) - and we don't mean the normal "untagged" network ports (hey, VLANs are transparent that way, anybody and anything can use untagged network ports). No, we mean that Debian can accept network traffic in from, and send traffic out to, a VLAN tagged switchport. Suppose you have a layer 2 switch with support for 802.1q VLANs, and want to route traffic from one VLAN to another. For this you can use a Debian router with a single network interface, using VLAN support (this is called "router on a stick" because the routing takes place over only one cable). First, as root, run apt-get install vlan modprobe 8021q The first line is to install the vlan package, which contains all necessary tools to create and manipulate VLAN-enabled network ports. The second line loads the module that enables VLAN tagging for your ethernet network cards. Note: if you don't have the stock Debian kernel, but compiled your own, then you might have chosen not to compile the 8021q module. In that case, compile the module. Also note, that if you've compiled the 8021q code into the kernel itself, then you don't need to load the module and that second line is unnecessary for you. You'll find this kernel compile option (depending on your kernel version) under Networking -> Networking Options -> "802.1Q VLAN Support". This option has been in the Linux kernel since version 2.4.14. ifconfig eth0 down vconfig add eth0 2 vconfig add eth0 3 The first command brings down your network on eth0 (not the thing to do if you're working remote, then :-). The next two commands create two virtual interfaces ''eth0.2'' and ''eth0.3'', which have VLAN tags 2 and 3 (don't use VLAN tag 1 if you can help it; on many devices VLAN1 is a special hardware management VLAN). The virtual interfaces run on top of your ''eth0'' interface.<br> Now because your VLAN interfaces run on top of ''eth0'', you've got to bring ''eth0'' itself up, even if you don't want to run network traffic over it. Furthermore, you've got to configure the two virtual interfaces you've created. Let's suppose you want to run IP subnet 192.168.1.0/24 on VLAN2, and 192.168.2.0/24 on VLAN3. You can do so with ifconfig eth0 0.0.0.0 up ifconfig eth0.2 192.168.1.1 broadcast 192.168.1.255 netmask 255.255.255.0 up ifconfig eth0.3 192.168.2.1 broadcast 192.168.2.255 netmask 255.255.255.0 up Now that you've this done, you must still configure one of your switch ports to belong to VLAN 2 and 3 at the same time (tagged port), and connect ''eth0'' from your linux box to that port. This enables your box to run network traffic on both VLANs. To round things up: if you haven't yet enabled forwarding, you can do so now. Furthermore, you might wish to augment your route table so that the routing engine in your server knows how to handle packets that it needs to forward from one VLAN to the other: echo 1 > /proc/sys/net/ipv4/ip_forward route add -net 10.1.1.0 netmask 255.255.255.0 gw eth0.2 route add -net 10.1.2.0 netmask 255.255.255.0 gw eth0.3 This is it; nothing to it, right? =Tunneling under Debian= Being a Linux distribution, Debian gives you all the networking power of that platform. One of the powerful features of Linux networking is the ease with which you can create network tunnels. Many possibilities exist; in this wiki we've documented the following: * [[IPsec site-to-site tunnel]] with which you can connect two networks, so that machines in both networks can reach machines in the other network fbb1f6124f455aaf51277de1963ac0019da1741f 0 1487 2364 1937 2009-02-12T19:16:32Z Saruman! 2 /* Editing the CA.sh script */ used GeSHi wikitext text/x-wiki ==Certificates, an introduction== Digital certificates are an extremely important means to identify identities (of users, as well as of servers) on the Internet, or indeed on most any network. For instance, we use them to encrypt network traffic when we use the HTTPS protocol. Thus, we really need certificates. Now, as [http://www.debian-administration.org/articles/618 this article] explains, you can either buy your certificates from a certificate authority like [http://www.verisign.com/ VeriSign], [http://www.thawte.com/ Thawte] or [http://www.equifaxsecure.co.uk/index.html Equifax Secure], but these certificates cost more than a couple of Euro's, and also need to be renewed (usually every year). So the other route, the one we'll be taking, is to create our own Certificate Authority (CA), and use that to sign certificates for our needs (secure webserver, secure mailserver etcetera). Now, "creating a CA" sounds like grave installation and configuration work, but in fact a CA does not have to be an actual service, demon or program. A CA is more like a concept, at the heart of which lies the CA "root certificate". So if we obtain a little set of tools and generate our own root certificate, then we're in business. ==Creating the Certificate Authority (CA) - preparations== To generate the root CA for our own little organization, we first need tools. These tools under Debian come with the OpenSSL software - which you'll usually find already installed. Now to generate the CA root certificate, we'll use a shell script from the OpenSSL package: ''/usr/lib/ssl/misc/CA.sh'', which together with the configuration file ''/etc/ssl/openssl.cnf'' can create our CA root certificate. To that end, we'll first need to decide on some parameters. ===Deciding on CA parameters=== '''How strong''' do we want our root certificate? 1024 bits is the default, but the stronger, the better. We suggest 2048 bits. How long should our '''CA root certificate remain valid'''? The longer, the more convenient - but maybe some day in the future, you feel you don't want certificates from ten years earlies to wander around, expired but otherwise valid. Expiry of the root certificate that goes along with that certificate might help you. So what's an appropriate time for your root CA? That depends. For our home CA, we use 15 years. For a business, the cost of providing new root certificates to all computers, employees, and maybe customers, can be so high that you'd rather have 25 years - or maybe security is paramount, and 5 years is long enough for you. We can't say - but our home CA's use 15 years, because we feel that that's a nice intermediate value. 15 years, including about 4 leap days, comes to 5479 days. '''Where do we want to store''' our CA root certificate? By default, the ''CA.sh'' script feels it must store all generated certificates in ''./demoCA''. That's not very handy for us. We rather have a central location like ''/etc/ssl/ca'' on our central server. How long should '''any generated certificate be valid'''? The default value that the ''CA.sh'' script provides is one year. We find that enough - although we add 7 days to accomodate some overlap when having to regenerate the certificate upon nearing the expiry date (note: we really want to replace certificates ''prior'' to expiry :-) '''What "company" data''' will we enter in the certificate? Several fields must be entered, some of which you could fill out at will. However, it's not exactly clear why you would want to confuse people trying to authenticate you, your webserver or some other connection by filling out, for example, the country with an incorrect or even non-existent code. On the other hand, you can keep your own privacy in mind, and not fill in your full name, but rather your website's name, at the "common name" section of your CA root certificate. Again, this depends on what you're going to use your CA for. We at [https://www.saruman.biz saruman.biz] decided to use the following values: * Organization name: Saruman.biz. We're private persons, not companies, but we want to maintain a minimum of privacy, so we've put this fake entity name here. * Province: Utrecht. Yep, that's a province in the Netherlands, and we live pretty close to it. * Country: NL (that's the Netherlands) Maybe you want to provide more default information to your CA setup; just look further down on how to. So the information we've decided upon is like this: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Parameter !style="background:#ffdead;"|value |- |root certificate encryption |2048 bits |- |root certificate validity |5479 days (15 years) |- |certificate store |''/etc/ssl/ca'' |- |default certificate validity |370 days (1 year) |- |Organization name |Saruman.biz |- |Certificate province/county name (default) |Utrecht |- |Certificate country name (default) |NL |- |} === Editing the ''CA.sh'' script === Actually, you don't need to use the ''CA.sh'' shell script. There's also a ''CA.pl'' perl script. However, if you're more into shell scripting than perl programming, go for the shell script. Now edit ''/usr/lib/ssl/misc/CA.sh''; find the two lines near the top that define the variables ''DAYS'' and ''CADAYS'', and set these to what we want them to be. A little further down, we find the default location ''CATOP=./demoCA''. Change this (relative) path to the (absolute) path we've decided upon. Then, a lot further down, we find the line that's responsible for creating the CA root certificate itself, it's the line that goes ''$REQ -new -keyout ${CATOP}/private/$CAKEY -out ${CATOP}/$CAREQ'' (well actually it's split out over two lines). Here, right after ''-new'' we add ''-newkey rsa:2048''. With all these changes, the three relevant sections in ''CA.sh'' will be changed to something like this: <source lang="bash"> DAYS="-days 370" # 1 year CADAYS="-days 5479" # 15 years ... CATOP=/etc/ssl/ca ... echo "Making CA certificate ..." $REQ -new -newkey rsa:2048 -keyout ${CATOP}/private/$CAKEY \ -out ${CATOP}/$CAREQ </source> === Editing the ''openssl.cnf'' configuration file=== When generating certificates, the OpenSSL tools check the configuration file ''/etc/ssl/openssl.cnf''. It is necessary to match the parameters in there with the choices and changes of the previous sections, and also it's handy to change some of the default parameters that certificates require upon generation. It's important to remember that these parameters will be asked every time you generate a certificate, but it's ofcourse pretty handy if the default value is set for your situation, so you can just hit that big &lt;enter> key. First up, we'll change the ''dir'' variable in section ''[ CA_default ]'' to match the dir from the ''CA.sh'' script. Then we find ''default_days'' and change it to our default certificate lifetime: 370 days. Furthermore, we find the certificate strengt in the ''[ req ]'' section; we can change it to our preferred value of 2048 bits. Now we can put in the optional bits: the default values. Not necessary, but handy. We go to section ''[ req_distinguished_name ]'' and fill them in. For this, we again use the table we've previously compounded. So the changes we've made will amount to something like this: [ CA_default ] dir = /etc/ssl/ca ... default_days = 370 ... [ req ] default_bits = 2048 ... [ req_distinguished_name ] 0.organizationName_default = Saruman.biz stateOrProvinceName_default = Utrecht countryName_default = NL Especially the last section is, again, a pretty arbitrary choice. You could choose not to provide customized default answers (in which case you're stuck with Internet Widgets Pty from Some-State, AU as the default answers). There are more default values in that section of the ''openssl.cnf'' configuration file; go in there and decide what you want. ==the Certificate Authority root certificate== Now with the basic information in place, we can go about generating the certificate itself, and putting it to use. Well, actually we're not going to generate ''one'' certificate, but ''two'': the public one, that we give out to anyone that might want to check the validity of any certificate that claims to have been issued by the Saruman.biz CA, and the private one, with which we can digitally sign certificates so as to prove that they're really issued by said Saruman.biz CA. This is also referred to as a "key pair". ===Creating the CA root certificate key pair=== To generate the CA's public and private root certificate, as root, execute /usr/lib/ssl/misc/CA.sh -newca With the defaults set as given above, you still get some questions. One is "CA certificate filename". This actually requests from you another certificate with which to sign the one we're creating. However, we're generating our root certificate, so we leave this empty and just hit &lt;enter>. Next question is for the PEM passphrase. Make that a strong passphrase or password, keep it very secret, and '''don't forget it!''' (and DON'T write it on a piece of paper; use something like [http://keepass.info keepass] to store your secret passwords). For the next set of questions, you probably have filled in some of the defaults. If you want to leave some entry blank, fill in a period ('''.'''). You'll have to provide the country code, province or state, locality (like city; Saruman.biz leaves this empty), Organization Name, Organizational Unit name (again, empty), and finally the Common Name. This last question is pretty important: the name you put in here is the name under which your CA will go for the next 15 years!! So don't put in a "funny" name, a bland name, or whatever. We put in "Saruman.biz Root CA", somewhat like official root CA's like "Equifax Secure Global eBusiness CA-1" or "Macao Post eSignTrust Root Certification Authority". The script also asks for an email address, which you may or may not provide, a challenge password, and an "optional company name", both of which you can leave blank because we're not sending a certificate signing request out to someone else, but signing it ourselves.<br> Having provided this information, we've actually already created one half of the key pair, namely the private key. It'll be ''/etc/openssl/ca/private/ca.pem'', and is protected by our chosen very strong password. However, we now need the public key, self-signed with the private key. The next step in our CA creation process thus ''again'' asks for the passphrase. Since this is the second step in a two-step process, we again put in the passphrase we've already provided. However, now the shellscript uses this to unlock the private key we've (already) created, and then use it to sign the public key we're now creating. However, the passphrase is ''all'' that it asks. It now generates a signing request (''/etc/openssl/ca/careq.pem''), then uses the private key to sign it, and then generate the public key, to be found in ''/etc/openssl/ca/cacert.pem''. You can remove ''careq.pem'' after you've inspected the ''cacert.pem''. So now we've got two root certificates, namely '''private''' key ''/etc/openssl/ca/private/cakey.pem'' and '''public''' key ''/etc/openssl/ca/cacert.pem''. NEVER send your public key out to ANYONE! Protect that key, and its passphrase, with your life. If you lose the file, lose the passphrase, or the key gets compromised (lost to an unknown party) then you've got to replace your root certificates AND you'll have to re-issue ALL certificates that you've ever signed (we're not going into certificate revocation here). You can inspect your certificates (when you're in directory ''/etc/openssl/ca'') with commands like this: openssl x509 -in cacert.pem -noout -text openssl x509 -in cacert.pem -noout -dates openssl x509 -in cacert.pem -noout -purpose Note from the last command that this certificate is obviously a root certificate: it can sign everything but the kitchen sink. ===We've got the CA certificate, now what?=== With the root CA certificates available to us, we've got two things to do: * guard very carefully the public and (especially) the private key file * sign certificates for our own use The first means we've got to keep a copy of the private key file in some other, safe location, and we've got to secure the private key on the server where it sits - both the machine and the file. It might even be wise to remove the private key, and keep it on a USB stick, and only read it when signing certificates. The second thing means we've got to generate keys for SSL and TLS connections, just as we need them. This is covered in our [[Creating digital certificates with our root certificate | creating digital certificates]] section. 36ccbe73ccd76aa8166f82d1013eef17b5348bce 0 1490 2365 1973 2009-02-12T19:40:36Z Saruman! 2 added GeSHi wikitext text/x-wiki <source lang="mysql"> USE mysql; REPLACE INTO user (host, user, password) VALUES ( 'localhost', 'vmail_admin', PASSWORD('SuperSecret') ); REPLACE INTO db (host, db, user, select_priv) VALUES ( 'localhost', 'vmail', 'vmail_admin', 'Y' ); -- Make sure that priviliges are reloaded. FLUSH PRIVILEGES; -- You should drop a pre-existing "vmail" -- database manually to avoid CREATE errors. CREATE DATABASE vmail; USE vmail; CREATE TABLE virtual_domains ( id INT NOT NULL AUTO_INCREMENT PRIMARY KEY, vdomain VARCHAR(50) NOT NULL ) ENGINE = InnoDB; CREATE TABLE relaydomains ( id INT NOT NULL AUTO_INCREMENT PRIMARY KEY, relaydomain VARCHAR(80) NOT NULL, transport VARCHAR(80) NOT NULL ) ENGINE = InnoDB; CREATE TABLE virtual_users ( id INT(11) NOT NULL AUTO_INCREMENT PRIMARY KEY, domain_id INT(11) NOT NULL, user VARCHAR(40) NOT NULL, passwd VARCHAR(32) NOT NULL ) ENGINE = InnoDB; CREATE TABLE virtual_aliases ( id INT(11) NOT NULL AUTO_INCREMENT PRIMARY KEY, domain_id INT(11) NOT NULL, source VARCHAR(80) NOT NULL, destination VARCHAR(80) NOT NULL, FOREIGN KEY (domain_id) REFERENCES virtual_domains(id) ON DELETE CASCADE ) ENGINE = InnoDB; FLUSH PRIVILEGES; CREATE VIEW view_users AS SELECT CONCAT(virtual_users.user, '@', virtual_domains.vdomain) AS email, virtual_users.passwd FROM virtual_users LEFT JOIN virtual_domains ON virtual_users.domain_id=virtual_domains.id; CREATE VIEW view_aliases AS SELECT CONCAT(virtual_aliases.source, '@', virtual_domains.vdomain) AS email, destination FROM virtual_aliases LEFT JOIN virtual_domains ON virtual_aliases.domain_id=virtual_domains.id; </source> Using this script to create the ''vmail'' database should result in the following database (log into ''mysql'' as a root user, and type the commands shown after ''mysql>'' to check): mysql> show databases; +--------------------+ | Database | +--------------------+ | information_schema | | mysql | | vmail | +--------------------+ 3 rows in set mysql> use vmail; Database changed mysql> show tables; +-----------------+ | Tables_in_vmail | +-----------------+ | relaydomains | | view_aliases | | view_users | | virtual_aliases | | virtual_domains | | virtual_users | +-----------------+ 6 rows in set mysql> describe relaydomains; +-------------+-------------+------+-----+---------+----------------+ | Field | Type | Null | Key | Default | Extra | +-------------+-------------+------+-----+---------+----------------+ | id | int(11) | NO | PRI | NULL | auto_increment | | relaydomain | varchar(80) | NO | | NULL | | | transport | varchar(80) | NO | | NULL | | +-------------+-------------+------+-----+---------+----------------+ 3 rows in set mysql> describe view_aliases; +-------------+--------------+------+-----+---------+-------+ | Field | Type | Null | Key | Default | Extra | +-------------+--------------+------+-----+---------+-------+ | email | varchar(131) | YES | | NULL | | | destination | varchar(80) | NO | | NULL | | +-------------+--------------+------+-----+---------+-------+ 2 rows in set mysql> describe view_users; +--------+-------------+------+-----+---------+-------+ | Field | Type | Null | Key | Default | Extra | +--------+-------------+------+-----+---------+-------+ | email | varchar(91) | YES | | NULL | | | passwd | varchar(32) | NO | | NULL | | +--------+-------------+------+-----+---------+-------+ 2 rows in set mysql> describe virtual_aliases; +-------------+-------------+------+-----+---------+----------------+ | Field | Type | Null | Key | Default | Extra | +-------------+-------------+------+-----+---------+----------------+ | id | int(11) | NO | PRI | NULL | auto_increment | | domain_id | int(11) | NO | MUL | NULL | | | source | varchar(80) | NO | | NULL | | | destination | varchar(80) | NO | | NULL | | +-------------+-------------+------+-----+---------+----------------+ 4 rows in set mysql> describe virtual_domains; +---------+-------------+------+-----+---------+----------------+ | Field | Type | Null | Key | Default | Extra | +---------+-------------+------+-----+---------+----------------+ | id | int(11) | NO | PRI | NULL | auto_increment | | vdomain | varchar(50) | NO | | NULL | | +---------+-------------+------+-----+---------+----------------+ 2 rows in set mysql> describe virtual_users; +-----------+-------------+------+-----+---------+----------------+ | Field | Type | Null | Key | Default | Extra | +-----------+-------------+------+-----+---------+----------------+ | id | int(11) | NO | PRI | NULL | auto_increment | | domain_id | int(11) | NO | | NULL | | | user | varchar(40) | NO | | NULL | | | passwd | varchar(32) | NO | | NULL | | +-----------+-------------+------+-----+---------+----------------+ 4 rows in set 4acb5917e8545de1f909971b0eb4b206d7be870c 0 1532 2366 2207 2009-02-12T19:54:49Z Saruman! 2 [[MediaWikiExtension GroupPermissionsManager]] moved to [[MediaWiki Extension - GroupPermissionsManager]]: nicer name wikitext text/x-wiki ==Mediawiki Extension: Group Permissions Manager== Sometimes you as a Mediawiki administrator might feel the need to add or remove a group, or edit a groups rights. Unfortunately, there is no such function in the MediaWiki software itself, you'd have to edit the ''LocalSettings.php'' file somehow. [http://www.imdb.com/title/tt0096928/ Bogus!] But fortunately, there now exists an extension that adds this functionality. [http://www.imdb.com/title/tt0096928/ Most excellent!] Note: if you want to install the older version 2.00 of this plugin (which is much simpler, both in installation and in functionality), then go to the [[MediaWikiExtension GroupPermissionsManager2.00| Group Permissions Manager 2.00]] page. The instructions on this page are for the 3.2.6 version (build r45886). ==Adding the extension== First, download the latest snapshot of the GroupPermissionsManager extension from here: [http://www.mediawiki.org/wiki/Extension:GroupPermissionsManager Mediawiki Extension:Group Permissions Manager]. It's a single archive with a name that looks like ''GroupPermissionsManager-trunk-r45886.tar.gz''. You'll best extract it in some temporary place (e.g. ''/tmp''); out comes a little directory structure like this: GroupPermissionsManager |-- plugins | |-- disabled | `-- messages `-- scripts You'll have to make sure all files and directories are owned by root, and that the PHP files cannot be edited by anyone else than root. As root: cd /tmp/GroupPermissionsManager chown -R root:root * chmod -R 644 *.php Next, contrary to the instructions on the extension's homepage, all files and directories under the ''GroupPermissionsManager'' directory are to be placed directly in the extension directory of your Debian MediaWiki installation, presumably ''/usr/share/mediawiki-extensions''. This is because the Debian way of managing MediaWiki extension is non-standard. We can do this with the following commands: cd /tmp/GroupPermissionsManager mv * /usr/share/mediawiki-extensions Next, we have to make a small alteration to ''/usr/share/mediawiki/includes/GlobalFunctions.php'' because there's a bug or shortcoming in MediaWiki 1.12, and that's the version that Lenny uses. The alteration is described in [http://www.mediawiki.org/wiki/Extension:GroupPermissionsManager#Patch a patch prescription on the MediaWiki site], but in essence we add a line after line number 422: the line beginning with "wfRunHooks": function wfMsgGetKey( $key, $useDB, $forContent = false, $transform = true ) { global $wgParser, $wgContLang, $wgMessageCache, $wgLang; wfRunHooks( 'NormalizeMessageKey', array( &$key, &$useDB, &$langCode, &$transform ) ); Next, we create a directory where Group Permissions Manager will keep the configuration files. In the Debian style, we need something under ''/etc'' so we suggest creating ''/etc/mediawiki/config''. After that, grant the permission to write in this directory to the web server daemon, for Apache2 ''www-data''.<br> Finally, create a symlink to this config directory in the place where GroupPermissionsManager actually ''expects'' it, namely in the directory where the PHP-script itself resides (here: ''/usr/share/mediawiki-extensions/''). All of this can be achieved by following these steps: cd /etc/mediawiki mkdir config chown www-data:www-data config cd /usr/share/mediawiki-extensions ln -s /etc/mediawiki/config Now we can mark the extension ''GroupPermissionsManager.php'' available to MediaWiki: cd /etc/mediawiki-extensions/extensions-available ln -s /usr/share/mediawiki-extensions/GroupPermissionsManager.php Then, enable the extension mwenext GroupPermissionsManager.php This by default adds some extra capabilities to the Mediawiki administrator group "bureaucrat", of which WikiAdmin is a member - and presumably you too. The capabilities are to use a ''Special'' page to create, manage, and remove Wiki groups and their permissions. ==Using the extension== To manage group permissions, you need the following: * your MediaWiki user account needs to be in a MediaWiki group that has been granted the right to use Group Permissions Manager, e.g. ''bureaucrat'' as depicted above; * you must be logged in with that MediaWiki account; * you need to know the name of the group whose permissions you want to manage (or create or delete). In the left navigation area, click on ''Special pages''; scroll down to the section ''Restricted special pages'', you should see an entry ''Manage Group Permissions''. Click it to enter the Manage Group Permissions special page. Here, you'll find just an empty box and a "Go" button. Fill in the name of the group you want to create/manage/delete, and click "Go". You'll find yourself in a long page with group permissions, each of which can be "true", "false" or "inherit". Setting a permission to "true" or "false" enables or disables the permission for this group, while leaving it on "inherit" means the group gets the default permission that MediaWiki assigns every group - just think of the default rights of the default group "users" Furthermore: * If the group pre-exists, you'll find above the list a comment box and a "Delete group" button, where you can remove the group, while leaving the comment in the ''GroupPermissionsLog.log'' log file. * Furthermore, if the group pre-exists, the permissions list ends with a comment box and a "Change group permissions" button. Clicking that button will change the group permissions to the set designated in the permissions list. The changes, along with all other group permissions, can be found in the ''/etc/mediawiki/config'' directory in file ''GroupPermissons.php''. Clicking the button will also have resulted in a backup of the ''GroupPermissons.php'' file in that same directory, but named ''GroupPermissons.<timestamp>.php'', e.g. ''GroupPermissions.21012009171713.php''. * If the group name is "new", no "Delete group" button is shown, but the permissions list ends with a comment box and an "Add group" button, which will create the group with the designated name, while leaving the comment in the ''GroupPermissionsLog.log'' log file. Again, the comment is logged, and a backup of the ''GroupPermissons.php'' file is made. e2927ada15b5e7ed0d95d33d10f1660877025d0e 2370 2366 2009-02-12T20:04:44Z Saruman! 2 made GPM directory structure match our own recommendations on non-debian extension dir structure wikitext text/x-wiki ==Mediawiki Extension: Group Permissions Manager== Sometimes you as a Mediawiki administrator might feel the need to add or remove a group, or edit a groups rights. Unfortunately, there is no such function in the MediaWiki software itself, you'd have to edit the ''LocalSettings.php'' file somehow. [http://www.imdb.com/title/tt0096928/ Bogus!] But fortunately, there now exists an extension that adds this functionality. [http://www.imdb.com/title/tt0096928/ Most excellent!] Note: if you want to install the older version 2.00 of this plugin (which is much simpler, both in installation and in functionality), then go to the [[MediaWikiExtension GroupPermissionsManager2.00| Group Permissions Manager 2.00]] page. The instructions on this page are for the 3.2.6 version (build r45886). ==Adding the extension== First, download the latest snapshot of the GroupPermissionsManager extension from here: [http://www.mediawiki.org/wiki/Extension:GroupPermissionsManager Mediawiki Extension:Group Permissions Manager]. It's a single archive with a name that looks like ''GroupPermissionsManager-trunk-r45886.tar.gz''. You can extract it straight into the Debian mediawiki extensions directory ''/usr/share/mediawiki-extensions'', that already exists if you've installed the ''[[Mediawiki-extensions_under_Debian|mediawiki-extensions]]'' package; out comes a little directory structure like this: GroupPermissionsManager |-- plugins | |-- disabled | `-- messages `-- scripts You'll have to make sure all files and directories are owned by ''root'', and that the PHP files cannot be edited by anyone else than ''root''. If you extracted the files as ''root'', this will already be the case. If not, then as ''root'' run: cd /usr/share/mediawiki-extensions/GroupPermissionsManager chown -R root:root * chmod -R 644 *.php Next, we have to make a small alteration to ''/usr/share/mediawiki/includes/GlobalFunctions.php'' because there's a bug or shortcoming in MediaWiki 1.12, and that's the version that Lenny uses. The alteration is described in [http://www.mediawiki.org/wiki/Extension:GroupPermissionsManager#Patch a patch prescription on the MediaWiki site], but in essence we add a line after line number 422: the line beginning with "wfRunHooks": function wfMsgGetKey( $key, $useDB, $forContent = false, $transform = true ) { global $wgParser, $wgContLang, $wgMessageCache, $wgLang; wfRunHooks( 'NormalizeMessageKey', array( &$key, &$useDB, &$langCode, &$transform ) ); Next, we create a directory where Group Permissions Manager will keep the configuration files. In the Debian style, we need something under ''/etc''. We would ordinarily suggest something under ''/etc/mediawiki-extensions'', but the configuration that the extension manipulates is used by MediaWiki itself. Thus we suggest creating ''/etc/mediawiki/config''. After that, grant the permission to write in this directory to the web server daemon, for Apache2 ''www-data''.<br> Finally, create a symlink to this config directory in the place where GroupPermissionsManager actually ''expects'' it, namely in the directory where the PHP-script itself resides (here: ''/usr/share/mediawiki-extensions/''). All of this can be achieved by following these steps: cd /etc/mediawiki mkdir config chown www-data:www-data config cd /usr/share/mediawiki-extensions ln -s /etc/mediawiki/config Now we can mark the extension ''GroupPermissionsManager.php'' available to MediaWiki: cd /etc/mediawiki-extensions/extensions-available ln -s /usr/share/mediawiki-extensions/GroupPermissionsManager/GroupPermissionsManager.php Then, enable the extension mwenext GroupPermissionsManager.php This by default adds some extra capabilities to the Mediawiki administrator group "bureaucrat", of which WikiAdmin is a member - and presumably you too. The capabilities are to use a ''Special'' page to create, manage, and remove Wiki groups and their permissions. ==Using the extension== To manage group permissions, you need the following: * your MediaWiki user account needs to be in a MediaWiki group that has been granted the right to use Group Permissions Manager, e.g. ''bureaucrat'' as depicted above; * you must be logged in with that MediaWiki account; * you need to know the name of the group whose permissions you want to manage (or create or delete). In the left navigation area, click on ''Special pages''; scroll down to the section ''Restricted special pages'', you should see an entry ''Manage Group Permissions''. Click it to enter the Manage Group Permissions special page. Here, you'll find just an empty box and a "Go" button. Fill in the name of the group you want to create/manage/delete, and click "Go". You'll find yourself in a long page with group permissions, each of which can be "true", "false" or "inherit". Setting a permission to "true" or "false" enables or disables the permission for this group, while leaving it on "inherit" means the group gets the default permission that MediaWiki assigns every group - just think of the default rights of the default group "users" Furthermore: * If the group pre-exists, you'll find above the list a comment box and a "Delete group" button, where you can remove the group, while leaving the comment in the ''GroupPermissionsLog.log'' log file. * Furthermore, if the group pre-exists, the permissions list ends with a comment box and a "Change group permissions" button. Clicking that button will change the group permissions to the set designated in the permissions list. The changes, along with all other group permissions, can be found in the ''/etc/mediawiki/config'' directory in file ''GroupPermissons.php''. Clicking the button will also have resulted in a backup of the ''GroupPermissons.php'' file in that same directory, but named ''GroupPermissons.<timestamp>.php'', e.g. ''GroupPermissions.21012009171713.php''. * If the group name is "new", no "Delete group" button is shown, but the permissions list ends with a comment box and an "Add group" button, which will create the group with the designated name, while leaving the comment in the ''GroupPermissionsLog.log'' log file. Again, the comment is logged, and a backup of the ''GroupPermissons.php'' file is made. 6ca85398433f4ba0de56b03f7ba331dbc62f7df1 2371 2370 2009-02-12T20:05:39Z Saruman! 2 /* Adding the extension */ used GeSHi wikitext text/x-wiki ==Mediawiki Extension: Group Permissions Manager== Sometimes you as a Mediawiki administrator might feel the need to add or remove a group, or edit a groups rights. Unfortunately, there is no such function in the MediaWiki software itself, you'd have to edit the ''LocalSettings.php'' file somehow. [http://www.imdb.com/title/tt0096928/ Bogus!] But fortunately, there now exists an extension that adds this functionality. [http://www.imdb.com/title/tt0096928/ Most excellent!] Note: if you want to install the older version 2.00 of this plugin (which is much simpler, both in installation and in functionality), then go to the [[MediaWikiExtension GroupPermissionsManager2.00| Group Permissions Manager 2.00]] page. The instructions on this page are for the 3.2.6 version (build r45886). ==Adding the extension== First, download the latest snapshot of the GroupPermissionsManager extension from here: [http://www.mediawiki.org/wiki/Extension:GroupPermissionsManager Mediawiki Extension:Group Permissions Manager]. It's a single archive with a name that looks like ''GroupPermissionsManager-trunk-r45886.tar.gz''. You can extract it straight into the Debian mediawiki extensions directory ''/usr/share/mediawiki-extensions'', that already exists if you've installed the ''[[Mediawiki-extensions_under_Debian|mediawiki-extensions]]'' package; out comes a little directory structure like this: GroupPermissionsManager |-- plugins | |-- disabled | `-- messages `-- scripts You'll have to make sure all files and directories are owned by ''root'', and that the PHP files cannot be edited by anyone else than ''root''. If you extracted the files as ''root'', this will already be the case. If not, then as ''root'' run: cd /usr/share/mediawiki-extensions/GroupPermissionsManager chown -R root:root * chmod -R 644 *.php Next, we have to make a small alteration to ''/usr/share/mediawiki/includes/GlobalFunctions.php'' because there's a bug or shortcoming in MediaWiki 1.12, and that's the version that Lenny uses. The alteration is described in [http://www.mediawiki.org/wiki/Extension:GroupPermissionsManager#Patch a patch prescription on the MediaWiki site], but in essence we add a line after line number 422: the line beginning with "wfRunHooks": <source lang="php"> function wfMsgGetKey( $key, $useDB, $forContent = false, $transform = true ) { global $wgParser, $wgContLang, $wgMessageCache, $wgLang; wfRunHooks( 'NormalizeMessageKey', array( &$key, &$useDB, &$langCode, &$transform ) ); </source> Next, we create a directory where Group Permissions Manager will keep the configuration files. In the Debian style, we need something under ''/etc''. We would ordinarily suggest something under ''/etc/mediawiki-extensions'', but the configuration that the extension manipulates is used by MediaWiki itself. Thus we suggest creating ''/etc/mediawiki/config''. After that, grant the permission to write in this directory to the web server daemon, for Apache2 ''www-data''.<br> Finally, create a symlink to this config directory in the place where GroupPermissionsManager actually ''expects'' it, namely in the directory where the PHP-script itself resides (here: ''/usr/share/mediawiki-extensions/''). All of this can be achieved by following these steps: cd /etc/mediawiki mkdir config chown www-data:www-data config cd /usr/share/mediawiki-extensions ln -s /etc/mediawiki/config Now we can mark the extension ''GroupPermissionsManager.php'' available to MediaWiki: cd /etc/mediawiki-extensions/extensions-available ln -s /usr/share/mediawiki-extensions/GroupPermissionsManager/GroupPermissionsManager.php Then, enable the extension mwenext GroupPermissionsManager.php This by default adds some extra capabilities to the Mediawiki administrator group "bureaucrat", of which WikiAdmin is a member - and presumably you too. The capabilities are to use a ''Special'' page to create, manage, and remove Wiki groups and their permissions. ==Using the extension== To manage group permissions, you need the following: * your MediaWiki user account needs to be in a MediaWiki group that has been granted the right to use Group Permissions Manager, e.g. ''bureaucrat'' as depicted above; * you must be logged in with that MediaWiki account; * you need to know the name of the group whose permissions you want to manage (or create or delete). In the left navigation area, click on ''Special pages''; scroll down to the section ''Restricted special pages'', you should see an entry ''Manage Group Permissions''. Click it to enter the Manage Group Permissions special page. Here, you'll find just an empty box and a "Go" button. Fill in the name of the group you want to create/manage/delete, and click "Go". You'll find yourself in a long page with group permissions, each of which can be "true", "false" or "inherit". Setting a permission to "true" or "false" enables or disables the permission for this group, while leaving it on "inherit" means the group gets the default permission that MediaWiki assigns every group - just think of the default rights of the default group "users" Furthermore: * If the group pre-exists, you'll find above the list a comment box and a "Delete group" button, where you can remove the group, while leaving the comment in the ''GroupPermissionsLog.log'' log file. * Furthermore, if the group pre-exists, the permissions list ends with a comment box and a "Change group permissions" button. Clicking that button will change the group permissions to the set designated in the permissions list. The changes, along with all other group permissions, can be found in the ''/etc/mediawiki/config'' directory in file ''GroupPermissons.php''. Clicking the button will also have resulted in a backup of the ''GroupPermissons.php'' file in that same directory, but named ''GroupPermissons.<timestamp>.php'', e.g. ''GroupPermissions.21012009171713.php''. * If the group name is "new", no "Delete group" button is shown, but the permissions list ends with a comment box and an "Add group" button, which will create the group with the designated name, while leaving the comment in the ''GroupPermissionsLog.log'' log file. Again, the comment is logged, and a backup of the ''GroupPermissons.php'' file is made. 51a2c49cf4b78ee5d16cef4c8f5cfee5ffc745d4 2374 2371 2009-02-12T21:11:51Z Saruman! 2 /* Adding the extension */ undoing added incorrect GPM subdir wikitext text/x-wiki ==Mediawiki Extension: Group Permissions Manager== Sometimes you as a Mediawiki administrator might feel the need to add or remove a group, or edit a groups rights. Unfortunately, there is no such function in the MediaWiki software itself, you'd have to edit the ''LocalSettings.php'' file somehow. [http://www.imdb.com/title/tt0096928/ Bogus!] But fortunately, there now exists an extension that adds this functionality. [http://www.imdb.com/title/tt0096928/ Most excellent!] Note: if you want to install the older version 2.00 of this plugin (which is much simpler, both in installation and in functionality), then go to the [[MediaWikiExtension GroupPermissionsManager2.00| Group Permissions Manager 2.00]] page. The instructions on this page are for the 3.2.6 version (build r45886). ==Adding the extension== First, download the latest snapshot of the GroupPermissionsManager extension from here: [http://www.mediawiki.org/wiki/Extension:GroupPermissionsManager Mediawiki Extension:Group Permissions Manager]. It's a single archive with a name that looks like ''GroupPermissionsManager-trunk-r45886.tar.gz''. You can extract it straight into the Debian mediawiki extensions directory ''/usr/share/mediawiki-extensions'', that already exists if you've installed the ''[[Mediawiki-extensions_under_Debian|mediawiki-extensions]]'' package; out comes a little directory structure like this: GroupPermissionsManager |-- plugins | |-- disabled | `-- messages `-- scripts You'll have to make sure all files and directories are owned by ''root'', and that the PHP files cannot be edited by anyone else than ''root''. This will most likely not be the case: as ''root'' run: cd /usr/share/mediawiki-extensions/GroupPermissionsManager chown -R root:root * chmod -R 644 *.php Now, to make the extension work with Debian, we ''must'' move all files and folders under ''GroupPermissionsManager'' to ''/usr/share/mediawiki-extensions'': cd /usr/share/mediawiki-extensions/GroupPermissionsManager mv scripts .. mv plugins .. mv * .. cd .. rmdir GroupPermissionsManager Next, we have to make a small alteration to ''/usr/share/mediawiki/includes/GlobalFunctions.php'' because there's a bug or shortcoming in MediaWiki 1.12, and that's the version that Lenny uses. The alteration is described in [http://www.mediawiki.org/wiki/Extension:GroupPermissionsManager#Patch a patch prescription on the MediaWiki site], but in essence we add a line after line number 422: the line beginning with "wfRunHooks": <source lang="php"> function wfMsgGetKey( $key, $useDB, $forContent = false, $transform = true ) { global $wgParser, $wgContLang, $wgMessageCache, $wgLang; wfRunHooks( 'NormalizeMessageKey', array( &$key, &$useDB, &$langCode, &$transform ) ); </source> Next, we create a directory where Group Permissions Manager will keep the configuration files. In the Debian style, we need something under ''/etc''. We would ordinarily suggest something under ''/etc/mediawiki-extensions'', but the configuration that the extension manipulates is used by MediaWiki itself. Thus we suggest creating ''/etc/mediawiki/config''. After that, grant the permission to write in this directory to the web server daemon, for Apache2 ''www-data''.<br> Finally, create a symlink to this config directory in the place where GroupPermissionsManager actually ''expects'' it, namely in the directory where the PHP-script itself resides (here: ''/usr/share/mediawiki-extensions/''). All of this can be achieved by following these steps: cd /etc/mediawiki mkdir config chown www-data:www-data config cd /usr/share/mediawiki-extensions ln -s /etc/mediawiki/config Now we can mark the extension ''GroupPermissionsManager.php'' available to MediaWiki: cd /etc/mediawiki-extensions/extensions-available ln -s /usr/share/mediawiki-extensions/GroupPermissionsManager.php Then, enable the extension mwenext GroupPermissionsManager.php This by default adds some extra capabilities to the Mediawiki administrator group "bureaucrat", of which WikiAdmin is a member - and presumably you too. The capabilities are to use a ''Special'' page to create, manage, and remove Wiki groups and their permissions. ==Using the extension== To manage group permissions, you need the following: * your MediaWiki user account needs to be in a MediaWiki group that has been granted the right to use Group Permissions Manager, e.g. ''bureaucrat'' as depicted above; * you must be logged in with that MediaWiki account; * you need to know the name of the group whose permissions you want to manage (or create or delete). In the left navigation area, click on ''Special pages''; scroll down to the section ''Restricted special pages'', you should see an entry ''Manage Group Permissions''. Click it to enter the Manage Group Permissions special page. Here, you'll find just an empty box and a "Go" button. Fill in the name of the group you want to create/manage/delete, and click "Go". You'll find yourself in a long page with group permissions, each of which can be "true", "false" or "inherit". Setting a permission to "true" or "false" enables or disables the permission for this group, while leaving it on "inherit" means the group gets the default permission that MediaWiki assigns every group - just think of the default rights of the default group "users" Furthermore: * If the group pre-exists, you'll find above the list a comment box and a "Delete group" button, where you can remove the group, while leaving the comment in the ''GroupPermissionsLog.log'' log file. * Furthermore, if the group pre-exists, the permissions list ends with a comment box and a "Change group permissions" button. Clicking that button will change the group permissions to the set designated in the permissions list. The changes, along with all other group permissions, can be found in the ''/etc/mediawiki/config'' directory in file ''GroupPermissons.php''. Clicking the button will also have resulted in a backup of the ''GroupPermissons.php'' file in that same directory, but named ''GroupPermissons.<timestamp>.php'', e.g. ''GroupPermissions.21012009171713.php''. * If the group name is "new", no "Delete group" button is shown, but the permissions list ends with a comment box and an "Add group" button, which will create the group with the designated name, while leaving the comment in the ''GroupPermissionsLog.log'' log file. Again, the comment is logged, and a backup of the ''GroupPermissons.php'' file is made. 68ee753044775663feb079b839301aa3bb9ef2d5 2375 2374 2009-02-12T21:12:37Z Saruman! 2 /* Adding the extension */ expanded chmod reach wikitext text/x-wiki ==Mediawiki Extension: Group Permissions Manager== Sometimes you as a Mediawiki administrator might feel the need to add or remove a group, or edit a groups rights. Unfortunately, there is no such function in the MediaWiki software itself, you'd have to edit the ''LocalSettings.php'' file somehow. [http://www.imdb.com/title/tt0096928/ Bogus!] But fortunately, there now exists an extension that adds this functionality. [http://www.imdb.com/title/tt0096928/ Most excellent!] Note: if you want to install the older version 2.00 of this plugin (which is much simpler, both in installation and in functionality), then go to the [[MediaWikiExtension GroupPermissionsManager2.00| Group Permissions Manager 2.00]] page. The instructions on this page are for the 3.2.6 version (build r45886). ==Adding the extension== First, download the latest snapshot of the GroupPermissionsManager extension from here: [http://www.mediawiki.org/wiki/Extension:GroupPermissionsManager Mediawiki Extension:Group Permissions Manager]. It's a single archive with a name that looks like ''GroupPermissionsManager-trunk-r45886.tar.gz''. You can extract it straight into the Debian mediawiki extensions directory ''/usr/share/mediawiki-extensions'', that already exists if you've installed the ''[[Mediawiki-extensions_under_Debian|mediawiki-extensions]]'' package; out comes a little directory structure like this: GroupPermissionsManager |-- plugins | |-- disabled | `-- messages `-- scripts You'll have to make sure all files and directories are owned by ''root'', and that the PHP files cannot be edited by anyone else than ''root''. This will most likely not be the case: as ''root'' run: cd /usr/share/mediawiki-extensions/GroupPermissionsManager chown -R root:root * chmod -R 644 * Now, to make the extension work with Debian, we ''must'' move all files and folders under ''GroupPermissionsManager'' to ''/usr/share/mediawiki-extensions'': cd /usr/share/mediawiki-extensions/GroupPermissionsManager mv scripts .. mv plugins .. mv * .. cd .. rmdir GroupPermissionsManager Next, we have to make a small alteration to ''/usr/share/mediawiki/includes/GlobalFunctions.php'' because there's a bug or shortcoming in MediaWiki 1.12, and that's the version that Lenny uses. The alteration is described in [http://www.mediawiki.org/wiki/Extension:GroupPermissionsManager#Patch a patch prescription on the MediaWiki site], but in essence we add a line after line number 422: the line beginning with "wfRunHooks": <source lang="php"> function wfMsgGetKey( $key, $useDB, $forContent = false, $transform = true ) { global $wgParser, $wgContLang, $wgMessageCache, $wgLang; wfRunHooks( 'NormalizeMessageKey', array( &$key, &$useDB, &$langCode, &$transform ) ); </source> Next, we create a directory where Group Permissions Manager will keep the configuration files. In the Debian style, we need something under ''/etc''. We would ordinarily suggest something under ''/etc/mediawiki-extensions'', but the configuration that the extension manipulates is used by MediaWiki itself. Thus we suggest creating ''/etc/mediawiki/config''. After that, grant the permission to write in this directory to the web server daemon, for Apache2 ''www-data''.<br> Finally, create a symlink to this config directory in the place where GroupPermissionsManager actually ''expects'' it, namely in the directory where the PHP-script itself resides (here: ''/usr/share/mediawiki-extensions/''). All of this can be achieved by following these steps: cd /etc/mediawiki mkdir config chown www-data:www-data config cd /usr/share/mediawiki-extensions ln -s /etc/mediawiki/config Now we can mark the extension ''GroupPermissionsManager.php'' available to MediaWiki: cd /etc/mediawiki-extensions/extensions-available ln -s /usr/share/mediawiki-extensions/GroupPermissionsManager.php Then, enable the extension mwenext GroupPermissionsManager.php This by default adds some extra capabilities to the Mediawiki administrator group "bureaucrat", of which WikiAdmin is a member - and presumably you too. The capabilities are to use a ''Special'' page to create, manage, and remove Wiki groups and their permissions. ==Using the extension== To manage group permissions, you need the following: * your MediaWiki user account needs to be in a MediaWiki group that has been granted the right to use Group Permissions Manager, e.g. ''bureaucrat'' as depicted above; * you must be logged in with that MediaWiki account; * you need to know the name of the group whose permissions you want to manage (or create or delete). In the left navigation area, click on ''Special pages''; scroll down to the section ''Restricted special pages'', you should see an entry ''Manage Group Permissions''. Click it to enter the Manage Group Permissions special page. Here, you'll find just an empty box and a "Go" button. Fill in the name of the group you want to create/manage/delete, and click "Go". You'll find yourself in a long page with group permissions, each of which can be "true", "false" or "inherit". Setting a permission to "true" or "false" enables or disables the permission for this group, while leaving it on "inherit" means the group gets the default permission that MediaWiki assigns every group - just think of the default rights of the default group "users" Furthermore: * If the group pre-exists, you'll find above the list a comment box and a "Delete group" button, where you can remove the group, while leaving the comment in the ''GroupPermissionsLog.log'' log file. * Furthermore, if the group pre-exists, the permissions list ends with a comment box and a "Change group permissions" button. Clicking that button will change the group permissions to the set designated in the permissions list. The changes, along with all other group permissions, can be found in the ''/etc/mediawiki/config'' directory in file ''GroupPermissons.php''. Clicking the button will also have resulted in a backup of the ''GroupPermissons.php'' file in that same directory, but named ''GroupPermissons.<timestamp>.php'', e.g. ''GroupPermissions.21012009171713.php''. * If the group name is "new", no "Delete group" button is shown, but the permissions list ends with a comment box and an "Add group" button, which will create the group with the designated name, while leaving the comment in the ''GroupPermissionsLog.log'' log file. Again, the comment is logged, and a backup of the ''GroupPermissons.php'' file is made. 1ce7a1f28a74e54093058bc96cc6169717b4960a 0 1585 2367 2009-02-12T19:54:49Z Saruman! 2 [[MediaWikiExtension GroupPermissionsManager]] moved to [[MediaWiki Extension - GroupPermissionsManager]]: nicer name wikitext text/x-wiki #REDIRECT [[MediaWiki Extension - GroupPermissionsManager]] 7cbb8152f8588fa43bf6b1df62ef3a5c7f5d3c9a 0 1507 2377 2152 2009-02-14T21:24:18Z Saruman! 2 Started dav/ldap section wikitext text/x-wiki ==Apache2== ===Installation of Apache2=== Contribution needed. ===Configuration of Apache2=== Once Apache2 is in place, you might want to [[Enabling SSL for Apache2 | enable SSL]] for it. ==Installation of PHP5== Contribution needed. ==Adding WebDAV to your Apache2== Out of the box, your Debian Apache2 is prepared to start using WebDAV. All you need is to enable two modules: one for WebDAV itself, one for the authentication that you want to use. Since our server mainly uses LDAP, we'll describe WebDAV+LDAP here. First, enable the WebDAV and authnz_ldap modules: a2enmod dav a2enmod dav_fs a2enmod authnz_ldap Do not restart Apache2 just yet, because we haven't configured either the WebDAV site or its authentication! Next, adapt the virtual host that may employ WebDAV and LDAP authentication. The virtual host file needs a section that enables WebDAV (using the directive ''Dav On''), and some directives on how to authorize users within this section. Suppose we want to enable WebDAV only for subdirectory ''webdav'' within virtual host ''<nowiki>http://www.saruman.biz/</nowiki>''. Then in the correspondig Virtual Host file (something like ''/etc/apache2/sites-available/000-saruman.biz'') we need to include the following section: DavLockDB /var/run/apache2.DavLock <Location /webdav> Order Allow,Deny Allow from all Dav On AuthType Basic AuthBasicProvider ldap AuthzLDAPAuthoritative Off AuthName "Saruman.BIZ" AuthLDAPURL "ldap://myserver.my.domain.com/ou=it,ou=departments,dc=my,dc=domain,dc=com?sAMAccountName" AuthLDAPBindDN "myusername@my.domain.com" AuthLDAPBindPassword "mypassword" require valid-user </Location> e619b71095663cd9fb76af47e5f3799cf4c1c602 2378 2377 2009-02-14T22:06:59Z Saruman! 2 extra info wikitext text/x-wiki ==Apache2== ===Installation of Apache2=== Contribution needed. ===Configuration of Apache2=== Once Apache2 is in place, you might want to [[Enabling SSL for Apache2 | enable SSL]] for it. ==Installation of PHP5== Contribution needed. ==Adding WebDAV to your Apache2== ===Thoughts about WebDAV and your configuration=== Out of the box, your Debian Apache2 is prepared to start using WebDAV. All you need is to enable two modules: one for WebDAV itself, one for the authentication that you want to use. Since our server mainly uses LDAP, we'll describe WebDAV+LDAP here. Furthermore, because WebDAV allows editing files on your server, security is paramount (well, it always is, of course. What we mean is that it's even '''more''' important now). The Apache project recommends:<br> ''The use of HTTP Basic Authentication is not recommended. You should use at least HTTP Digest Authentication, which is provided by the mod_auth_digest module. Nearly all WebDAV clients support this authentication method. An alternative is Basic Authentication over an SSL enabled connection.''<br> Thus you should not using Basic Authentication (which is pretty simple to set up) unless you run it over SSL - so we do that as well. We choose the Virtual Host that defines our SSL-site, and extend it with WebDAV functionality. If this is not what you want, consider stepping your authentication up to Digest Authentication. ===Configuring WebDAV and LDAP for your SSL-enabled Virtual Host=== First, enable the WebDAV and authnz_ldap modules: a2enmod dav a2enmod dav_fs a2enmod authnz_ldap Do not restart Apache2 just yet, because we haven't configured either the WebDAV site or its authentication! Furthermore, a location for the DAV lock database must be specified in the global section of your Apache2 configuration file using the [http://httpd.apache.org/docs/2.2/mod/mod_dav_fs.html#davlockdb DavLockDB directive]. To this end, create a file under ''/etc/apache2/conf.d'' named ''webdav'' containing this single line: DavLockDB /var/run/apache2/DavLock This will act as the (global) lock database for WebDAV; we don't need to specify it in any other configuration file (like the Virtual Host configuration files). Of course, your server should have a directory ''/var/run/apache2'', and it must be writable for the user ''www-data'' under which Apache2 runs. Next, adapt the virtual host that may employ WebDAV and LDAP authentication. The virtual host file needs a section that enables WebDAV (using the directive ''Dav On''), and some directives on how to authorize users within this section. Suppose we want to enable WebDAV only for subdirectory ''webdav'' within virtual host ''<nowiki>http://www.saruman.biz/</nowiki>''. Then in the correspondig Virtual Host file (something like ''/etc/apache2/sites-available/000-saruman.biz'') we need to include the following section: <Location /webdav> Order Allow,Deny Allow from all Dav On These lines turn on WebDAV for the location ''/webdav''. This of course means that there should ''be'' a directory in your server's filesystem named ''webdav'' and located under the root of this virtual host, e.g. ''/var/www/saruman.biz/webdav'' AuthType Basic AuthBasicProvider ldap AuthzLDAPAuthoritative On This section sets up the authentication as HTTP Basic, with LDAP as the provider, and NOT allowing the authorization phase to fall back to other providers if LDAP cannot provide the required answer. If you want to use "require" statements from some other authorization provider, then you must set ''AuthzLDAPAuthoritative'' to "off". AuthName "Enter your Saruman.biz login" AuthLDAPURL "ldap://myserver.my.domain.com/ou=it,ou=departments,dc=my,dc=domain,dc=com?sAMAccountName" AuthLDAPBindDN "myusername@my.domain.com" AuthLDAPBindPassword "mypassword" The ''AuthName'' directive "sets the name of the authorization realm". The string provided for the AuthName is what will appear in the password dialog provided by most browsers.<br> require valid-user </Location> c960c2cd5298858400074898c780254408900385 2379 2378 2009-02-16T21:28:03Z Saruman! 2 /* Configuring WebDAV and LDAP for your SSL-enabled Virtual Host */ finished WebDAV section wikitext text/x-wiki ==Apache2== ===Installation of Apache2=== Contribution needed. ===Configuration of Apache2=== Once Apache2 is in place, you might want to [[Enabling SSL for Apache2 | enable SSL]] for it. ==Installation of PHP5== Contribution needed. ==Adding WebDAV to your Apache2== ===Thoughts about WebDAV and your configuration=== Out of the box, your Debian Apache2 is prepared to start using WebDAV. All you need is to enable two modules: one for WebDAV itself, one for the authentication that you want to use. Since our server mainly uses LDAP, we'll describe WebDAV+LDAP here. Furthermore, because WebDAV allows editing files on your server, security is paramount (well, it always is, of course. What we mean is that it's even '''more''' important now). The Apache project recommends:<br> ''The use of HTTP Basic Authentication is not recommended. You should use at least HTTP Digest Authentication, which is provided by the mod_auth_digest module. Nearly all WebDAV clients support this authentication method. An alternative is Basic Authentication over an SSL enabled connection.''<br> Thus you should not using Basic Authentication (which is pretty simple to set up) unless you run it over SSL - so we do that as well. We choose the Virtual Host that defines our SSL-site, and extend it with WebDAV functionality. If this is not what you want, consider stepping your authentication up to Digest Authentication. ===Configuring WebDAV and LDAP for your SSL-enabled Virtual Host=== First, enable the WebDAV and authnz_ldap modules: a2enmod dav a2enmod dav_fs a2enmod authnz_ldap Do not restart Apache2 just yet, because we haven't configured either the WebDAV site or its authentication! Furthermore, a location for the DAV lock database must be specified in the global section of your Apache2 configuration file using the [http://httpd.apache.org/docs/2.2/mod/mod_dav_fs.html#davlockdb DavLockDB directive]. To this end, create a file under ''/etc/apache2/conf.d'' named ''webdav'' containing this single line: DavLockDB /var/run/apache2/DavLock This will act as the (global) lock database for WebDAV; we don't need to specify it in any other configuration file (like the Virtual Host configuration files). Of course, your server should have a directory ''/var/run/apache2'', and it must be writable for the user ''www-data'' under which Apache2 runs. Next, adapt the virtual host that may employ WebDAV and LDAP authentication. The virtual host file needs a section that enables WebDAV (using the directive ''Dav On''), and some directives on how to authorize users within this section. Suppose we want to enable WebDAV only for subdirectory ''webdav'' within virtual host ''<nowiki>http://www.saruman.biz/</nowiki>''. Then in the correspondig Virtual Host file (something like ''/etc/apache2/sites-available/000-saruman.biz'') we need to include the following section: <Location /webdav> Order Allow,Deny Allow from all Dav On These lines turn on WebDAV for the location ''/webdav''. This of course means that there should ''be'' a directory in your server's filesystem named ''webdav'' and located under the root of this virtual host, e.g. ''/var/www/saruman.biz/webdav'' AuthType Basic AuthBasicProvider ldap AuthzLDAPAuthoritative On This section sets up the authentication as HTTP Basic, with LDAP as the provider, and NOT allowing the authorization phase to fall back to other providers if LDAP cannot provide the required answer. If you want to use "require" statements from some other authorization provider, then you must set ''AuthzLDAPAuthoritative'' to "off". AuthName "Enter your Saruman.biz login" AuthLDAPURL "ldap://myserver.saruman.biz/ou=people,dc=saruman,dc=biz?mail" NONE AuthLDAPBindDN "cn=admin,dc=saruman,dc=biz" AuthLDAPBindPassword "mypassword" The ''AuthName'' directive "sets the name of the authorization realm". The string provided for the AuthName is what will appear in the password dialog provided by most browsers.<br> The ''AuthLDAPURL'' should point to your server, and the word behind the question mark should be the LDAP field that you want to use as login. We use ''mail'' so that we can log in with our mail address.<br> The ''AuthLDAPBindDN'' should be of a user with the right to view the passwords of the users that will be using the WebDAV server, and the ''AuthLDAPBindPassword'' should be that user's password.<br> require valid-user </Location> This last directive means that any user who has authenticated is granted access. Since only LDAP users can authenticate, this is just fine. Next up, you need to create folder ''webdav'' under the root of your Virtual Host. Do not forget to make that folder owned by ''www-data:www-data'' and readable/writable only by that user: cd /data/wwwroot/yoursite mkdir webdav chown www-data:www-data webdav chmod 660 webdav Now you can restart Apache2, see if it restarts ok, and then test your new WebDAV folder. 4722b231cae48bae11651d97eff16f30621c529c 2399 2379 2009-05-17T10:34:35Z Saruman! 2 apache installation outlined wikitext text/x-wiki ==Apache2== ===Installation of Apache2=== Installation of Apache2 is quite simple: apt-get install apache2 This brings a slew of packages, a.o. ''apache2-mpm-worker'', ''apache2-utils'', ''libapr1'' et cetera. When you want a different worker (e.g. , you should use ''aptitude'' to select that different worker (prefork etc.). ===Configuration of Apache2=== Once Apache2 is in place, you might want to [[Enabling SSL for Apache2 | enable SSL]] for it. ==Installation of PHP5== Contribution needed. ==Adding WebDAV to your Apache2== ===Thoughts about WebDAV and your configuration=== Out of the box, your Debian Apache2 is prepared to start using WebDAV. All you need is to enable two modules: one for WebDAV itself, one for the authentication that you want to use. Since our server mainly uses LDAP, we'll describe WebDAV+LDAP here. Furthermore, because WebDAV allows editing files on your server, security is paramount (well, it always is, of course. What we mean is that it's even '''more''' important now). The Apache project recommends:<br> ''The use of HTTP Basic Authentication is not recommended. You should use at least HTTP Digest Authentication, which is provided by the mod_auth_digest module. Nearly all WebDAV clients support this authentication method. An alternative is Basic Authentication over an SSL enabled connection.''<br> Thus you should not using Basic Authentication (which is pretty simple to set up) unless you run it over SSL - so we do that as well. We choose the Virtual Host that defines our SSL-site, and extend it with WebDAV functionality. If this is not what you want, consider stepping your authentication up to Digest Authentication. ===Configuring WebDAV and LDAP for your SSL-enabled Virtual Host=== First, enable the WebDAV and authnz_ldap modules: a2enmod dav a2enmod dav_fs a2enmod authnz_ldap Do not restart Apache2 just yet, because we haven't configured either the WebDAV site or its authentication! Furthermore, a location for the DAV lock database must be specified in the global section of your Apache2 configuration file using the [http://httpd.apache.org/docs/2.2/mod/mod_dav_fs.html#davlockdb DavLockDB directive]. To this end, create a file under ''/etc/apache2/conf.d'' named ''webdav'' containing this single line: DavLockDB /var/run/apache2/DavLock This will act as the (global) lock database for WebDAV; we don't need to specify it in any other configuration file (like the Virtual Host configuration files). Of course, your server should have a directory ''/var/run/apache2'', and it must be writable for the user ''www-data'' under which Apache2 runs. Next, adapt the virtual host that may employ WebDAV and LDAP authentication. The virtual host file needs a section that enables WebDAV (using the directive ''Dav On''), and some directives on how to authorize users within this section. Suppose we want to enable WebDAV only for subdirectory ''webdav'' within virtual host ''<nowiki>http://www.saruman.biz/</nowiki>''. Then in the correspondig Virtual Host file (something like ''/etc/apache2/sites-available/000-saruman.biz'') we need to include the following section: <Location /webdav> Order Allow,Deny Allow from all Dav On These lines turn on WebDAV for the location ''/webdav''. This of course means that there should ''be'' a directory in your server's filesystem named ''webdav'' and located under the root of this virtual host, e.g. ''/var/www/saruman.biz/webdav'' AuthType Basic AuthBasicProvider ldap AuthzLDAPAuthoritative On This section sets up the authentication as HTTP Basic, with LDAP as the provider, and NOT allowing the authorization phase to fall back to other providers if LDAP cannot provide the required answer. If you want to use "require" statements from some other authorization provider, then you must set ''AuthzLDAPAuthoritative'' to "off". AuthName "Enter your Saruman.biz login" AuthLDAPURL "ldap://myserver.saruman.biz/ou=people,dc=saruman,dc=biz?mail" NONE AuthLDAPBindDN "cn=admin,dc=saruman,dc=biz" AuthLDAPBindPassword "mypassword" The ''AuthName'' directive "sets the name of the authorization realm". The string provided for the AuthName is what will appear in the password dialog provided by most browsers.<br> The ''AuthLDAPURL'' should point to your server, and the word behind the question mark should be the LDAP field that you want to use as login. We use ''mail'' so that we can log in with our mail address.<br> The ''AuthLDAPBindDN'' should be of a user with the right to view the passwords of the users that will be using the WebDAV server, and the ''AuthLDAPBindPassword'' should be that user's password.<br> require valid-user </Location> This last directive means that any user who has authenticated is granted access. Since only LDAP users can authenticate, this is just fine. Next up, you need to create folder ''webdav'' under the root of your Virtual Host. Do not forget to make that folder owned by ''www-data:www-data'' and readable/writable only by that user: cd /data/wwwroot/yoursite mkdir webdav chown www-data:www-data webdav chmod 660 webdav Now you can restart Apache2, see if it restarts ok, and then test your new WebDAV folder. 083f7aff6769c2e611ea68f1c44e9780b4f772d3 2400 2399 2009-05-17T11:00:25Z Saruman! 2 some words on PHP5 installation wikitext text/x-wiki ==Apache2== ===Installation of Apache2=== Installation of Apache2 is quite simple: apt-get install apache2 This brings a slew of packages, a.o. ''apache2-mpm-worker'', ''apache2-utils'', ''libapr1'' et cetera. When you want a different worker (e.g. , you should use ''aptitude'' to select that different worker (prefork etc.). ===Configuration of Apache2=== Once Apache2 is in place, you might want to [[Enabling SSL for Apache2 | enable SSL]] for it. ==Installation of PHP5== Installing PHP5 is as easy as sudo apt-get install php5 php5-cli Note that if you had installed Apache2 module ''apache2-mpm-worker'', it will get replaced with ''apache2-mpm-prefork''. Furthermore, note that ''php5-cli'' is only needed if you want to run PHP commands at the prompt - but our guess is that you want it (e.g. to perform maintenance tasks for your [[Mediawiki_Installation|MediaWiki wikiserver]]. ==Adding WebDAV to your Apache2== ===Thoughts about WebDAV and your configuration=== Out of the box, your Debian Apache2 is prepared to start using WebDAV. All you need is to enable two modules: one for WebDAV itself, one for the authentication that you want to use. Since our server mainly uses LDAP, we'll describe WebDAV+LDAP here. Furthermore, because WebDAV allows editing files on your server, security is paramount (well, it always is, of course. What we mean is that it's even '''more''' important now). The Apache project recommends:<br> ''The use of HTTP Basic Authentication is not recommended. You should use at least HTTP Digest Authentication, which is provided by the mod_auth_digest module. Nearly all WebDAV clients support this authentication method. An alternative is Basic Authentication over an SSL enabled connection.''<br> Thus you should not using Basic Authentication (which is pretty simple to set up) unless you run it over SSL - so we do that as well. We choose the Virtual Host that defines our SSL-site, and extend it with WebDAV functionality. If this is not what you want, consider stepping your authentication up to Digest Authentication. ===Configuring WebDAV and LDAP for your SSL-enabled Virtual Host=== First, enable the WebDAV and authnz_ldap modules: a2enmod dav a2enmod dav_fs a2enmod authnz_ldap Do not restart Apache2 just yet, because we haven't configured either the WebDAV site or its authentication! Furthermore, a location for the DAV lock database must be specified in the global section of your Apache2 configuration file using the [http://httpd.apache.org/docs/2.2/mod/mod_dav_fs.html#davlockdb DavLockDB directive]. To this end, create a file under ''/etc/apache2/conf.d'' named ''webdav'' containing this single line: DavLockDB /var/run/apache2/DavLock This will act as the (global) lock database for WebDAV; we don't need to specify it in any other configuration file (like the Virtual Host configuration files). Of course, your server should have a directory ''/var/run/apache2'', and it must be writable for the user ''www-data'' under which Apache2 runs. Next, adapt the virtual host that may employ WebDAV and LDAP authentication. The virtual host file needs a section that enables WebDAV (using the directive ''Dav On''), and some directives on how to authorize users within this section. Suppose we want to enable WebDAV only for subdirectory ''webdav'' within virtual host ''<nowiki>http://www.saruman.biz/</nowiki>''. Then in the correspondig Virtual Host file (something like ''/etc/apache2/sites-available/000-saruman.biz'') we need to include the following section: <Location /webdav> Order Allow,Deny Allow from all Dav On These lines turn on WebDAV for the location ''/webdav''. This of course means that there should ''be'' a directory in your server's filesystem named ''webdav'' and located under the root of this virtual host, e.g. ''/var/www/saruman.biz/webdav'' AuthType Basic AuthBasicProvider ldap AuthzLDAPAuthoritative On This section sets up the authentication as HTTP Basic, with LDAP as the provider, and NOT allowing the authorization phase to fall back to other providers if LDAP cannot provide the required answer. If you want to use "require" statements from some other authorization provider, then you must set ''AuthzLDAPAuthoritative'' to "off". AuthName "Enter your Saruman.biz login" AuthLDAPURL "ldap://myserver.saruman.biz/ou=people,dc=saruman,dc=biz?mail" NONE AuthLDAPBindDN "cn=admin,dc=saruman,dc=biz" AuthLDAPBindPassword "mypassword" The ''AuthName'' directive "sets the name of the authorization realm". The string provided for the AuthName is what will appear in the password dialog provided by most browsers.<br> The ''AuthLDAPURL'' should point to your server, and the word behind the question mark should be the LDAP field that you want to use as login. We use ''mail'' so that we can log in with our mail address.<br> The ''AuthLDAPBindDN'' should be of a user with the right to view the passwords of the users that will be using the WebDAV server, and the ''AuthLDAPBindPassword'' should be that user's password.<br> require valid-user </Location> This last directive means that any user who has authenticated is granted access. Since only LDAP users can authenticate, this is just fine. Next up, you need to create folder ''webdav'' under the root of your Virtual Host. Do not forget to make that folder owned by ''www-data:www-data'' and readable/writable only by that user: cd /data/wwwroot/yoursite mkdir webdav chown www-data:www-data webdav chmod 660 webdav Now you can restart Apache2, see if it restarts ok, and then test your new WebDAV folder. c7601627f04a9e36fd8e81d550eaae643554c3f5 0 1562 2380 2295 2009-02-23T19:42:29Z Saruman! 2 /* Preparations */ described virtualhost behaviour wikitext text/x-wiki ==Preparations== In the following, we'll assume you already have the following packages installed and configured: * Apache2 * MySQL-server * PHP5 (including php5-mysql) Furthermore, you have the following credentials (name and password) or equivalent rights: * root (for installation and configuration of both MediaWiki and Apache2) * MySQL root (for MySQL database creation) Update your APT sources, and run apt-get install mediawiki This installs all mediawiki files, including a default configuration. For your convenience, we've created a [[MediaWiki directory structure]] map. If you run Apache2 (as we recommend), then that is automatically configured (for the most part) as well. By the way, you can reconfigure MediaWiki with ''dpkg-reconfigure'', but that will only ask you for which web servers you'd like to generate a default configuration (those web servers being apache, apache-ssl, apache2 and cherokee). To get Apache2 to serve the Wiki on the default alias ''/mediawiki'', edit ''/etc/mediawiki/apache.conf''. Uncomment the alias line, so that the top of the file looks like this: # Uncomment this to add an alias. # This does not work properly with virtual hosts.. Alias /mediawiki /var/lib/mediawiki Then restart or reload Apache2: invoke-rc.d apache2 reload What does the config file mean with "does not work properly", you might ask? Well, the Mediawiki config file is placed in ''/etc/apache2/conf.d'' using a symlink, so that it is loaded "generally", and not included within any Virtual Host. The consequence is, that the Mediawiki configuration, including the alias, works in ''every'' Virtual Host that you'll configure. If this is not what you want, despair not and just follow these directions. Further on down we will describe how you can fix this potentially unwanted behaviour. Now the MediaWiki instance is being served on your webserver; you should be able to visit ''<nowiki>http://yourserver.lan/mediawiki</nowiki>'', and see the friendly MediaWiki sunflower, and a link to "Please set up the wiki first". ==Configuring the Wiki instance== Clicking the "Please set up the wiki first" link will bring you to a single, long web page, that'll help you to actually create the Wiki instance. The first section contains the result of an environment check. It should end with the sentence "<span style="color:green">'''Environment checked. You can install MediaWiki.'''</span>". If not, then you'll first have to fix whatever is holding back your MediaWiki installation. The rest of the page is one long form. You'll have to provide all data to define your wiki. Questions are a.o. the following. * Site Config questions: ** The Wiki name: Must not be blank or "MediaWiki" and may not contain "#". Preferably a short word without punctuation, i.e. "SaruWiki". Will appear as the namespace name for "meta" pages, and throughout the interface. ** Contact e-mail: Displayed to users in some error messages, used as the return address for password reminders, and used as the default sender address of e-mail notifications. ** Language: determines the wiki interface localization. We only have experience with "en - English" but the pulldown list reveals an impressive list of languages, from "nl - Nederlands" to "jut - Jysk" and from "ak - Akan" to "yo - Yorùbá". ** the Copyright/license: you can have your Wiki display the GNU Free Documentation License, a Creative Commons license (that you'll have to select in a page under a hyperlink), or no license metadata at all. Think careful what you want with the materials that you and others create in your Wiki instance! ** an Admin username and password: the proposed default is ''WikiSysop''. Provide a strong password! * Email notification and authentication setup: ** Email address authentication: if this is enabled, then users have to confirm their e-mail address using a magic link sent to them whenever they set or change it, and only authenticated e-mail addresses can receive mails from other users and/or change notification mails. Setting this option is recommended for public wikis because of potential abuse of the e-mail features just above this particular question. * Database options: ** Database type: You can choose from a list of one, being MySQL :-). ** Database host: can be localhost, if you've installed MySQL on this same machine, but can also be an IP address or a DNS name to a remote MySQL server ** Database name: Here you choose under what name the database will be created in the MySQL server. The default is ''wikidb''. ** Database user: With the MySQL root privileges, we can have the MediaWiki configuration script create a new user within the new database, that has the necessary privileges to enter data in, and read data from, the MySQL database. The proposed name is ''wikiuser'', and you'll have to provide a strong (!) password. ** Superuser account: check the box to signal that you have a root account for the MySQL server, fill in the name (presumably 'root'') and the password, so that the configuration script gets the authority to create the ''wikidb'' database and all necessary users, tables et cetera. * There are some MySQL specific options, most importantly: ** Database table prefix: If you need to share one database between multiple wikis, or between MediaWiki and another web application, you may choose to add a prefix to all the table names to avoid conflicts. Avoid exotic characters; something like mw_ is good. However, if you plan to have only a single wiki, then this box can remain empty. ** Storage Engine: choose between InnoDB and MyISAM. InnoDB is the default. ** Database character set: "Backwards-compatible UTF-8" is the default choice Having provided all the above info, you can click the bottom button optimistically labeled "'''Install MediaWiki!'''". If you left something important empty (e.g. the Wiki name cannot be blank) or gave inconsistant information (two different passwords for "wikiuser"), you're thrown back to the same page with an urgent red box at the top:<br> "<span style="color:red">'''Something's not quite right yet; make sure everything below is filled out correctly.'''</span>".<br> However, when you've gotten it right, you'll see a result page, ending with <span style="color:green">'''Installation successful!'''</span> ==Finishing up the configuration== The above procedure has resulted in a new configuration file ''/var/lib/mediawiki/config/LocalSettings.php'' (owner: ''www-data:www-data''), and in a database in your MySQL server named as you've indicated (presumably ''wikidb'', right?). As the result page indicated, you'll have to now move the ''LocalSettings.php'' file to ''/etc/mediawiki'', and set the permissions so that no-one can mess with that file: cd /etc/mediawiki mv /var/lib/mediawiki/config/LocalSettings.php . chmod 444 LocalSettings.php If you now follow the link to ''<nowiki>http://yourserver.lan/mediawiki</nowiki>'', you'll find yourself on the default start page of your new Wiki instance. You can immediately start using your Wiki, or you can add things like extensions. b2c4754f36e348b72a97a0572cbb4a52a011fdec 2381 2380 2009-02-28T15:03:08Z Saruman! 2 added AdminSettings.php and outlined config files wikitext text/x-wiki ==Preparations== In the following, we'll assume you already have the following packages installed and configured: * Apache2 * MySQL-server * PHP5 (including php5-mysql) Furthermore, you have the following credentials (name and password) or equivalent rights: * root (for installation and configuration of both MediaWiki and Apache2) * MySQL root (for MySQL database creation) Update your APT sources, and run apt-get install mediawiki This installs all mediawiki files, including a default configuration. For your convenience, we've created a [[MediaWiki directory structure]] map. If you run Apache2 (as we recommend), then that is automatically configured (for the most part) as well. By the way, you can reconfigure MediaWiki with ''dpkg-reconfigure'', but that will only ask you for which web servers you'd like to generate a default configuration (those web servers being apache, apache-ssl, apache2 and cherokee). To get Apache2 to serve the Wiki on the default alias ''/mediawiki'', edit ''/etc/mediawiki/apache.conf''. Uncomment the alias line, so that the top of the file looks like this: # Uncomment this to add an alias. # This does not work properly with virtual hosts.. Alias /mediawiki /var/lib/mediawiki Then restart or reload Apache2: invoke-rc.d apache2 reload What does the config file mean with "does not work properly", you might ask? Well, the Mediawiki config file is placed in ''/etc/apache2/conf.d'' using a symlink, so that it is loaded "generally", and not included within any Virtual Host. The consequence is, that the Mediawiki configuration, including the alias, works in ''every'' Virtual Host that you'll configure. If this is not what you want, despair not and just follow these directions. Further on down we will describe how you can fix this potentially unwanted behaviour. Now the MediaWiki instance is being served on your webserver; you should be able to visit ''<nowiki>http://yourserver.lan/mediawiki</nowiki>'', and see the friendly MediaWiki sunflower, and a link to "Please set up the wiki first". ==Configuring the Wiki instance== Clicking the "Please set up the wiki first" link will bring you to a single, long web page, that'll help you to actually create the Wiki instance. The first section contains the result of an environment check. It should end with the sentence "<span style="color:green">'''Environment checked. You can install MediaWiki.'''</span>". If not, then you'll first have to fix whatever is holding back your MediaWiki installation. The rest of the page is one long form. You'll have to provide all data to define your wiki. Questions are a.o. the following. * Site Config questions: ** The Wiki name: Must not be blank or "MediaWiki" and may not contain "#". Preferably a short word without punctuation, i.e. "SaruWiki". Will appear as the namespace name for "meta" pages, and throughout the interface. ** Contact e-mail: Displayed to users in some error messages, used as the return address for password reminders, and used as the default sender address of e-mail notifications. ** Language: determines the wiki interface localization. We only have experience with "en - English" but the pulldown list reveals an impressive list of languages, from "nl - Nederlands" to "jut - Jysk" and from "ak - Akan" to "yo - Yorùbá". ** the Copyright/license: you can have your Wiki display the GNU Free Documentation License, a Creative Commons license (that you'll have to select in a page under a hyperlink), or no license metadata at all. Think careful what you want with the materials that you and others create in your Wiki instance! ** an Admin username and password: the proposed default is ''WikiSysop''. Provide a strong password! * Email notification and authentication setup: ** Email address authentication: if this is enabled, then users have to confirm their e-mail address using a magic link sent to them whenever they set or change it, and only authenticated e-mail addresses can receive mails from other users and/or change notification mails. Setting this option is recommended for public wikis because of potential abuse of the e-mail features just above this particular question. * Database options: ** Database type: You can choose from a list of one, being MySQL :-). ** Database host: can be localhost, if you've installed MySQL on this same machine, but can also be an IP address or a DNS name to a remote MySQL server ** Database name: Here you choose under what name the database will be created in the MySQL server. The default is ''wikidb''. ** Database user: With the MySQL root privileges, we can have the MediaWiki configuration script create a new user within the new database, that has the necessary privileges to enter data in, and read data from, the MySQL database. The proposed name is ''wikiuser'', and you'll have to provide a strong (!) password. ** Superuser account: check the box to signal that you have a root account for the MySQL server, fill in the name (presumably 'root'') and the password, so that the configuration script gets the authority to create the ''wikidb'' database and all necessary users, tables et cetera. * There are some MySQL specific options, most importantly: ** Database table prefix: If you need to share one database between multiple wikis, or between MediaWiki and another web application, you may choose to add a prefix to all the table names to avoid conflicts. Avoid exotic characters; something like mw_ is good. However, if you plan to have only a single wiki, then this box can remain empty. ** Storage Engine: choose between InnoDB and MyISAM. InnoDB is the default. ** Database character set: "Backwards-compatible UTF-8" is the default choice Having provided all the above info, you can click the bottom button optimistically labeled "'''Install MediaWiki!'''". If you left something important empty (e.g. the Wiki name cannot be blank) or gave inconsistant information (two different passwords for "wikiuser"), you're thrown back to the same page with an urgent red box at the top:<br> "<span style="color:red">'''Something's not quite right yet; make sure everything below is filled out correctly.'''</span>".<br> However, when you've gotten it right, you'll see a result page, ending with <span style="color:green">'''Installation successful!'''</span> ==Finishing up the configuration== The above procedure has resulted in a new configuration file ''/var/lib/mediawiki/config/LocalSettings.php'' (owner: ''www-data:www-data''), and in a database in your MySQL server named as you've indicated (presumably ''wikidb'', right?). As the result page indicated, you'll have to now move the ''LocalSettings.php'' file to ''/etc/mediawiki'', and set the permissions so that no-one can mess with that file: cd /etc/mediawiki mv /var/lib/mediawiki/config/LocalSettings.php . chmod 444 LocalSettings.php If you now follow the link to ''<nowiki>http://yourserver.lan/mediawiki</nowiki>'', you'll find yourself on the default start page of your new Wiki instance. You can immediately start using your Wiki, or you can add things like extensions. Furthermore, should you ever need to run a maintenance script (contained in ''/var/lib/mediawiki/maintenance'') you will want to provide those scripts with the database admin password. To this end, copy ''/usr/share/doc/mediawiki/examples/AdminSettings.sample'' to ''/etc/mediawiki/AdminSettings.php''. Then, secure this file by ''chmod''ding it to 600 and ''chown''ing it to ''root:root''. Finally, put in the MySQL root database user, something like $wgDBadminuser = 'root'; $wgDBadminpassword = 'waYacUbaT2uW'; Of course, you need to put in ''your'' MySQL root user data. Furthermore, you'll probably understand that you need to be ''really'' careful with this data. ==The configuration files for MediaWiki under Debian== When you've installed MediaWiki under Debian, the configuration of it is contained in the following files and databases: * ''/etc/mediawiki/LocalSettings.php'' - exists only after configuration is completed; contains the settings PHP needs to run all its PHP scripts according to your wishes for your wiki. * ''/etc/mediawiki/AdminSettings.php'' - optional configuration to facilitate using maintenance scripts. * ''/etc/mediawiki/apache.conf'' - contains the Apache2 configuration lines. * MySQL database ''wikidb'' - exists only after configuration is completed; contains the wiki content itself. 82b9a03e3b131044a791d87f74b890ea4c9631b1 0 1561 2382 2332 2009-03-01T08:27:37Z Saruman! 2 wikifarm explanation added wikitext text/x-wiki ==On Wikifarms== ===What is a Wikifarm?=== Wikifarm and the verb Wikifarming refer to the setup and operation of multiple wikis on a single server. This could be because on a single website you want to run multiple wikis (e.g. ''<nowiki>http://www.saruman.biz/linuxwiki</nowiki>'' and ''<nowiki>http://www.saruman.biz/bsdwiki</nowiki>''). Or it could be because you're running multiple websites on a single server (each behind its own IP, or all on the same IP number using virtual hosts), and more than one of these websites needs to have its own wiki. ===Types of Wikifarms=== There are multiple ways to set up a wikifarm; what is the most suitable way for you depends on how you want to use the farm. We can roughly distinguish the following type of farms: * Multiple wikis, each running '''their own code and their own database'''. This is simple to set up when you install the Wiki code base from source - funny enough, under Debian it's ''not'' easy. Also, it's not a recommendable solution from the perspective of maintenance: each wiki must be updated separately when e.g. a security patch is issued for the wiki software. * Multiple wikis, running on '''a shared code base, but each with their own database'''. This is a good solution for multiple wikis for multiple websites. * Multiple wikis, running on '''a shared code base, and on a shared database'''. This could be a good solution for multiple wikis for a single website, because a user can register on one wiki, and automatically have the same account in the other database as well. ==The standard Debian MediaWiki structure== ==Recreating (moving over) your first MediaWiki instance== We'll assume you've followed the other tips in this wiki. Most notably, you've taken all steps described in the article on "how to [[Place MediaWiki inside a Virtual Host]]". The steps are simple ===Move the Wiki configuration within /etc=== Your Wiki config file will be ''/etc/mediawiki/LocalSettings.php'', and the settings for Apache2 will be in ''/etc/mediawiki/apache.conf''. We'll create a subdirectory under ''/etc/mediawiki'' that hosts the configuration of your Wiki. Suppose we name the subdirectory after the Wiki we're handling, in this example the SaruWiki. Furthermore, suppose that you also have an ''AdminSettings.php'' file. If you don't: no worries! Just skip the steps involved with that file! cd /etc/mediawiki mkdir SaruWiki mv LocalSettings.php SaruWiki mv AdminSettings.php SaruWiki mv apache.conf Saruwiki Note: make sure that after moving the files, the owner and permissions are the same. Moving a file while you are ''root'' has the effect of changing ownership to ''root''. ''LocalSettings.php'' must be owned by user:group ''www-data:www-data'' in order for Apache2 to be able to read the file. The ''AdminSettings.php'' file, if it exists, must be owned by ''root:root'' and NOT be readable by world (permissions 600) because it should contain the MySQL "root" username and password, with which maintenance scripts can perform their tasks if you instruct them to (while you are root, of course). To keep the Wiki running, we're going to need to tell Apache2 where the two files went to. In this case: * change the path to ''apache.conf'' in the ''Include'' statement in the site declaration (e.g. in ''/etc/apache2/sites-available/000-saruman.biz'', change the ''Include'' line to Include /etc/mediawiki/SaruWiki/apache.conf * change the symlink in ''/var/lib/mediawiki'' that points to ''LocalSettings.php''; and if you have one, change the ''AdminSettings.php'' symlink as well: cd /var/lib/mediawiki unlink LocalSettings.php ln -s /etc/mediawiki/SaruWiki/LocalSettings.php unlink AdminSettings.php ln -s /etc/mediawiki/SaruWiki/AdminSettings.php If you now restart Apache2, your Wiki will still work - but the two primary configuration files have moved over to a dedicated spot. ===Move the Wiki website=== As you can see from the [[MediaWiki directory structure]], the code that is actually served in the webserver is in two separate trees: by default the webserver ''thinks'' the full tree is in ''/var/lib/mediawiki'', but a large part of what you find in that spot is actually symlinked to files and directories in ''/usr/share/mediawiki''. Actually, the tree ''/usr/share/mediawiki'' can be thought of as a source code library, and ''/var/lib/mediawiki'' as the instance that we're actually serving. Since an instance needs both source code and some files of its own, we find that ''/var/lib/mediawiki'' contains both links to that source code, as well as actual files and directories. So what we now need to do, is to tell the webserver that the full tree can be served from elsewhere, and in that spot "elsewhere" create symlinks to the right spots. Let's begin with the latter. Let's assume we wish to move our default Wiki instance to ''/data/wikifarm/SaruWiki''. Other instances could then run under ''/data/wikifarm/<instancename>''. We now first create the links to the ''/usr/share/mediawiki'' files as we see them in the ''/var/lib/mediawiki'' instance: cd /data/wikifarm/SaruWiki for i in /usr/share/mediawiki/*.php; do > ln -s $i > done unlink AdminSettings.php unlink LocalSettings.php ln -s /usr/share/mediawiki/*.phtml ln -s /usr/share/mediawiki/install-utils.inc ln -s /usr/share/mediawiki/includes ln -s /usr/share/mediawiki/languages ln -s /usr/share/mediawiki/maintenance ln -s /usr/share/mediawiki/skins Next, we create the directories that contain the instance-specific files, i.e. the files that belong to this one member of the Wiki farm. This includes the ''images'' directory, where users of this wiki instance can upload their images. mkdir images chown www-data:www-data images mkdir config chown www-data:www-data config cp -P /var/lib/mediawiki/config/* . ==Adding MediaWiki instances to your farm== 40bd791c5a39f50c25e9ab7ac5e0daa2bc105d5c 2383 2382 2009-03-01T09:14:34Z Saruman! 2 added structure extension wikitext text/x-wiki ==On Wikifarms== ===What is a Wikifarm?=== Wikifarm and the verb Wikifarming refer to the setup and operation of multiple wikis on a single server. This could be because on a single website you want to run multiple wikis (e.g. ''<nowiki>http://www.saruman.biz/linuxwiki</nowiki>'' and ''<nowiki>http://www.saruman.biz/bsdwiki</nowiki>''). Or it could be because you're running multiple websites on a single server (each behind its own IP, or all on the same IP number using virtual hosts), and more than one of these websites needs to have its own wiki. ===Types of Wikifarms=== There are multiple ways to set up a wikifarm; what is the most suitable way for you depends on how you want to use the farm. We can roughly distinguish the following type of farms: * Multiple wikis, each running '''their own code and their own database'''. This is simple to set up when you install the Wiki code base from source - funny enough, under Debian it's ''not'' easy. Also, it's not a recommendable solution from the perspective of maintenance: each wiki must be updated separately when e.g. a security patch is issued for the wiki software. * Multiple wikis, running on '''a shared code base, but each with their own database'''. This is a good solution for multiple wikis for multiple websites. * Multiple wikis, running on '''a shared code base, and on a shared database'''. This could be a good solution for multiple wikis for a single website, because a user can register on one wiki, and automatically have the same account in the other database as well. We're not going to go into the first type, since the shared codebase is more maintainable. Instead, we're going to show how you can share the Mediawiki code base under Debian, so that a Debian update to the Mediawiki package is automatically applied to all instances of your wikifarm. And we'll see that from there, the choice between separate databases or shared databases is quite trivial. ==Debian Mediawiki wikifarm structure== ===The standard Debian MediaWiki structure=== After installation of the ''mediawiki'' package, your server will be expanded with the [[MediaWiki directory structure]]. Within this structure, there are four main branches (if you haven't installed the ''mediawiki-extensions'' package yet): * ''/etc/mediawiki'' contains the configuration files for MediaWiki. * ''/usr/share/doc/mediawiki'' contains the documentation files. * ''/usr/share/mediawiki'' contains the source code. It is not used directly, rather it is linked to from the ''/var/lib/mediawiki'' directory. * ''/var/lib/mediawiki'' contains the site, including links to the configuration files in ''/etc/mediawiki''. Within these branches, we should not delete or move any file or directory, since that will confuse our [[APT|Debian package manager]] when an update to the ''mediawiki'' package becomes available, so we strive to minimize the changes to this structure. ===Extending the structure for a wikifarm=== First we need a label, a name for each wikifarm, so that we can label the wiki instances we're creating. Each name needs to be unique because we're going to create directories based on the labels. Note that this label need NOT be the Wiki name, as you fill it in when [[Basic_MediaWiki_Installation#Configuring_the_Wiki_instance|configuring the wiki instance]]. In our example, we use the domain name of the website on which the wiki instance is running. Furthermore, you need a database name for each wiki instance that gets its own database. You could use the label you've chosen, or different ones, or derived ones. Remember to observe the MySQL [http://dev.mysql.com/doc/refman/5.0/en/identifiers.html limits on database names] (no more than 64 characters, no slashes or dots in the name, not ending in a space et cetera). Thus, you could have labels and database names like this: * saruman.biz and saruman-biz-wiki * iceditch.nl and iceditchNLwiki * ann.example.org and wiki-ann * bob.example.org and wiki-bob * charles.example.org wiki-charles And remember, they are just labels. You could just as easily use user names, numbers or whatever. For maintainability though, we recommend recognizable labels. On the other hand, there are a number of labels you must avoid, because they will come to conflict with directories that already exist: most notably ''config'', ''extensions'' and ''images''. So before you begin, sit down and write out what your label and database name convention will be. This is trivial if you have just a handful of wikis, but can become very important when you've got hundreds of instances. Each wikifarm will need its own set of configuration files, so for each new wiki instance we'll create directories under ''/etc/mediawiki'' using the chosen wiki labels: * ''/etc/mediawiki/saruman.biz'' * ''/etc/mediawiki/iceditch.nl'' * et cetera. Make each of these directories owned by the Apache2 user (''chmod www-data:www-data saruman.biz'' et cetera). Each wikifarm will need its own code base, so for each new wiki instance we'll create directories under ''/var/lib/mediawiki'' using the wiki labels: * ''/var/lib/mediawiki/saruman.biz'' * ''/var/lib/mediawiki/iceditch.nl'' * et cetera. ==Linking to the shared code base== Now we can create links to the code base for each wikifarm instance. ==Recreating (moving over) your first MediaWiki instance== We'll assume you've followed the other tips in this wiki. Most notably, you've taken all steps described in the article on "how to [[Place MediaWiki inside a Virtual Host]]". The steps are simple ===Move the Wiki configuration within /etc=== Your Wiki config file will be ''/etc/mediawiki/LocalSettings.php'', and the settings for Apache2 will be in ''/etc/mediawiki/apache.conf''. We'll create a subdirectory under ''/etc/mediawiki'' that hosts the configuration of your Wiki. Suppose we name the subdirectory after the Wiki we're handling, in this example the SaruWiki. Furthermore, suppose that you also have an ''AdminSettings.php'' file. If you don't: no worries! Just skip the steps involved with that file! cd /etc/mediawiki mkdir SaruWiki mv LocalSettings.php SaruWiki mv AdminSettings.php SaruWiki mv apache.conf Saruwiki Note: make sure that after moving the files, the owner and permissions are the same. Moving a file while you are ''root'' has the effect of changing ownership to ''root''. ''LocalSettings.php'' must be owned by user:group ''www-data:www-data'' in order for Apache2 to be able to read the file. The ''AdminSettings.php'' file, if it exists, must be owned by ''root:root'' and NOT be readable by world (permissions 600) because it should contain the MySQL "root" username and password, with which maintenance scripts can perform their tasks if you instruct them to (while you are root, of course). To keep the Wiki running, we're going to need to tell Apache2 where the two files went to. In this case: * change the path to ''apache.conf'' in the ''Include'' statement in the site declaration (e.g. in ''/etc/apache2/sites-available/000-saruman.biz'', change the ''Include'' line to Include /etc/mediawiki/SaruWiki/apache.conf * change the symlink in ''/var/lib/mediawiki'' that points to ''LocalSettings.php''; and if you have one, change the ''AdminSettings.php'' symlink as well: cd /var/lib/mediawiki unlink LocalSettings.php ln -s /etc/mediawiki/SaruWiki/LocalSettings.php unlink AdminSettings.php ln -s /etc/mediawiki/SaruWiki/AdminSettings.php If you now restart Apache2, your Wiki will still work - but the two primary configuration files have moved over to a dedicated spot. ===Move the Wiki website=== As you can see from the [[MediaWiki directory structure]], the code that is actually served in the webserver is in two separate trees: by default the webserver ''thinks'' the full tree is in ''/var/lib/mediawiki'', but a large part of what you find in that spot is actually symlinked to files and directories in ''/usr/share/mediawiki''. Actually, the tree ''/usr/share/mediawiki'' can be thought of as a source code library, and ''/var/lib/mediawiki'' as the instance that we're actually serving. Since an instance needs both source code and some files of its own, we find that ''/var/lib/mediawiki'' contains both links to that source code, as well as actual files and directories. So what we now need to do, is to tell the webserver that the full tree can be served from elsewhere, and in that spot "elsewhere" create symlinks to the right spots. Let's begin with the latter. Let's assume we wish to move our default Wiki instance to ''/data/wikifarm/SaruWiki''. Other instances could then run under ''/data/wikifarm/<instancename>''. We now first create the links to the ''/usr/share/mediawiki'' files as we see them in the ''/var/lib/mediawiki'' instance: cd /data/wikifarm/SaruWiki for i in /usr/share/mediawiki/*.php; do > ln -s $i > done unlink AdminSettings.php unlink LocalSettings.php ln -s /usr/share/mediawiki/*.phtml ln -s /usr/share/mediawiki/install-utils.inc ln -s /usr/share/mediawiki/includes ln -s /usr/share/mediawiki/languages ln -s /usr/share/mediawiki/maintenance ln -s /usr/share/mediawiki/skins Next, we create the directories that contain the instance-specific files, i.e. the files that belong to this one member of the Wiki farm. This includes the ''images'' directory, where users of this wiki instance can upload their images. mkdir images chown www-data:www-data images mkdir config chown www-data:www-data config cp -P /var/lib/mediawiki/config/* . ==Adding MediaWiki instances to your farm== f6ce3531a5b62633834de0a3ba993c21aab7f96e 2384 2383 2009-03-02T17:40:57Z Saruman! 2 /* Extending the structure for a wikifarm */ added images dir wikitext text/x-wiki ==On Wikifarms== ===What is a Wikifarm?=== Wikifarm and the verb Wikifarming refer to the setup and operation of multiple wikis on a single server. This could be because on a single website you want to run multiple wikis (e.g. ''<nowiki>http://www.saruman.biz/linuxwiki</nowiki>'' and ''<nowiki>http://www.saruman.biz/bsdwiki</nowiki>''). Or it could be because you're running multiple websites on a single server (each behind its own IP, or all on the same IP number using virtual hosts), and more than one of these websites needs to have its own wiki. ===Types of Wikifarms=== There are multiple ways to set up a wikifarm; what is the most suitable way for you depends on how you want to use the farm. We can roughly distinguish the following type of farms: * Multiple wikis, each running '''their own code and their own database'''. This is simple to set up when you install the Wiki code base from source - funny enough, under Debian it's ''not'' easy. Also, it's not a recommendable solution from the perspective of maintenance: each wiki must be updated separately when e.g. a security patch is issued for the wiki software. * Multiple wikis, running on '''a shared code base, but each with their own database'''. This is a good solution for multiple wikis for multiple websites. * Multiple wikis, running on '''a shared code base, and on a shared database'''. This could be a good solution for multiple wikis for a single website, because a user can register on one wiki, and automatically have the same account in the other database as well. We're not going to go into the first type, since the shared codebase is more maintainable. Instead, we're going to show how you can share the Mediawiki code base under Debian, so that a Debian update to the Mediawiki package is automatically applied to all instances of your wikifarm. And we'll see that from there, the choice between separate databases or shared databases is quite trivial. ==Debian Mediawiki wikifarm structure== ===The standard Debian MediaWiki structure=== After installation of the ''mediawiki'' package, your server will be expanded with the [[MediaWiki directory structure]]. Within this structure, there are four main branches (if you haven't installed the ''mediawiki-extensions'' package yet): * ''/etc/mediawiki'' contains the configuration files for MediaWiki. * ''/usr/share/doc/mediawiki'' contains the documentation files. * ''/usr/share/mediawiki'' contains the source code. It is not used directly, rather it is linked to from the ''/var/lib/mediawiki'' directory. * ''/var/lib/mediawiki'' contains the site, including links to the configuration files in ''/etc/mediawiki''. Within these branches, we should not delete or move any file or directory, since that will confuse our [[APT|Debian package manager]] when an update to the ''mediawiki'' package becomes available, so we strive to minimize the changes to this structure. ===Extending the structure for a wikifarm=== First we need a label, a name for each wikifarm, so that we can label the wiki instances we're creating. Each name needs to be unique because we're going to create directories based on the labels. Note that this label need NOT be the Wiki name, as you fill it in when [[Basic_MediaWiki_Installation#Configuring_the_Wiki_instance|configuring the wiki instance]]. In our example, we use the domain name of the website on which the wiki instance is running. Furthermore, you need a database name for each wiki instance that gets its own database. You could use the label you've chosen, or different ones, or derived ones. Remember to observe the MySQL [http://dev.mysql.com/doc/refman/5.0/en/identifiers.html limits on database names] (no more than 64 characters, no slashes or dots in the name, not ending in a space et cetera). Thus, you could have labels and database names like this: * saruman.biz and saruman-biz-wiki * iceditch.nl and iceditchNLwiki * ann.example.org and wiki-ann * bob.example.org and wiki-bob * charles.example.org wiki-charles And remember, they are just labels. You could just as easily use user names, numbers or whatever. For maintainability though, we recommend recognizable labels. On the other hand, there are a number of labels you must avoid, because they will come to conflict with directories that already exist: most notably ''config'', ''extensions'' and ''images''. So before you begin, sit down and write out what your label and database name convention will be. This is trivial if you have just a handful of wikis, but can become very important when you've got hundreds of instances. Each wikifarm will need its own set of configuration files, so for each new wiki instance we'll create directories under ''/etc/mediawiki'' using the chosen wiki labels: * ''/etc/mediawiki/saruman.biz'' * ''/etc/mediawiki/iceditch.nl'' * et cetera. Make each of these directories owned by the Apache2 user (''chmod www-data:www-data saruman.biz'' et cetera). Each wikifarm will need its own code base, so for each new wiki instance we'll create directories under ''/opt/mediawikifarm'' using the wiki labels: * ''/opt/mediawikifarm/saruman.biz'' * ''/opt/mediawikifarm/iceditch.nl'' * et cetera. The choice for ''/opt/mediawikifarm'' is quite arbitrary; one could make a case to use ''/var/www'' or ''/var/lib/mediawikifarm/'' or anything like this, but ''/opt'' is meant for optional software, which under Debian is software that's not in the standard repositories. And since the wikifarm isn't, it makes sense to create the links to the codebase there. Each wikifarm may have its own upload directory for images. This directory should not be placed under ''/opt'', but rather in a place where you expect data, e.g. ''/data'' if you have that, or ''/var/www'', or something like this. We have chosen for ''/data/wikifarm/<wikilabel>/images''. ==Linking to the shared code base== Now we can create links to the code base for each wikifarm instance. ==Recreating (moving over) your first MediaWiki instance== We'll assume you've followed the other tips in this wiki. Most notably, you've taken all steps described in the article on "how to [[Place MediaWiki inside a Virtual Host]]". The steps are simple ===Move the Wiki configuration within /etc=== Your Wiki config file will be ''/etc/mediawiki/LocalSettings.php'', and the settings for Apache2 will be in ''/etc/mediawiki/apache.conf''. We'll create a subdirectory under ''/etc/mediawiki'' that hosts the configuration of your Wiki. Suppose we name the subdirectory after the Wiki we're handling, in this example the SaruWiki. Furthermore, suppose that you also have an ''AdminSettings.php'' file. If you don't: no worries! Just skip the steps involved with that file! cd /etc/mediawiki mkdir SaruWiki mv LocalSettings.php SaruWiki mv AdminSettings.php SaruWiki mv apache.conf Saruwiki Note: make sure that after moving the files, the owner and permissions are the same. Moving a file while you are ''root'' has the effect of changing ownership to ''root''. ''LocalSettings.php'' must be owned by user:group ''www-data:www-data'' in order for Apache2 to be able to read the file. The ''AdminSettings.php'' file, if it exists, must be owned by ''root:root'' and NOT be readable by world (permissions 600) because it should contain the MySQL "root" username and password, with which maintenance scripts can perform their tasks if you instruct them to (while you are root, of course). To keep the Wiki running, we're going to need to tell Apache2 where the two files went to. In this case: * change the path to ''apache.conf'' in the ''Include'' statement in the site declaration (e.g. in ''/etc/apache2/sites-available/000-saruman.biz'', change the ''Include'' line to Include /etc/mediawiki/SaruWiki/apache.conf * change the symlink in ''/var/lib/mediawiki'' that points to ''LocalSettings.php''; and if you have one, change the ''AdminSettings.php'' symlink as well: cd /var/lib/mediawiki unlink LocalSettings.php ln -s /etc/mediawiki/SaruWiki/LocalSettings.php unlink AdminSettings.php ln -s /etc/mediawiki/SaruWiki/AdminSettings.php If you now restart Apache2, your Wiki will still work - but the two primary configuration files have moved over to a dedicated spot. ===Move the Wiki website=== As you can see from the [[MediaWiki directory structure]], the code that is actually served in the webserver is in two separate trees: by default the webserver ''thinks'' the full tree is in ''/var/lib/mediawiki'', but a large part of what you find in that spot is actually symlinked to files and directories in ''/usr/share/mediawiki''. Actually, the tree ''/usr/share/mediawiki'' can be thought of as a source code library, and ''/var/lib/mediawiki'' as the instance that we're actually serving. Since an instance needs both source code and some files of its own, we find that ''/var/lib/mediawiki'' contains both links to that source code, as well as actual files and directories. So what we now need to do, is to tell the webserver that the full tree can be served from elsewhere, and in that spot "elsewhere" create symlinks to the right spots. Let's begin with the latter. Let's assume we wish to move our default Wiki instance to ''/data/wikifarm/SaruWiki''. Other instances could then run under ''/data/wikifarm/<instancename>''. We now first create the links to the ''/usr/share/mediawiki'' files as we see them in the ''/var/lib/mediawiki'' instance: cd /data/wikifarm/SaruWiki for i in /usr/share/mediawiki/*.php; do > ln -s $i > done unlink AdminSettings.php unlink LocalSettings.php ln -s /usr/share/mediawiki/*.phtml ln -s /usr/share/mediawiki/install-utils.inc ln -s /usr/share/mediawiki/includes ln -s /usr/share/mediawiki/languages ln -s /usr/share/mediawiki/maintenance ln -s /usr/share/mediawiki/skins Next, we create the directories that contain the instance-specific files, i.e. the files that belong to this one member of the Wiki farm. This includes the ''images'' directory, where users of this wiki instance can upload their images. mkdir images chown www-data:www-data images mkdir config chown www-data:www-data config cp -P /var/lib/mediawiki/config/* . ==Adding MediaWiki instances to your farm== 9db9bc020c4753497062178ef2a4c0724a216468 2385 2384 2009-03-04T08:49:34Z Saruman! 2 laid in the wikifarm procedure wikitext text/x-wiki ==On Wikifarms== ===What is a Wikifarm?=== Wikifarm and the verb Wikifarming refer to the setup and operation of multiple wikis on a single server. This could be because on a single website you want to run multiple wikis (e.g. ''<nowiki>http://www.saruman.biz/linuxwiki</nowiki>'' and ''<nowiki>http://www.saruman.biz/bsdwiki</nowiki>''). Or it could be because you're running multiple websites on a single server (each behind its own IP, or all on the same IP number using virtual hosts), and more than one of these websites needs to have its own wiki. ===Types of Wikifarms=== There are multiple ways to set up a wikifarm; what is the most suitable way for you depends on how you want to use the farm. We can roughly distinguish the following type of farms: * Multiple wikis, each running '''their own code and their own database'''. This is simple to set up when you install the Wiki code base from source - funny enough, under Debian it's ''not'' easy. Also, it's not a recommendable solution from the perspective of maintenance: each wiki must be updated separately when e.g. a security patch is issued for the wiki software. * Multiple wikis, running on '''a shared code base, but each with their own database'''. This is a good solution for multiple wikis for multiple websites. * Multiple wikis, running on '''a shared code base, and on a shared database'''. This could be a good solution for multiple wikis for a single website, because a user can register on one wiki, and automatically have the same account in the other database as well. We're not going to go into the first type, since the shared codebase is more maintainable. Instead, we're going to show how you can share the Mediawiki code base under Debian, so that a Debian update to the Mediawiki package is automatically applied to all instances of your wikifarm. And we'll see that from there, the choice between separate databases or shared databases is quite trivial. ===Wikifarming under Debian=== As with most Linux-based software packages, the MediaWiki package ''mediawiki'' that Debian offers is modified to suit the Debian policies and needs. This means that it has moved all configuration files to reside under ''/etc/mediawiki'', but also that it offers a somewhat better way to include extensions. The downside of these modifications is that creating a wikifarm under Debian is somewhat more complicated than when you're using vanilla MediaWiki sources - mostly because there isn't much documentation on the Internet about it. In the following we'll be documenting one possible way to create a wikifarm. Note that our method is particularly well-suited to "small" wikifarms (a handful of wikis on a single server), and not exactly fit for "big" wikifarms (thousands of wikis on one or more servers). ==General procedure to creat a wikifarm wiki instance== Setting up a wiki under Debian is quite easy - as you might have seen from this wiki's description under entry [[Basic MediaWiki Installation]]. This is because the Debian customization includes specific changes to some MediaWiki files, and to the default configuration files. Thus, the usual methods of creating a wiki instance next to the default one run into an additional obstacle: the forementioned Debian customizations. The way around it is this: * We suppose you've already installed your first wiki. It'll probably be just as described in the [[Basic MediaWiki Installation]]. * Make sure you adapt this first wiki to support virtual hosts, as described in the section on [[Place_MediaWiki_inside_a_Virtual_Host|placing MediaWiki inside a Virtual Host]]. * If your first wiki is running OK, follow the instructions in the next set of sections to move the wiki from its default place to the wikifarm. As a result, your first wiki should still run OK, but the place where Debian expects your wiki to live is now "empty" again * Set up your second wiki as if it were the first one, and move it over to the wiki farm. * et cetera. Because of the manual work involved, this system is not very well suited to "big" wikifarms; for those instances you'd be better off with one of the scripts that creates the wikifarm instance, and populates it with a default database and default configuration file. Scripts and instructions can be found on the Internet, like this one [http://www.jirp.nl/2008/04/11/mediawiki-farm-multiple-wiki/ on jirp.nl].<br> However, the method is quite doable when you've only got a handful of wikis to create, and remains largely compatible with Debians mechanisms for updating packages. ==Debian Mediawiki wikifarm structure== ===The standard Debian MediaWiki structure=== After installation of the ''mediawiki'' package, your server will be expanded with the [[MediaWiki directory structure]]. Within this structure, there are four main branches (if you haven't installed the ''mediawiki-extensions'' package yet): * ''/etc/mediawiki'' contains the configuration files for MediaWiki. * ''/usr/share/doc/mediawiki'' contains the documentation files. * ''/usr/share/mediawiki'' contains the source code. It is not used directly, rather it is linked to from the ''/var/lib/mediawiki'' directory. * ''/var/lib/mediawiki'' contains the site, including links to the configuration files in ''/etc/mediawiki''. Within these branches, we should not delete or move any file or directory, since that will confuse our [[APT|Debian package manager]] when an update to the ''mediawiki'' package becomes available, so we strive to minimize the changes to this structure. Furthermore, the default configuration files explicitly declare the wiki to "live" in ''/var/lib/mediawiki'', so we'll designate the wiki in that location as the "default wiki" as opposed by "wikifarm instances" that live e.g. under ''/var/wikifarm/<instancename>''. ===Extending the structure for a wikifarm=== First we need a label <instancename>, which designates the name for each wikifarm instance, so that we can label them as we're creating them. Each name needs to be unique because we're going to create directories based on the labels. Note that this label need not be the Wiki name, as you fill it in when [[Basic_MediaWiki_Installation#Configuring_the_Wiki_instance|configuring the default wiki instance]], although you could of course use that name. In our example, we use the domain name of the website on which the wiki instance is running. Thus, this wiki named "SaruWiki" is instance "saruman.biz" in our little wikifarm. Furthermore, you need a database name for each wiki instance that gets its own database, and it should be different from the default database name "wikidb" (unless you ''want'' to put your wiki instance into this default database, together with the wiki or wikis that are already in there). You could use the label you've chosen, or different ones, or derived ones. Remember to observe the MySQL [http://dev.mysql.com/doc/refman/5.0/en/identifiers.html limits on database names] (no more than 64 characters, no slashes or dots in the name, not ending in a space et cetera). Thus, you could have labels and database names like this: * saruman.biz and saruman-biz-wiki * iceditch.nl and iceditchNLwiki * ann.example.org and wiki-ann * bob.example.org and wiki-bob * charles.example.org and wikiCharles And remember, they are just labels. You could just as easily use user names, numbers or whatever. For maintainability though, we recommend a consistent scheme with recognizable labels. On the other hand, there are a number of labels you must avoid, because they will come to conflict with directories that already exist: most notably ''config'', ''extensions'' and ''images''. So before you begin, sit down and write out what your label and database name convention will be. This is trivial if you have just a handful of wikis, but can become very important should you ever grow to hundreds of instances. Each wikifarm will need its own set of configuration files, so for each new wiki instance we'll create directories under ''/etc/mediawiki'' using the chosen wiki labels: * ''/etc/mediawiki/saruman.biz'' * ''/etc/mediawiki/iceditch.nl'' * et cetera. Make each of these directories owned by the Apache2 user (''chmod www-data:www-data saruman.biz'' et cetera). Each wikifarm will need its own code base, so for each new wiki instance we'll create directories under ''/opt/mediawikifarm'' using the wiki labels: * ''/opt/mediawikifarm/saruman.biz'' * ''/opt/mediawikifarm/iceditch.nl'' * et cetera. The choice for ''/opt/mediawikifarm'' is quite arbitrary; one could make a case to use ''/var/www'' or ''/var/lib/mediawikifarm/'' or anything like this, but ''/opt'' is meant for optional software, which under Debian is software that's not in the standard repositories. And since the wikifarm isn't, it makes sense to create the links to the codebase there. Each wikifarm may have its own upload directory for images. This directory should not be placed under ''/opt'', but rather in a place where you expect data, e.g. ''/data'' if you have that, or ''/var/www'', or something like this. We have chosen for ''/data/wikifarm/<wikilabel>/images''. ==Linking to the shared code base== Now we can create links to the code base for each wikifarm instance. ==Recreating (moving over) your first MediaWiki instance== We'll assume you've followed the other tips in this wiki. Most notably, you've taken all steps described in the article on "how to [[Place MediaWiki inside a Virtual Host]]". The steps are simple ===Move the Wiki configuration within /etc=== Your Wiki config file will be ''/etc/mediawiki/LocalSettings.php'', and the settings for Apache2 will be in ''/etc/mediawiki/apache.conf''. We'll create a subdirectory under ''/etc/mediawiki'' that hosts the configuration of your Wiki. Suppose we name the subdirectory after the Wiki we're handling, in this example the SaruWiki. Furthermore, suppose that you also have an ''AdminSettings.php'' file. If you don't: no worries! Just skip the steps involved with that file! cd /etc/mediawiki mkdir SaruWiki mv LocalSettings.php SaruWiki mv AdminSettings.php SaruWiki mv apache.conf Saruwiki Note: make sure that after moving the files, the owner and permissions are the same. Moving a file while you are ''root'' has the effect of changing ownership to ''root''. ''LocalSettings.php'' must be owned by user:group ''www-data:www-data'' in order for Apache2 to be able to read the file. The ''AdminSettings.php'' file, if it exists, must be owned by ''root:root'' and NOT be readable by world (permissions 600) because it should contain the MySQL "root" username and password, with which maintenance scripts can perform their tasks if you instruct them to (while you are root, of course). To keep the Wiki running, we're going to need to tell Apache2 where the two files went to. In this case: * change the path to ''apache.conf'' in the ''Include'' statement in the site declaration (e.g. in ''/etc/apache2/sites-available/000-saruman.biz'', change the ''Include'' line to Include /etc/mediawiki/SaruWiki/apache.conf * change the symlink in ''/var/lib/mediawiki'' that points to ''LocalSettings.php''; and if you have one, change the ''AdminSettings.php'' symlink as well: cd /var/lib/mediawiki unlink LocalSettings.php ln -s /etc/mediawiki/SaruWiki/LocalSettings.php unlink AdminSettings.php ln -s /etc/mediawiki/SaruWiki/AdminSettings.php If you now restart Apache2, your Wiki will still work - but the two primary configuration files have moved over to a dedicated spot. ===Move the Wiki website=== As you can see from the [[MediaWiki directory structure]], the code that is actually served in the webserver is in two separate trees: by default the webserver ''thinks'' the full tree is in ''/var/lib/mediawiki'', but a large part of what you find in that spot is actually symlinked to files and directories in ''/usr/share/mediawiki''. Actually, the tree ''/usr/share/mediawiki'' can be thought of as a source code library, and ''/var/lib/mediawiki'' as the instance that we're actually serving. Since an instance needs both source code and some files of its own, we find that ''/var/lib/mediawiki'' contains both links to that source code, as well as actual files and directories. So what we now need to do, is to tell the webserver that the full tree can be served from elsewhere, and in that spot "elsewhere" create symlinks to the right spots. Let's begin with the latter. Let's assume we wish to move our default Wiki instance to ''/data/wikifarm/SaruWiki''. Other instances could then run under ''/data/wikifarm/<instancename>''. We now first create the links to the ''/usr/share/mediawiki'' files as we see them in the ''/var/lib/mediawiki'' instance: cd /data/wikifarm/SaruWiki for i in /usr/share/mediawiki/*.php; do > ln -s $i > done unlink AdminSettings.php unlink LocalSettings.php ln -s /usr/share/mediawiki/*.phtml ln -s /usr/share/mediawiki/install-utils.inc ln -s /usr/share/mediawiki/includes ln -s /usr/share/mediawiki/languages ln -s /usr/share/mediawiki/maintenance ln -s /usr/share/mediawiki/skins Next, we create the directories that contain the instance-specific files, i.e. the files that belong to this one member of the Wiki farm. This includes the ''images'' directory, where users of this wiki instance can upload their images. mkdir images chown www-data:www-data images mkdir config chown www-data:www-data config cp -P /var/lib/mediawiki/config/* . ==Adding MediaWiki instances to your farm== fd873b4b374182e5bfb71601a9e1a55861c1745c 2386 2385 2009-03-04T11:02:33Z Saruman! 2 shared codebase linking added wikitext text/x-wiki ==On Wikifarms== ===What is a Wikifarm?=== Wikifarm and the verb Wikifarming refer to the setup and operation of multiple wikis on a single server. This could be because on a single website you want to run multiple wikis (e.g. ''<nowiki>http://www.saruman.biz/linuxwiki</nowiki>'' and ''<nowiki>http://www.saruman.biz/bsdwiki</nowiki>''). Or it could be because you're running multiple websites on a single server (each behind its own IP, or all on the same IP number using virtual hosts), and more than one of these websites needs to have its own wiki. ===Types of Wikifarms=== There are multiple ways to set up a wikifarm; what is the most suitable way for you depends on how you want to use the farm. We can roughly distinguish the following type of farms: * Multiple wikis, each running '''their own code and their own database'''. This is simple to set up when you install the Wiki code base from source - funny enough, under Debian it's ''not'' easy. Also, it's not a recommendable solution from the perspective of maintenance: each wiki must be updated separately when e.g. a security patch is issued for the wiki software. * Multiple wikis, running on '''a shared code base, but each with their own database'''. This is a good solution for multiple wikis for multiple websites. * Multiple wikis, running on '''a shared code base, and on a shared database'''. This could be a good solution for multiple wikis for a single website, because a user can register on one wiki, and automatically have the same account in the other database as well. We're not going to go into the first type, since the shared codebase is more maintainable. Instead, we're going to show how you can share the Mediawiki code base under Debian, so that a Debian update to the Mediawiki package is automatically applied to all instances of your wikifarm. And we'll see that from there, the choice between separate databases or shared databases is quite trivial. ===Wikifarming under Debian=== As with most Linux-based software packages, the MediaWiki package ''mediawiki'' that Debian offers is modified to suit the Debian policies and needs. This means that it has moved all configuration files to reside under ''/etc/mediawiki'', but also that it offers a somewhat better way to include extensions. The downside of these modifications is that creating a wikifarm under Debian is somewhat more complicated than when you're using vanilla MediaWiki sources - mostly because there isn't much documentation on the Internet about it. In the following we'll be documenting one possible way to create a wikifarm. Note that our method is particularly well-suited to "small" wikifarms (a handful of wikis on a single server), and not exactly fit for "big" wikifarms (thousands of wikis on one or more servers). ==General procedure to creat a wikifarm wiki instance== Setting up a wiki under Debian is quite easy - as you might have seen from this wiki's description under entry [[Basic MediaWiki Installation]]. This is because the Debian customization includes specific changes to some MediaWiki files, and to the default configuration files. Thus, the usual methods of creating a wiki instance next to the default one run into an additional obstacle: the forementioned Debian customizations. The way around it is this: * We suppose you've already installed your first wiki. It'll probably be just as described in the [[Basic MediaWiki Installation]]. * Make sure you adapt this first wiki to support virtual hosts, as described in the section on [[Place_MediaWiki_inside_a_Virtual_Host|placing MediaWiki inside a Virtual Host]]. * If your first wiki is running OK, follow the instructions in the next set of sections to move the wiki from its default place to the wikifarm. As a result, your first wiki should still run OK, but the place where Debian expects your wiki to live is now "empty" again * Set up your second wiki as if it were the first one, and move it over to the wiki farm. * et cetera. Because of the manual work involved, this system is not very well suited to "big" wikifarms; for those instances you'd be better off with one of the scripts that creates the wikifarm instance, and populates it with a default database and default configuration file. Scripts and instructions can be found on the Internet, like this one [http://www.jirp.nl/2008/04/11/mediawiki-farm-multiple-wiki/ on jirp.nl].<br> However, the method is quite doable when you've only got a handful of wikis to create, and remains largely compatible with Debians mechanisms for updating packages. ==Debian Mediawiki wikifarm structure== ===The standard Debian MediaWiki structure=== After installation of the ''mediawiki'' package, your server will be expanded with the [[MediaWiki directory structure]]. Within this structure, there are four main branches (if you haven't installed the ''mediawiki-extensions'' package yet): * ''/etc/mediawiki'' contains the configuration files for MediaWiki. * ''/usr/share/doc/mediawiki'' contains the documentation files. * ''/usr/share/mediawiki'' contains the source code. It is not used directly, rather it is linked to from the ''/var/lib/mediawiki'' directory. * ''/var/lib/mediawiki'' contains the site, including links to the configuration files in ''/etc/mediawiki''. Within these branches, we should not delete or move any file or directory, since that will confuse our [[APT|Debian package manager]] when an update to the ''mediawiki'' package becomes available, so we strive to minimize the changes to this structure. Furthermore, the default configuration files explicitly declare the wiki to "live" in ''/var/lib/mediawiki'', so we'll designate the wiki in that location as the "default wiki" as opposed by "wikifarm instances" that live e.g. under ''/var/wikifarm/<instancename>''. ===Extending the structure for a wikifarm=== First we need a label <instancename>, which designates the name for each wikifarm instance, so that we can label them as we're creating them. Each name needs to be unique because we're going to create directories based on the labels. Note that this label need not be the Wiki name, as you fill it in when [[Basic_MediaWiki_Installation#Configuring_the_Wiki_instance|configuring the default wiki instance]], although you could of course use that name. In our example, we use the domain name of the website on which the wiki instance is running. Thus, this wiki named "SaruWiki" is instance "saruman.biz" in our little wikifarm. Furthermore, you need a database name for each wiki instance that gets its own database, and it should be different from the default database name "wikidb" (unless you ''want'' to put your wiki instance into this default database, together with the wiki or wikis that are already in there). You could use the label you've chosen, or different ones, or derived ones. Remember to observe the MySQL [http://dev.mysql.com/doc/refman/5.0/en/identifiers.html limits on database names] (no more than 64 characters, no slashes or dots in the name, not ending in a space et cetera). Thus, you could have labels and database names like this: * saruman.biz and saruman-biz-wiki * iceditch.nl and iceditchNLwiki * ann.example.org and wiki-ann * bob.example.org and wiki-bob * charles.example.org and wikiCharles And remember, they are just labels. You could just as easily use user names, numbers or whatever. For maintainability though, we recommend a consistent scheme with recognizable labels. On the other hand, there are a number of labels you must avoid, because they will come to conflict with directories that already exist: most notably ''config'', ''extensions'' and ''images''. So before you begin, sit down and write out what your label and database name convention will be. This is trivial if you have just a handful of wikis, but can become very important should you ever grow to hundreds of instances. Each wikifarm will need its own set of configuration files, so for each new wiki instance we'll create directories under ''/etc/mediawiki'' using the chosen wiki labels: * ''/etc/mediawiki/saruman.biz'' * ''/etc/mediawiki/iceditch.nl'' * et cetera. Make each of these directories owned by the Apache2 user (''chmod www-data:www-data saruman.biz'' et cetera). Each wikifarm will need its own code base, so for each new wiki instance we'll create directories under ''/opt/mediawikifarm'' using the wiki labels: * ''/opt/mediawikifarm/saruman.biz'' * ''/opt/mediawikifarm/iceditch.nl'' * et cetera. The choice for ''/opt/mediawikifarm'' is quite arbitrary; one could make a case to use ''/var/www'' or ''/var/lib/mediawikifarm/'' or anything like this, but ''/opt'' is meant for optional software, which under Debian is software that's not in the standard repositories. And since the wikifarm isn't, it makes sense to create the links to the codebase there. Each wikifarm may have its own upload directory for images. This directory should not be placed under ''/opt'', but rather in a place where you expect data, e.g. ''/data'' if you have that, or ''/var/www'', or something like this. We have chosen for ''/data/wikifarm/<wikilabel>/images''. ==Linking to the shared code base== Now we can create links to the code base for each wikifarm instance. You need to create symlinks in your chosen wiki directory (e.g. ''/opt/mediawikifarm/saruman.biz'') to all files and folders in ''/var/lib/mediawiki'', except the directory ''images'' and the files ''AdminSettings.php'' (if it even exists) and ''LocalSettings.php''. Such a thing can be done simplest with a little script like this: <source lang="bash"> WSRC='/var/lib/mediawiki' WDEST='/opt/mediawikifarm/saruman.biz' cd $WSRC for s in *; do ln -s $WSRC/$s $WDEST/$s done cd $WDEST unlink images unlink AdminSetings.php unlink LocalSettings.php </source> Either run this at the command prompt, or bake it into a little Bash script (it could take the destination directory as a parameter to make it reusable). ==Recreating (moving over) your first MediaWiki instance== We'll assume you've followed the other tips in this wiki. Most notably, you've taken all steps described in the article on "how to [[Place MediaWiki inside a Virtual Host]]". The steps are simple ===Move the Wiki configuration within /etc=== Your Wiki config file will be ''/etc/mediawiki/LocalSettings.php'', and the settings for Apache2 will be in ''/etc/mediawiki/apache.conf''. We'll create a subdirectory under ''/etc/mediawiki'' that hosts the configuration of your Wiki. Suppose we name the subdirectory after the Wiki we're handling, in this example the SaruWiki. Furthermore, suppose that you also have an ''AdminSettings.php'' file. If you don't: no worries! Just skip the steps involved with that file! cd /etc/mediawiki mkdir SaruWiki mv LocalSettings.php SaruWiki mv AdminSettings.php SaruWiki mv apache.conf Saruwiki Note: make sure that after moving the files, the owner and permissions are the same. Moving a file while you are ''root'' has the effect of changing ownership to ''root''. ''LocalSettings.php'' must be owned by user:group ''www-data:www-data'' in order for Apache2 to be able to read the file. The ''AdminSettings.php'' file, if it exists, must be owned by ''root:root'' and NOT be readable by world (permissions 600) because it should contain the MySQL "root" username and password, with which maintenance scripts can perform their tasks if you instruct them to (while you are root, of course). To keep the Wiki running, we're going to need to tell Apache2 where the two files went to. In this case: * change the path to ''apache.conf'' in the ''Include'' statement in the site declaration (e.g. in ''/etc/apache2/sites-available/000-saruman.biz'', change the ''Include'' line to Include /etc/mediawiki/SaruWiki/apache.conf * change the symlink in ''/var/lib/mediawiki'' that points to ''LocalSettings.php''; and if you have one, change the ''AdminSettings.php'' symlink as well: cd /var/lib/mediawiki unlink LocalSettings.php ln -s /etc/mediawiki/SaruWiki/LocalSettings.php unlink AdminSettings.php ln -s /etc/mediawiki/SaruWiki/AdminSettings.php If you now restart Apache2, your Wiki will still work - but the two primary configuration files have moved over to a dedicated spot. ===Move the Wiki website=== As you can see from the [[MediaWiki directory structure]], the code that is actually served in the webserver is in two separate trees: by default the webserver ''thinks'' the full tree is in ''/var/lib/mediawiki'', but a large part of what you find in that spot is actually symlinked to files and directories in ''/usr/share/mediawiki''. Actually, the tree ''/usr/share/mediawiki'' can be thought of as a source code library, and ''/var/lib/mediawiki'' as the instance that we're actually serving. Since an instance needs both source code and some files of its own, we find that ''/var/lib/mediawiki'' contains both links to that source code, as well as actual files and directories. So what we now need to do, is to tell the webserver that the full tree can be served from elsewhere, and in that spot "elsewhere" create symlinks to the right spots. Let's begin with the latter. Let's assume we wish to move our default Wiki instance to ''/data/wikifarm/SaruWiki''. Other instances could then run under ''/data/wikifarm/<instancename>''. We now first create the links to the ''/usr/share/mediawiki'' files as we see them in the ''/var/lib/mediawiki'' instance: cd /data/wikifarm/SaruWiki for i in /usr/share/mediawiki/*.php; do > ln -s $i > done unlink AdminSettings.php unlink LocalSettings.php ln -s /usr/share/mediawiki/*.phtml ln -s /usr/share/mediawiki/install-utils.inc ln -s /usr/share/mediawiki/includes ln -s /usr/share/mediawiki/languages ln -s /usr/share/mediawiki/maintenance ln -s /usr/share/mediawiki/skins Next, we create the directories that contain the instance-specific files, i.e. the files that belong to this one member of the Wiki farm. This includes the ''images'' directory, where users of this wiki instance can upload their images. mkdir images chown www-data:www-data images mkdir config chown www-data:www-data config cp -P /var/lib/mediawiki/config/* . ==Adding MediaWiki instances to your farm== 1c516effadbf4167796041f637c91ff85bf963f0 2387 2386 2009-03-04T11:34:32Z Saruman! 2 /* Move the Wiki configuration within /etc */ note about codebase wikitext text/x-wiki ==On Wikifarms== ===What is a Wikifarm?=== Wikifarm and the verb Wikifarming refer to the setup and operation of multiple wikis on a single server. This could be because on a single website you want to run multiple wikis (e.g. ''<nowiki>http://www.saruman.biz/linuxwiki</nowiki>'' and ''<nowiki>http://www.saruman.biz/bsdwiki</nowiki>''). Or it could be because you're running multiple websites on a single server (each behind its own IP, or all on the same IP number using virtual hosts), and more than one of these websites needs to have its own wiki. ===Types of Wikifarms=== There are multiple ways to set up a wikifarm; what is the most suitable way for you depends on how you want to use the farm. We can roughly distinguish the following type of farms: * Multiple wikis, each running '''their own code and their own database'''. This is simple to set up when you install the Wiki code base from source - funny enough, under Debian it's ''not'' easy. Also, it's not a recommendable solution from the perspective of maintenance: each wiki must be updated separately when e.g. a security patch is issued for the wiki software. * Multiple wikis, running on '''a shared code base, but each with their own database'''. This is a good solution for multiple wikis for multiple websites. * Multiple wikis, running on '''a shared code base, and on a shared database'''. This could be a good solution for multiple wikis for a single website, because a user can register on one wiki, and automatically have the same account in the other database as well. We're not going to go into the first type, since the shared codebase is more maintainable. Instead, we're going to show how you can share the Mediawiki code base under Debian, so that a Debian update to the Mediawiki package is automatically applied to all instances of your wikifarm. And we'll see that from there, the choice between separate databases or shared databases is quite trivial. ===Wikifarming under Debian=== As with most Linux-based software packages, the MediaWiki package ''mediawiki'' that Debian offers is modified to suit the Debian policies and needs. This means that it has moved all configuration files to reside under ''/etc/mediawiki'', but also that it offers a somewhat better way to include extensions. The downside of these modifications is that creating a wikifarm under Debian is somewhat more complicated than when you're using vanilla MediaWiki sources - mostly because there isn't much documentation on the Internet about it. In the following we'll be documenting one possible way to create a wikifarm. Note that our method is particularly well-suited to "small" wikifarms (a handful of wikis on a single server), and not exactly fit for "big" wikifarms (thousands of wikis on one or more servers). ==General procedure to creat a wikifarm wiki instance== Setting up a wiki under Debian is quite easy - as you might have seen from this wiki's description under entry [[Basic MediaWiki Installation]]. This is because the Debian customization includes specific changes to some MediaWiki files, and to the default configuration files. Thus, the usual methods of creating a wiki instance next to the default one run into an additional obstacle: the forementioned Debian customizations. The way around it is this: * We suppose you've already installed your first wiki. It'll probably be just as described in the [[Basic MediaWiki Installation]]. * Make sure you adapt this first wiki to support virtual hosts, as described in the section on [[Place_MediaWiki_inside_a_Virtual_Host|placing MediaWiki inside a Virtual Host]]. * If your first wiki is running OK, follow the instructions in the next set of sections to move the wiki from its default place to the wikifarm. As a result, your first wiki should still run OK, but the place where Debian expects your wiki to live is now "empty" again * Set up your second wiki as if it were the first one, and move it over to the wiki farm. * et cetera. Because of the manual work involved, this system is not very well suited to "big" wikifarms; for those instances you'd be better off with one of the scripts that creates the wikifarm instance, and populates it with a default database and default configuration file. Scripts and instructions can be found on the Internet, like this one [http://www.jirp.nl/2008/04/11/mediawiki-farm-multiple-wiki/ on jirp.nl].<br> However, the method is quite doable when you've only got a handful of wikis to create, and remains largely compatible with Debians mechanisms for updating packages. ==Debian Mediawiki wikifarm structure== ===The standard Debian MediaWiki structure=== After installation of the ''mediawiki'' package, your server will be expanded with the [[MediaWiki directory structure]]. Within this structure, there are four main branches (if you haven't installed the ''mediawiki-extensions'' package yet): * ''/etc/mediawiki'' contains the configuration files for MediaWiki. * ''/usr/share/doc/mediawiki'' contains the documentation files. * ''/usr/share/mediawiki'' contains the source code. It is not used directly, rather it is linked to from the ''/var/lib/mediawiki'' directory. * ''/var/lib/mediawiki'' contains the site, including links to the configuration files in ''/etc/mediawiki''. Within these branches, we should not delete or move any file or directory, since that will confuse our [[APT|Debian package manager]] when an update to the ''mediawiki'' package becomes available, so we strive to minimize the changes to this structure. Furthermore, the default configuration files explicitly declare the wiki to "live" in ''/var/lib/mediawiki'', so we'll designate the wiki in that location as the "default wiki" as opposed by "wikifarm instances" that live e.g. under ''/var/wikifarm/<instancename>''. ===Extending the structure for a wikifarm=== First we need a label <instancename>, which designates the name for each wikifarm instance, so that we can label them as we're creating them. Each name needs to be unique because we're going to create directories based on the labels. Note that this label need not be the Wiki name, as you fill it in when [[Basic_MediaWiki_Installation#Configuring_the_Wiki_instance|configuring the default wiki instance]], although you could of course use that name. In our example, we use the domain name of the website on which the wiki instance is running. Thus, this wiki named "SaruWiki" is instance "saruman.biz" in our little wikifarm. Furthermore, you need a database name for each wiki instance that gets its own database, and it should be different from the default database name "wikidb" (unless you ''want'' to put your wiki instance into this default database, together with the wiki or wikis that are already in there). You could use the label you've chosen, or different ones, or derived ones. Remember to observe the MySQL [http://dev.mysql.com/doc/refman/5.0/en/identifiers.html limits on database names] (no more than 64 characters, no slashes or dots in the name, not ending in a space et cetera). Thus, you could have labels and database names like this: * saruman.biz and saruman-biz-wiki * iceditch.nl and iceditchNLwiki * ann.example.org and wiki-ann * bob.example.org and wiki-bob * charles.example.org and wikiCharles And remember, they are just labels. You could just as easily use user names, numbers or whatever. For maintainability though, we recommend a consistent scheme with recognizable labels. On the other hand, there are a number of labels you must avoid, because they will come to conflict with directories that already exist: most notably ''config'', ''extensions'' and ''images''. So before you begin, sit down and write out what your label and database name convention will be. This is trivial if you have just a handful of wikis, but can become very important should you ever grow to hundreds of instances. Each wikifarm will need its own set of configuration files, so for each new wiki instance we'll create directories under ''/etc/mediawiki'' using the chosen wiki labels: * ''/etc/mediawiki/saruman.biz'' * ''/etc/mediawiki/iceditch.nl'' * et cetera. Make each of these directories owned by the Apache2 user (''chmod www-data:www-data saruman.biz'' et cetera). Each wikifarm will need its own code base, so for each new wiki instance we'll create directories under ''/opt/mediawikifarm'' using the wiki labels: * ''/opt/mediawikifarm/saruman.biz'' * ''/opt/mediawikifarm/iceditch.nl'' * et cetera. The choice for ''/opt/mediawikifarm'' is quite arbitrary; one could make a case to use ''/var/www'' or ''/var/lib/mediawikifarm/'' or anything like this, but ''/opt'' is meant for optional software, which under Debian is software that's not in the standard repositories. And since the wikifarm isn't, it makes sense to create the links to the codebase there. Each wikifarm may have its own upload directory for images. This directory should not be placed under ''/opt'', but rather in a place where you expect data, e.g. ''/data'' if you have that, or ''/var/www'', or something like this. We have chosen for ''/data/wikifarm/<wikilabel>/images''. ==Linking to the shared code base== Now we can create links to the code base for each wikifarm instance. You need to create symlinks in your chosen wiki directory (e.g. ''/opt/mediawikifarm/saruman.biz'') to all files and folders in ''/var/lib/mediawiki'', except the directory ''images'' and the files ''AdminSettings.php'' (if it even exists) and ''LocalSettings.php''. Such a thing can be done simplest with a little script like this: <source lang="bash"> WSRC='/var/lib/mediawiki' WDEST='/opt/mediawikifarm/saruman.biz' cd $WSRC for s in *; do ln -s $WSRC/$s $WDEST/$s done cd $WDEST unlink images unlink AdminSetings.php unlink LocalSettings.php </source> Either run this at the command prompt, or bake it into a little Bash script (it could take the destination directory as a parameter to make it reusable). ==Recreating (moving over) your first MediaWiki instance== We'll assume you've followed the other tips in this wiki. Most notably, you've taken all steps described in the article on "how to [[Place MediaWiki inside a Virtual Host]]". The steps are simple ===Move the Wiki configuration within /etc=== Your Wiki config file will be ''/etc/mediawiki/LocalSettings.php'', and the settings for Apache2 will be in ''/etc/mediawiki/apache.conf''. We'll create a subdirectory under ''/etc/mediawiki'' that hosts the configuration of your Wiki. Suppose we name the subdirectory after the Wiki we're handling, in this example the SaruWiki. Furthermore, suppose that you also have an ''AdminSettings.php'' file. If you don't: no worries! Just skip the steps involved with that file! cd /etc/mediawiki mkdir SaruWiki mv LocalSettings.php SaruWiki mv AdminSettings.php SaruWiki mv apache.conf Saruwiki Note: make sure that after moving the files, the owner and permissions are the same. Moving a file while you are ''root'' has the effect of changing ownership to ''root''. ''LocalSettings.php'' must be owned by user:group ''www-data:www-data'' in order for Apache2 to be able to read the file. The ''AdminSettings.php'' file, if it exists, must be owned by ''root:root'' and NOT be readable by world (permissions 600) because it should contain the MySQL "root" username and password, with which maintenance scripts can perform their tasks if you instruct them to (while you are root, of course). To keep the Wiki running, we're going to need to tell Apache2 where the two files went to. In this case: * change the path to ''apache.conf'' in the ''Include'' statement in the site declaration (e.g. in ''/etc/apache2/sites-available/000-saruman.biz'', change the ''Include'' line to Include /etc/mediawiki/SaruWiki/apache.conf * change the symlink in ''/var/lib/mediawiki'' that points to ''LocalSettings.php''; and if you have one, change the ''AdminSettings.php'' symlink as well: cd /var/lib/mediawiki unlink LocalSettings.php ln -s /etc/mediawiki/SaruWiki/LocalSettings.php unlink AdminSettings.php ln -s /etc/mediawiki/SaruWiki/AdminSettings.php If you now restart Apache2, your Wiki will still work - but the two primary configuration files have moved over to a dedicated spot. Also note that you're not yet using the new codebase - that comes later. ===Move the Wiki website=== As you can see from the [[MediaWiki directory structure]], the code that is actually served in the webserver is in two separate trees: by default the webserver ''thinks'' the full tree is in ''/var/lib/mediawiki'', but a large part of what you find in that spot is actually symlinked to files and directories in ''/usr/share/mediawiki''. Actually, the tree ''/usr/share/mediawiki'' can be thought of as a source code library, and ''/var/lib/mediawiki'' as the instance that we're actually serving. Since an instance needs both source code and some files of its own, we find that ''/var/lib/mediawiki'' contains both links to that source code, as well as actual files and directories. So what we now need to do, is to tell the webserver that the full tree can be served from elsewhere, and in that spot "elsewhere" create symlinks to the right spots. Let's begin with the latter. Let's assume we wish to move our default Wiki instance to ''/data/wikifarm/SaruWiki''. Other instances could then run under ''/data/wikifarm/<instancename>''. We now first create the links to the ''/usr/share/mediawiki'' files as we see them in the ''/var/lib/mediawiki'' instance: cd /data/wikifarm/SaruWiki for i in /usr/share/mediawiki/*.php; do > ln -s $i > done unlink AdminSettings.php unlink LocalSettings.php ln -s /usr/share/mediawiki/*.phtml ln -s /usr/share/mediawiki/install-utils.inc ln -s /usr/share/mediawiki/includes ln -s /usr/share/mediawiki/languages ln -s /usr/share/mediawiki/maintenance ln -s /usr/share/mediawiki/skins Next, we create the directories that contain the instance-specific files, i.e. the files that belong to this one member of the Wiki farm. This includes the ''images'' directory, where users of this wiki instance can upload their images. mkdir images chown www-data:www-data images mkdir config chown www-data:www-data config cp -P /var/lib/mediawiki/config/* . ==Adding MediaWiki instances to your farm== 2b2ba9784e95a22f7dfe3d1a2d5d1e2847dd66c0 2388 2387 2009-03-04T12:37:28Z Saruman! 2 finished moving over wikitext text/x-wiki ==On Wikifarms== ===What is a Wikifarm?=== Wikifarm and the verb Wikifarming refer to the setup and operation of multiple wikis on a single server. This could be because on a single website you want to run multiple wikis (e.g. ''<nowiki>http://www.saruman.biz/linuxwiki</nowiki>'' and ''<nowiki>http://www.saruman.biz/bsdwiki</nowiki>''). Or it could be because you're running multiple websites on a single server (each behind its own IP, or all on the same IP number using virtual hosts), and more than one of these websites needs to have its own wiki. ===Types of Wikifarms=== There are multiple ways to set up a wikifarm; what is the most suitable way for you depends on how you want to use the farm. We can roughly distinguish the following type of farms: * Multiple wikis, each running '''their own code and their own database'''. This is simple to set up when you install the Wiki code base from source - funny enough, under Debian it's ''not'' easy. Also, it's not a recommendable solution from the perspective of maintenance: each wiki must be updated separately when e.g. a security patch is issued for the wiki software. * Multiple wikis, running on '''a shared code base, but each with their own database'''. This is a good solution for multiple wikis for multiple websites. * Multiple wikis, running on '''a shared code base, and on a shared database'''. This could be a good solution for multiple wikis for a single website, because a user can register on one wiki, and automatically have the same account in the other database as well. We're not going to go into the first type, since the shared codebase is more maintainable. Instead, we're going to show how you can share the Mediawiki code base under Debian, so that a Debian update to the Mediawiki package is automatically applied to all instances of your wikifarm. And we'll see that from there, the choice between separate databases or shared databases is quite trivial. ===Wikifarming under Debian=== As with most Linux-based software packages, the MediaWiki package ''mediawiki'' that Debian offers is modified to suit the Debian policies and needs. This means that it has moved all configuration files to reside under ''/etc/mediawiki'', but also that it offers a somewhat better way to include extensions. The downside of these modifications is that creating a wikifarm under Debian is somewhat more complicated than when you're using vanilla MediaWiki sources - mostly because there isn't much documentation on the Internet about it. In the following we'll be documenting one possible way to create a wikifarm. Note that our method is particularly well-suited to "small" wikifarms (a handful of wikis on a single server), and not exactly fit for "big" wikifarms (thousands of wikis on one or more servers). ==General procedure to creat a wikifarm wiki instance== Setting up a wiki under Debian is quite easy - as you might have seen from this wiki's description under entry [[Basic MediaWiki Installation]]. This is because the Debian customization includes specific changes to some MediaWiki files, and to the default configuration files. Thus, the usual methods of creating a wiki instance next to the default one run into an additional obstacle: the forementioned Debian customizations. The way around it is this: * We suppose you've already installed your first wiki. It'll probably be just as described in the [[Basic MediaWiki Installation]]. * Make sure you adapt this first wiki to support virtual hosts, as described in the section on [[Place_MediaWiki_inside_a_Virtual_Host|placing MediaWiki inside a Virtual Host]]. * If your first wiki is running OK, follow the instructions in the next set of sections to move the wiki from its default place to the wikifarm. As a result, your first wiki should still run OK, but the place where Debian expects your wiki to live is now "empty" again * Set up your second wiki as if it were the first one, and move it over to the wiki farm. * et cetera. Because of the manual work involved, this system is not very well suited to "big" wikifarms; for those instances you'd be better off with one of the scripts that creates the wikifarm instance, and populates it with a default database and default configuration file. Scripts and instructions can be found on the Internet, like this one [http://www.jirp.nl/2008/04/11/mediawiki-farm-multiple-wiki/ on jirp.nl].<br> However, the method is quite doable when you've only got a handful of wikis to create, and remains largely compatible with Debians mechanisms for updating packages. ==Debian Mediawiki wikifarm structure== ===The standard Debian MediaWiki structure=== After installation of the ''mediawiki'' package, your server will be expanded with the [[MediaWiki directory structure]]. Within this structure, there are four main branches (if you haven't installed the ''mediawiki-extensions'' package yet): * ''/etc/mediawiki'' contains the configuration files for MediaWiki. * ''/usr/share/doc/mediawiki'' contains the documentation files. * ''/usr/share/mediawiki'' contains the source code. It is not used directly, rather it is linked to from the ''/var/lib/mediawiki'' directory. * ''/var/lib/mediawiki'' contains the site, including links to the configuration files in ''/etc/mediawiki''. Within these branches, we should not delete or move any file or directory, since that will confuse our [[APT|Debian package manager]] when an update to the ''mediawiki'' package becomes available, so we strive to minimize the changes to this structure. Furthermore, the default configuration files explicitly declare the wiki to "live" in ''/var/lib/mediawiki'', so we'll designate the wiki in that location as the "default wiki" as opposed by "wikifarm instances" that live e.g. under ''/var/wikifarm/<instancename>''. ===Extending the structure for a wikifarm=== First we need a label <instancename>, which designates the name for each wikifarm instance, so that we can label them as we're creating them. Each name needs to be unique because we're going to create directories based on the labels. Note that this label need not be the Wiki name, as you fill it in when [[Basic_MediaWiki_Installation#Configuring_the_Wiki_instance|configuring the default wiki instance]], although you could of course use that name. In our example, we use the domain name of the website on which the wiki instance is running. Thus, this wiki named "SaruWiki" is instance "saruman.biz" in our little wikifarm. Furthermore, you need a database name for each wiki instance that gets its own database, and it should be different from the default database name "wikidb" (unless you ''want'' to put your wiki instance into this default database, together with the wiki or wikis that are already in there). You could use the label you've chosen, or different ones, or derived ones. Remember to observe the MySQL [http://dev.mysql.com/doc/refman/5.0/en/identifiers.html limits on database names] (no more than 64 characters, no slashes or dots in the name, not ending in a space et cetera). Thus, you could have labels and database names like this: * saruman.biz and saruman-biz-wiki * iceditch.nl and iceditchNLwiki * ann.example.org and wiki-ann * bob.example.org and wiki-bob * charles.example.org and wikiCharles And remember, they are just labels. You could just as easily use user names, numbers or whatever. For maintainability though, we recommend a consistent scheme with recognizable labels. On the other hand, there are a number of labels you must avoid, because they will come to conflict with directories that already exist: most notably ''config'', ''extensions'' and ''images''. So before you begin, sit down and write out what your label and database name convention will be. This is trivial if you have just a handful of wikis, but can become very important should you ever grow to hundreds of instances. Each wikifarm will need its own set of configuration files, so for each new wiki instance we'll create directories under ''/etc/mediawiki'' using the chosen wiki labels: * ''/etc/mediawiki/saruman.biz'' * ''/etc/mediawiki/iceditch.nl'' * et cetera. Make each of these directories owned by the Apache2 user (''chmod www-data:www-data saruman.biz'' et cetera). Each wikifarm will need its own code base, so for each new wiki instance we'll create directories under ''/opt/mediawikifarm'' using the wiki labels: * ''/opt/mediawikifarm/saruman.biz'' * ''/opt/mediawikifarm/iceditch.nl'' * et cetera. The choice for ''/opt/mediawikifarm'' is quite arbitrary; one could make a case to use ''/var/www'' or ''/var/lib/mediawikifarm/'' or anything like this, but ''/opt'' is meant for optional software, which under Debian is software that's not in the standard repositories. And since the wikifarm isn't, it makes sense to create the links to the codebase there. Each wikifarm may have its own upload directory for images. This directory should not be placed under ''/opt'', but rather in a place where you expect data, e.g. ''/data'' if you have that, or ''/var/www'', or something like this. We have chosen for ''/data/wikifarm/<wikilabel>/images''. ==Linking to the shared code base== As you can see from the [[MediaWiki directory structure]], the code that is actually served in the webserver is in two separate trees: by default the webserver ''thinks'' the full tree is in ''/var/lib/mediawiki'', but a large part of what you find in that spot is actually symlinked to files and directories in ''/usr/share/mediawiki''. Actually, the tree ''/usr/share/mediawiki'' can be thought of as a source code library, and ''/var/lib/mediawiki'' as the instance that we're actually serving. Since an instance needs both source code and some files of its own, we find that ''/var/lib/mediawiki'' contains both links to that source code, as well as actual files and directories. Now we can create links to the code base for each wikifarm instance for themselves. You need to create symlinks in your chosen wiki directory (e.g. ''/opt/mediawikifarm/saruman.biz'') to all files and folders in ''/usr/share/mediawiki'', except the directory ''images'' and the files ''AdminSettings.php'' (if it even exists) and ''LocalSettings.php''. Such a thing can be done simplest with a little script like this: <source lang="bash"> WSRC='/usr/share/mediawiki' WDEST='/opt/mediawikifarm/saruman.biz' cd $WSRC for s in *; do ln -s $WSRC/$s $WDEST/$s done cd $WDEST unlink images unlink AdminSetings.php unlink LocalSettings.php </source> Either run this at the command prompt, or bake it into a little Bash script (it could take the destination directory as a parameter to make it reusable). ==Recreating (moving over) your first MediaWiki instance== We'll assume you've followed the other tips in this wiki. Most notably, you've taken all steps described in the article on "how to [[Place MediaWiki inside a Virtual Host]]". The steps are simple ===Move the Wiki configuration within /etc=== Your Wiki config file will be ''/etc/mediawiki/LocalSettings.php'', and the settings for Apache2 will be in ''/etc/mediawiki/apache.conf''. We'll create a subdirectory under ''/etc/mediawiki'' that hosts the configuration of your Wiki. Suppose we name the subdirectory after the Wiki we're handling, in this example the SaruWiki. Furthermore, suppose that you also have an ''AdminSettings.php'' file. If you don't: no worries! Just skip the steps involved with that file! cd /etc/mediawiki mkdir SaruWiki mv LocalSettings.php SaruWiki mv AdminSettings.php SaruWiki mv apache.conf Saruwiki Note: make sure that after moving the files, the owner and permissions are the same. Moving a file while you are ''root'' has the effect of changing ownership to ''root''. ''LocalSettings.php'' must be owned by user:group ''www-data:www-data'' in order for Apache2 to be able to read the file. The ''AdminSettings.php'' file, if it exists, must be owned by ''root:root'' and NOT be readable by world (permissions 600) because it should contain the MySQL "root" username and password, with which maintenance scripts can perform their tasks if you instruct them to (while you are root, of course). To keep the Wiki running, we're going to need to tell Apache2 where the two files went to. In this case: * change the path to ''apache.conf'' in the ''Include'' statement in the site declaration (e.g. in ''/etc/apache2/sites-available/000-saruman.biz'', change the ''Include'' line to Include /etc/mediawiki/SaruWiki/apache.conf * change the symlink in ''/var/lib/mediawiki'' that points to ''LocalSettings.php''; and if you have one, change the ''AdminSettings.php'' symlink as well: cd /var/lib/mediawiki unlink LocalSettings.php ln -s /etc/mediawiki/SaruWiki/LocalSettings.php unlink AdminSettings.php ln -s /etc/mediawiki/SaruWiki/AdminSettings.php If you now restart Apache2, your Wiki will still work - but the two primary configuration files have moved over to a dedicated spot. Also note that you're not yet using the new codebase - that comes later. ===Move the Wiki website=== So what we now need to do, is to tell the webserver that the full tree can be served from the codebase we prepared. To this end, we need to change the apache2 configuration file ''apache.conf'' of the Wiki, that we've previously copied over to the Mediawiki configuration directory ''/etc/mediawiki/SaruWiki'' and that's included in the Virtual Host file of the saruman.biz website. This file needs to point to the new shared code location; it will look something like this: Alias /wiki /opt/mediawikifarm/saruman.biz <Directory /opt/mediawikifarm/saruman.biz/> Options +FollowSymLinks AllowOverride All order allow,deny allow from all </Directory> # some directories must be protected <Directory /opt/mediawikifarm/saruman.biz/config> Options -FollowSymLinks AllowOverride None </Directory> <Directory /opt/mediawikifarm/saruman.biz/upload> Options -FollowSymLinks AllowOverride None </Directory> Note that we haven't created the upload directory (but we can if we ever need it). Also note that we haven't created the ''config'' directory; that is because we don't need that in this wikifarm instance, because this particular instance has already been configured. Furthermore, we now need to make sure Apache2 can find the (working) ''LocalSettings.php'' from the new wiki location ''/opt/mediawikifarm/saruman.biz'', '''AND''' we need to change a setting within ''LocalSettings.php'' to reflect the new wiki location. For the first bit, we make the correct link(s): cd /opt/mediawikifarm/saruman.biz ln -s /etc/mediawiki/SaruWiki/AdminSettings.php ln -s /etc/mediawiki/SaruWiki/LocalSettings.php (even if you don't have the ''AdminSettings.php'' file yet, you can still make that link). For the second bit, we edit # We define this to allow the configuration file to be explicitly # located in /etc/mediawiki. # Change this if you are setting up multisite wikis on your server. define('MW_INSTALL_PATH','/opt/mediawikifarm/saruman.biz'); This should be enough! Restart Apache2 and test the result invoke-rc.d apache2 restart ==Adding more MediaWiki instances to your farm== cb17dbaab5107eeea128dddd2d06a518552c51cb 2389 2388 2009-03-04T20:52:06Z Saruman! 2 /* Adding more MediaWiki instances to your farm */ first description wikitext text/x-wiki ==On Wikifarms== ===What is a Wikifarm?=== Wikifarm and the verb Wikifarming refer to the setup and operation of multiple wikis on a single server. This could be because on a single website you want to run multiple wikis (e.g. ''<nowiki>http://www.saruman.biz/linuxwiki</nowiki>'' and ''<nowiki>http://www.saruman.biz/bsdwiki</nowiki>''). Or it could be because you're running multiple websites on a single server (each behind its own IP, or all on the same IP number using virtual hosts), and more than one of these websites needs to have its own wiki. ===Types of Wikifarms=== There are multiple ways to set up a wikifarm; what is the most suitable way for you depends on how you want to use the farm. We can roughly distinguish the following type of farms: * Multiple wikis, each running '''their own code and their own database'''. This is simple to set up when you install the Wiki code base from source - funny enough, under Debian it's ''not'' easy. Also, it's not a recommendable solution from the perspective of maintenance: each wiki must be updated separately when e.g. a security patch is issued for the wiki software. * Multiple wikis, running on '''a shared code base, but each with their own database'''. This is a good solution for multiple wikis for multiple websites. * Multiple wikis, running on '''a shared code base, and on a shared database'''. This could be a good solution for multiple wikis for a single website, because a user can register on one wiki, and automatically have the same account in the other database as well. We're not going to go into the first type, since the shared codebase is more maintainable. Instead, we're going to show how you can share the Mediawiki code base under Debian, so that a Debian update to the Mediawiki package is automatically applied to all instances of your wikifarm. And we'll see that from there, the choice between separate databases or shared databases is quite trivial. ===Wikifarming under Debian=== As with most Linux-based software packages, the MediaWiki package ''mediawiki'' that Debian offers is modified to suit the Debian policies and needs. This means that it has moved all configuration files to reside under ''/etc/mediawiki'', but also that it offers a somewhat better way to include extensions. The downside of these modifications is that creating a wikifarm under Debian is somewhat more complicated than when you're using vanilla MediaWiki sources - mostly because there isn't much documentation on the Internet about it. In the following we'll be documenting one possible way to create a wikifarm. Note that our method is particularly well-suited to "small" wikifarms (a handful of wikis on a single server), and not exactly fit for "big" wikifarms (thousands of wikis on one or more servers). ==General procedure to creat a wikifarm wiki instance== Setting up a wiki under Debian is quite easy - as you might have seen from this wiki's description under entry [[Basic MediaWiki Installation]]. This is because the Debian customization includes specific changes to some MediaWiki files, and to the default configuration files. Thus, the usual methods of creating a wiki instance next to the default one run into an additional obstacle: the forementioned Debian customizations. The way around it is this: * We suppose you've already installed your first wiki. It'll probably be just as described in the [[Basic MediaWiki Installation]]. * Make sure you adapt this first wiki to support virtual hosts, as described in the section on [[Place_MediaWiki_inside_a_Virtual_Host|placing MediaWiki inside a Virtual Host]]. * If your first wiki is running OK, follow the instructions in the next set of sections to move the wiki from its default place to the wikifarm. As a result, your first wiki should still run OK, but the place where Debian expects your wiki to live is now "empty" again * Set up your second wiki as if it were the first one, and move it over to the wiki farm. * et cetera. Because of the manual work involved, this system is not very well suited to "big" wikifarms; for those instances you'd be better off with one of the scripts that creates the wikifarm instance, and populates it with a default database and default configuration file. Scripts and instructions can be found on the Internet, like this one [http://www.jirp.nl/2008/04/11/mediawiki-farm-multiple-wiki/ on jirp.nl].<br> However, the method is quite doable when you've only got a handful of wikis to create, and remains largely compatible with Debians mechanisms for updating packages. ==Debian Mediawiki wikifarm structure== ===The standard Debian MediaWiki structure=== After installation of the ''mediawiki'' package, your server will be expanded with the [[MediaWiki directory structure]]. Within this structure, there are four main branches (if you haven't installed the ''mediawiki-extensions'' package yet): * ''/etc/mediawiki'' contains the configuration files for MediaWiki. * ''/usr/share/doc/mediawiki'' contains the documentation files. * ''/usr/share/mediawiki'' contains the source code. It is not used directly, rather it is linked to from the ''/var/lib/mediawiki'' directory. * ''/var/lib/mediawiki'' contains the site, including links to the configuration files in ''/etc/mediawiki''. Within these branches, we should not delete or move any file or directory, since that will confuse our [[APT|Debian package manager]] when an update to the ''mediawiki'' package becomes available, so we strive to minimize the changes to this structure. Furthermore, the default configuration files explicitly declare the wiki to "live" in ''/var/lib/mediawiki'', so we'll designate the wiki in that location as the "default wiki" as opposed by "wikifarm instances" that live e.g. under ''/var/wikifarm/<instancename>''. ===Extending the structure for a wikifarm=== First we need a label <instancename>, which designates the name for each wikifarm instance, so that we can label them as we're creating them. Each name needs to be unique because we're going to create directories based on the labels. Note that this label need not be the Wiki name, as you fill it in when [[Basic_MediaWiki_Installation#Configuring_the_Wiki_instance|configuring the default wiki instance]], although you could of course use that name. In our example, we use the domain name of the website on which the wiki instance is running. Thus, this wiki named "SaruWiki" is instance "saruman.biz" in our little wikifarm. Furthermore, you need a database name for each wiki instance that gets its own database, and it should be different from the default database name "wikidb" (unless you ''want'' to put your wiki instance into this default database, together with the wiki or wikis that are already in there). You could use the label you've chosen, or different ones, or derived ones. Remember to observe the MySQL [http://dev.mysql.com/doc/refman/5.0/en/identifiers.html limits on database names] (no more than 64 characters, no slashes or dots in the name, not ending in a space et cetera). Thus, you could have labels and database names like this: * saruman.biz and saruman-biz-wiki * iceditch.nl and iceditchNLwiki * ann.example.org and wiki-ann * bob.example.org and wiki-bob * charles.example.org and wikiCharles And remember, they are just labels. You could just as easily use user names, numbers or whatever. For maintainability though, we recommend a consistent scheme with recognizable labels. On the other hand, there are a number of labels you must avoid, because they will come to conflict with directories that already exist: most notably ''config'', ''extensions'' and ''images''. So before you begin, sit down and write out what your label and database name convention will be. This is trivial if you have just a handful of wikis, but can become very important should you ever grow to hundreds of instances. Each wikifarm will need its own set of configuration files, so for each new wiki instance we'll create directories under ''/etc/mediawiki'' using the chosen wiki labels: * ''/etc/mediawiki/saruman.biz'' * ''/etc/mediawiki/iceditch.nl'' * et cetera. Make each of these directories owned by the Apache2 user (''chmod www-data:www-data saruman.biz'' et cetera). Each wikifarm will need its own code base, so for each new wiki instance we'll create directories under ''/opt/mediawikifarm'' using the wiki labels: * ''/opt/mediawikifarm/saruman.biz'' * ''/opt/mediawikifarm/iceditch.nl'' * et cetera. The choice for ''/opt/mediawikifarm'' is quite arbitrary; one could make a case to use ''/var/www'' or ''/var/lib/mediawikifarm/'' or anything like this, but ''/opt'' is meant for optional software, which under Debian is software that's not in the standard repositories. And since the wikifarm isn't, it makes sense to create the links to the codebase there. Each wikifarm may have its own upload directory for images. This directory should not be placed under ''/opt'', but rather in a place where you expect data, e.g. ''/data'' if you have that, or ''/var/www'', or something like this. We have chosen for ''/data/wikifarm/<wikilabel>/images''. ==Linking to the shared code base== As you can see from the [[MediaWiki directory structure]], the code that is actually served in the webserver is in two separate trees: by default the webserver ''thinks'' the full tree is in ''/var/lib/mediawiki'', but a large part of what you find in that spot is actually symlinked to files and directories in ''/usr/share/mediawiki''. Actually, the tree ''/usr/share/mediawiki'' can be thought of as a source code library, and ''/var/lib/mediawiki'' as the instance that we're actually serving. Since an instance needs both source code and some files of its own, we find that ''/var/lib/mediawiki'' contains both links to that source code, as well as actual files and directories. Now we can create links to the code base for each wikifarm instance for themselves. You need to create symlinks in your chosen wiki directory (e.g. ''/opt/mediawikifarm/saruman.biz'') to all files and folders in ''/usr/share/mediawiki'', except the directory ''images'' and the files ''AdminSettings.php'' (if it even exists) and ''LocalSettings.php''. Such a thing can be done simplest with a little script like this: <source lang="bash"> WSRC='/usr/share/mediawiki' WDEST='/opt/mediawikifarm/saruman.biz' cd $WSRC for s in *; do ln -s $WSRC/$s $WDEST/$s done cd $WDEST unlink images unlink AdminSetings.php unlink LocalSettings.php </source> Either run this at the command prompt, or bake it into a little Bash script (it could take the destination directory as a parameter to make it reusable). ==Recreating (moving over) your first MediaWiki instance== We'll assume you've followed the other tips in this wiki. Most notably, you've taken all steps described in the article on "how to [[Place MediaWiki inside a Virtual Host]]". The steps are simple ===Move the Wiki configuration within /etc=== Your Wiki config file will be ''/etc/mediawiki/LocalSettings.php'', and the settings for Apache2 will be in ''/etc/mediawiki/apache.conf''. We'll create a subdirectory under ''/etc/mediawiki'' that hosts the configuration of your Wiki. Suppose we name the subdirectory after the Wiki we're handling, in this example the SaruWiki. Furthermore, suppose that you also have an ''AdminSettings.php'' file. If you don't: no worries! Just skip the steps involved with that file! cd /etc/mediawiki mkdir SaruWiki mv LocalSettings.php SaruWiki mv AdminSettings.php SaruWiki mv apache.conf Saruwiki Note: make sure that after moving the files, the owner and permissions are the same. Moving a file while you are ''root'' has the effect of changing ownership to ''root''. ''LocalSettings.php'' must be owned by user:group ''www-data:www-data'' in order for Apache2 to be able to read the file. The ''AdminSettings.php'' file, if it exists, must be owned by ''root:root'' and NOT be readable by world (permissions 600) because it should contain the MySQL "root" username and password, with which maintenance scripts can perform their tasks if you instruct them to (while you are root, of course). To keep the Wiki running, we're going to need to tell Apache2 where the two files went to. In this case: * change the path to ''apache.conf'' in the ''Include'' statement in the site declaration (e.g. in ''/etc/apache2/sites-available/000-saruman.biz'', change the ''Include'' line to Include /etc/mediawiki/SaruWiki/apache.conf * change the symlink in ''/var/lib/mediawiki'' that points to ''LocalSettings.php''; and if you have one, change the ''AdminSettings.php'' symlink as well: cd /var/lib/mediawiki unlink LocalSettings.php ln -s /etc/mediawiki/SaruWiki/LocalSettings.php unlink AdminSettings.php ln -s /etc/mediawiki/SaruWiki/AdminSettings.php If you now restart Apache2, your Wiki will still work - but the two primary configuration files have moved over to a dedicated spot. Also note that you're not yet using the new codebase - that comes later. ===Move the Wiki website=== So what we now need to do, is to tell the webserver that the full tree can be served from the codebase we prepared. To this end, we need to change the apache2 configuration file ''apache.conf'' of the Wiki, that we've previously copied over to the Mediawiki configuration directory ''/etc/mediawiki/SaruWiki'' and that's included in the Virtual Host file of the saruman.biz website. This file needs to point to the new shared code location; it will look something like this: Alias /wiki /opt/mediawikifarm/saruman.biz <Directory /opt/mediawikifarm/saruman.biz/> Options +FollowSymLinks AllowOverride All order allow,deny allow from all </Directory> # some directories must be protected <Directory /opt/mediawikifarm/saruman.biz/config> Options -FollowSymLinks AllowOverride None </Directory> <Directory /opt/mediawikifarm/saruman.biz/upload> Options -FollowSymLinks AllowOverride None </Directory> Note that we haven't created the upload directory (but we can if we ever need it). Also note that we haven't created the ''config'' directory; that is because we don't need that in this wikifarm instance, because this particular instance has already been configured. Furthermore, we now need to make sure Apache2 can find the (working) ''LocalSettings.php'' from the new wiki location ''/opt/mediawikifarm/saruman.biz'', '''AND''' we need to change a setting within ''LocalSettings.php'' to reflect the new wiki location. For the first bit, we make the correct link(s): cd /opt/mediawikifarm/saruman.biz ln -s /etc/mediawiki/SaruWiki/AdminSettings.php ln -s /etc/mediawiki/SaruWiki/LocalSettings.php (even if you don't have the ''AdminSettings.php'' file yet, you can still make that link). For the second bit, we edit # We define this to allow the configuration file to be explicitly # located in /etc/mediawiki. # Change this if you are setting up multisite wikis on your server. define('MW_INSTALL_PATH','/opt/mediawikifarm/saruman.biz'); This should be enough! Restart Apache2 and test the result invoke-rc.d apache2 restart ==Adding more MediaWiki instances to your farm== So how do you now prepare the next wiki in your farm? Quite simple. We're now going to set up the next wiki in the default place, being ''/var/lib/mediawiki'', after which we can return to the previous step of [[Create_a_Wikifarm#Linking_to_the_shared_code_base|creating another copy of the code base]] and again move the new wiki over from the default location to its location in our fresh wiki farm. So we need to set up the next website with access to the (now empty) default wiki location. We say "now empty" because the default location is lacking a ''LocalSettings.php'' file. In essence then, it is again an empty wiki, for which we'll have to run through the steps of basic configuration, as described in [[Basic_MediaWiki_Installation|basic MediaWiki installation]]. First off, we'll link the next virtual website to the default wiki location. Suppose the next virtual website is called "iceditch.nl", and our wiki database will be called IceditchWiki. We'll start off by creating a location for the IceditchWiki configuration files under the MediaWiki configuration directory: cd /etc/mediawiki mkdir iceditch.nl cp apache.conf iceditch.nl/apache.conf Next, we'll instruct our virtual host to load this new MediaWiki apache configuration file: cd /etc/apache2/sites-available vi 010-iceditch.nl Inside of this virtual host file, we include the MediaWiki configuration; the virtual host file then looks something like this: <VirtualHost *:80> ServerName www.iceditch.nl ServerAdmin webmaster@iceditch.nl DocumentRoot /var/www/iceditch.nl <Directory /> Options FollowSymLinks AllowOverride None </Directory> <Directory /var/www/iceditch.nl> Options Indexes FollowSymLinks MultiViews AllowOverride None Order allow,deny allow from all </Directory> Include /etc/mediawiki/iceditch.nl/apache.conf ScriptAlias /cgi-bin/ /usr/lib/cgi-bin/ <Directory "/usr/lib/cgi-bin"> AllowOverride None Options +ExecCGI -MultiViews +SymLinksIfOwnerMatch Order allow,deny Allow from all </Directory> ErrorLog /var/appslog/apache2/iceditch.nl-error.log # Possible values include: debug, info, notice, warn, error, crit, # alert, emerg. LogLevel notice CustomLog /var/appslog/apache2/iceditch.nl-access.log combined </VirtualHost> Now restart Apache2, and visit the link designated to the new wiki, in this case ''<nowiki>http://www.iceditch.nl/mediawiki</nowiki>''. You'll get the familiar "please set up the wiki first" message. Click it, and manually configure your new wiki. 58eef5446c9e5cfd4cfe026b99473433bc3324d6 2390 2389 2009-03-04T21:05:56Z Saruman! 2 /* Adding more MediaWiki instances to your farm */ done wikitext text/x-wiki ==On Wikifarms== ===What is a Wikifarm?=== Wikifarm and the verb Wikifarming refer to the setup and operation of multiple wikis on a single server. This could be because on a single website you want to run multiple wikis (e.g. ''<nowiki>http://www.saruman.biz/linuxwiki</nowiki>'' and ''<nowiki>http://www.saruman.biz/bsdwiki</nowiki>''). Or it could be because you're running multiple websites on a single server (each behind its own IP, or all on the same IP number using virtual hosts), and more than one of these websites needs to have its own wiki. ===Types of Wikifarms=== There are multiple ways to set up a wikifarm; what is the most suitable way for you depends on how you want to use the farm. We can roughly distinguish the following type of farms: * Multiple wikis, each running '''their own code and their own database'''. This is simple to set up when you install the Wiki code base from source - funny enough, under Debian it's ''not'' easy. Also, it's not a recommendable solution from the perspective of maintenance: each wiki must be updated separately when e.g. a security patch is issued for the wiki software. * Multiple wikis, running on '''a shared code base, but each with their own database'''. This is a good solution for multiple wikis for multiple websites. * Multiple wikis, running on '''a shared code base, and on a shared database'''. This could be a good solution for multiple wikis for a single website, because a user can register on one wiki, and automatically have the same account in the other database as well. We're not going to go into the first type, since the shared codebase is more maintainable. Instead, we're going to show how you can share the Mediawiki code base under Debian, so that a Debian update to the Mediawiki package is automatically applied to all instances of your wikifarm. And we'll see that from there, the choice between separate databases or shared databases is quite trivial. ===Wikifarming under Debian=== As with most Linux-based software packages, the MediaWiki package ''mediawiki'' that Debian offers is modified to suit the Debian policies and needs. This means that it has moved all configuration files to reside under ''/etc/mediawiki'', but also that it offers a somewhat better way to include extensions. The downside of these modifications is that creating a wikifarm under Debian is somewhat more complicated than when you're using vanilla MediaWiki sources - mostly because there isn't much documentation on the Internet about it. In the following we'll be documenting one possible way to create a wikifarm. Note that our method is particularly well-suited to "small" wikifarms (a handful of wikis on a single server), and not exactly fit for "big" wikifarms (thousands of wikis on one or more servers). ==General procedure to creat a wikifarm wiki instance== Setting up a wiki under Debian is quite easy - as you might have seen from this wiki's description under entry [[Basic MediaWiki Installation]]. This is because the Debian customization includes specific changes to some MediaWiki files, and to the default configuration files. Thus, the usual methods of creating a wiki instance next to the default one run into an additional obstacle: the forementioned Debian customizations. The way around it is this: * We suppose you've already installed your first wiki. It'll probably be just as described in the [[Basic MediaWiki Installation]]. * Make sure you adapt this first wiki to support virtual hosts, as described in the section on [[Place_MediaWiki_inside_a_Virtual_Host|placing MediaWiki inside a Virtual Host]]. * If your first wiki is running OK, follow the instructions in the next set of sections to move the wiki from its default place to the wikifarm. As a result, your first wiki should still run OK, but the place where Debian expects your wiki to live is now "empty" again * Set up your second wiki as if it were the first one, and move it over to the wiki farm. * et cetera. Because of the manual work involved, this system is not very well suited to "big" wikifarms; for those instances you'd be better off with one of the scripts that creates the wikifarm instance, and populates it with a default database and default configuration file. Scripts and instructions can be found on the Internet, like this one [http://www.jirp.nl/2008/04/11/mediawiki-farm-multiple-wiki/ on jirp.nl].<br> However, the method is quite doable when you've only got a handful of wikis to create, and remains largely compatible with Debians mechanisms for updating packages. ==Debian Mediawiki wikifarm structure== ===The standard Debian MediaWiki structure=== After installation of the ''mediawiki'' package, your server will be expanded with the [[MediaWiki directory structure]]. Within this structure, there are four main branches (if you haven't installed the ''mediawiki-extensions'' package yet): * ''/etc/mediawiki'' contains the configuration files for MediaWiki. * ''/usr/share/doc/mediawiki'' contains the documentation files. * ''/usr/share/mediawiki'' contains the source code. It is not used directly, rather it is linked to from the ''/var/lib/mediawiki'' directory. * ''/var/lib/mediawiki'' contains the site, including links to the configuration files in ''/etc/mediawiki''. Within these branches, we should not delete or move any file or directory, since that will confuse our [[APT|Debian package manager]] when an update to the ''mediawiki'' package becomes available, so we strive to minimize the changes to this structure. Furthermore, the default configuration files explicitly declare the wiki to "live" in ''/var/lib/mediawiki'', so we'll designate the wiki in that location as the "default wiki" as opposed by "wikifarm instances" that live e.g. under ''/var/wikifarm/<instancename>''. ===Extending the structure for a wikifarm=== First we need a label <instancename>, which designates the name for each wikifarm instance, so that we can label them as we're creating them. Each name needs to be unique because we're going to create directories based on the labels. Note that this label need not be the Wiki name, as you fill it in when [[Basic_MediaWiki_Installation#Configuring_the_Wiki_instance|configuring the default wiki instance]], although you could of course use that name. In our example, we use the domain name of the website on which the wiki instance is running. Thus, this wiki named "SaruWiki" is instance "saruman.biz" in our little wikifarm. Furthermore, you need a database name for each wiki instance that gets its own database, and it should be different from the default database name "wikidb" (unless you ''want'' to put your wiki instance into this default database, together with the wiki or wikis that are already in there). You could use the label you've chosen, or different ones, or derived ones. Remember to observe the MySQL [http://dev.mysql.com/doc/refman/5.0/en/identifiers.html limits on database names] (no more than 64 characters, no slashes or dots in the name, not ending in a space et cetera). Thus, you could have labels and database names like this: * saruman.biz and saruman-biz-wiki * iceditch.nl and iceditchNLwiki * ann.example.org and wiki-ann * bob.example.org and wiki-bob * charles.example.org and wikiCharles And remember, they are just labels. You could just as easily use user names, numbers or whatever. For maintainability though, we recommend a consistent scheme with recognizable labels. On the other hand, there are a number of labels you must avoid, because they will come to conflict with directories that already exist: most notably ''config'', ''extensions'' and ''images''. So before you begin, sit down and write out what your label and database name convention will be. This is trivial if you have just a handful of wikis, but can become very important should you ever grow to hundreds of instances. Each wikifarm will need its own set of configuration files, so for each new wiki instance we'll create directories under ''/etc/mediawiki'' using the chosen wiki labels: * ''/etc/mediawiki/saruman.biz'' * ''/etc/mediawiki/iceditch.nl'' * et cetera. Make each of these directories owned by the Apache2 user (''chmod www-data:www-data saruman.biz'' et cetera). Each wikifarm will need its own code base, so for each new wiki instance we'll create directories under ''/opt/mediawikifarm'' using the wiki labels: * ''/opt/mediawikifarm/saruman.biz'' * ''/opt/mediawikifarm/iceditch.nl'' * et cetera. The choice for ''/opt/mediawikifarm'' is quite arbitrary; one could make a case to use ''/var/www'' or ''/var/lib/mediawikifarm/'' or anything like this, but ''/opt'' is meant for optional software, which under Debian is software that's not in the standard repositories. And since the wikifarm isn't, it makes sense to create the links to the codebase there. Each wikifarm may have its own upload directory for images. This directory should not be placed under ''/opt'', but rather in a place where you expect data, e.g. ''/data'' if you have that, or ''/var/www'', or something like this. We have chosen for ''/data/wikifarm/<wikilabel>/images''. ==Linking to the shared code base== As you can see from the [[MediaWiki directory structure]], the code that is actually served in the webserver is in two separate trees: by default the webserver ''thinks'' the full tree is in ''/var/lib/mediawiki'', but a large part of what you find in that spot is actually symlinked to files and directories in ''/usr/share/mediawiki''. Actually, the tree ''/usr/share/mediawiki'' can be thought of as a source code library, and ''/var/lib/mediawiki'' as the instance that we're actually serving. Since an instance needs both source code and some files of its own, we find that ''/var/lib/mediawiki'' contains both links to that source code, as well as actual files and directories. Now we can create links to the code base for each wikifarm instance for themselves. You need to create symlinks in your chosen wiki directory (e.g. ''/opt/mediawikifarm/saruman.biz'') to all files and folders in ''/usr/share/mediawiki'', except the directory ''images'' and the files ''AdminSettings.php'' (if it even exists) and ''LocalSettings.php''. Such a thing can be done simplest with a little script like this: <source lang="bash"> WSRC='/usr/share/mediawiki' WDEST='/opt/mediawikifarm/saruman.biz' cd $WSRC for s in *; do ln -s $WSRC/$s $WDEST/$s done cd $WDEST unlink images unlink AdminSetings.php unlink LocalSettings.php </source> Either run this at the command prompt, or bake it into a little Bash script (it could take the destination directory as a parameter to make it reusable). ==Recreating (moving over) your first MediaWiki instance== We'll assume you've followed the other tips in this wiki. Most notably, you've taken all steps described in the article on "how to [[Place MediaWiki inside a Virtual Host]]". The steps are simple ===Move the Wiki configuration within /etc=== Your Wiki config file will be ''/etc/mediawiki/LocalSettings.php'', and the settings for Apache2 will be in ''/etc/mediawiki/apache.conf''. We'll create a subdirectory under ''/etc/mediawiki'' that hosts the configuration of your Wiki. Suppose we name the subdirectory after the Wiki we're handling, in this example the SaruWiki. Furthermore, suppose that you also have an ''AdminSettings.php'' file. If you don't: no worries! Just skip the steps involved with that file! cd /etc/mediawiki mkdir SaruWiki mv LocalSettings.php SaruWiki mv AdminSettings.php SaruWiki mv apache.conf Saruwiki Note: make sure that after moving the files, the owner and permissions are the same. Moving a file while you are ''root'' has the effect of changing ownership to ''root''. ''LocalSettings.php'' must be owned by user:group ''www-data:www-data'' in order for Apache2 to be able to read the file. The ''AdminSettings.php'' file, if it exists, must be owned by ''root:root'' and NOT be readable by world (permissions 600) because it should contain the MySQL "root" username and password, with which maintenance scripts can perform their tasks if you instruct them to (while you are root, of course). To keep the Wiki running, we're going to need to tell Apache2 where the two files went to. In this case: * change the path to ''apache.conf'' in the ''Include'' statement in the site declaration (e.g. in ''/etc/apache2/sites-available/000-saruman.biz'', change the ''Include'' line to Include /etc/mediawiki/SaruWiki/apache.conf * change the symlink in ''/var/lib/mediawiki'' that points to ''LocalSettings.php''; and if you have one, change the ''AdminSettings.php'' symlink as well: cd /var/lib/mediawiki unlink LocalSettings.php ln -s /etc/mediawiki/SaruWiki/LocalSettings.php unlink AdminSettings.php ln -s /etc/mediawiki/SaruWiki/AdminSettings.php If you now restart Apache2, your Wiki will still work - but the two primary configuration files have moved over to a dedicated spot. Also note that you're not yet using the new codebase - that comes later. ===Move the Wiki website=== So what we now need to do, is to tell the webserver that the full tree can be served from the codebase we prepared. To this end, we need to change the apache2 configuration file ''apache.conf'' of the Wiki, that we've previously copied over to the Mediawiki configuration directory ''/etc/mediawiki/SaruWiki'' and that's included in the Virtual Host file of the saruman.biz website. This file needs to point to the new shared code location; it will look something like this: Alias /wiki /opt/mediawikifarm/saruman.biz <Directory /opt/mediawikifarm/saruman.biz/> Options +FollowSymLinks AllowOverride All order allow,deny allow from all </Directory> # some directories must be protected <Directory /opt/mediawikifarm/saruman.biz/config> Options -FollowSymLinks AllowOverride None </Directory> <Directory /opt/mediawikifarm/saruman.biz/upload> Options -FollowSymLinks AllowOverride None </Directory> Note that we haven't created the upload directory (but we can if we ever need it). Also note that we haven't created the ''config'' directory; that is because we don't need that in this wikifarm instance, because this particular instance has already been configured. Furthermore, we now need to make sure Apache2 can find the (working) ''LocalSettings.php'' from the new wiki location ''/opt/mediawikifarm/saruman.biz'', '''AND''' we need to change a setting within ''LocalSettings.php'' to reflect the new wiki location. For the first bit, we make the correct link(s): cd /opt/mediawikifarm/saruman.biz ln -s /etc/mediawiki/SaruWiki/AdminSettings.php ln -s /etc/mediawiki/SaruWiki/LocalSettings.php (even if you don't have the ''AdminSettings.php'' file yet, you can still make that link). For the second bit, we edit # We define this to allow the configuration file to be explicitly # located in /etc/mediawiki. # Change this if you are setting up multisite wikis on your server. define('MW_INSTALL_PATH','/opt/mediawikifarm/saruman.biz'); This should be enough! Restart Apache2 and test the result invoke-rc.d apache2 restart ==Adding more MediaWiki instances to your farm== So how do you now prepare the next wiki in your farm? Quite simple. We're now going to set up the next wiki in the default place, being ''/var/lib/mediawiki'', after which we can return to the previous step of [[Create_a_Wikifarm#Linking_to_the_shared_code_base|creating another copy of the code base]] and again move the new wiki over from the default location to its location in our fresh wiki farm. So we need to set up the next website with access to the (now empty) default wiki location. We say "now empty" because the default location is lacking a ''LocalSettings.php'' file. In essence then, it is again an empty wiki, for which we'll have to run through the steps of basic configuration, as described in [[Basic_MediaWiki_Installation|basic MediaWiki installation]]. First off, we'll link the next virtual website to the default wiki location. Suppose the next virtual website is called "iceditch.nl", and our wiki database will be called IceditchWiki. We'll start off by creating a location for the IceditchWiki configuration files under the MediaWiki configuration directory: cd /etc/mediawiki mkdir iceditch.nl cp apache.conf iceditch.nl/apache.conf Next, we'll instruct our virtual host to load this new MediaWiki apache configuration file: cd /etc/apache2/sites-available vi 010-iceditch.nl Inside of this virtual host file, we include the MediaWiki configuration; the virtual host file then looks something like this: <VirtualHost *:80> ServerName www.iceditch.nl ServerAdmin webmaster@iceditch.nl DocumentRoot /var/www/iceditch.nl <Directory /> Options FollowSymLinks AllowOverride None </Directory> <Directory /var/www/iceditch.nl> Options Indexes FollowSymLinks MultiViews AllowOverride None Order allow,deny allow from all </Directory> Include /etc/mediawiki/iceditch.nl/apache.conf ScriptAlias /cgi-bin/ /usr/lib/cgi-bin/ <Directory "/usr/lib/cgi-bin"> AllowOverride None Options +ExecCGI -MultiViews +SymLinksIfOwnerMatch Order allow,deny Allow from all </Directory> ErrorLog /var/appslog/apache2/iceditch.nl-error.log # Possible values include: debug, info, notice, warn, error, crit, # alert, emerg. LogLevel notice CustomLog /var/appslog/apache2/iceditch.nl-access.log combined </VirtualHost> Now restart Apache2, and visit the link designated to the new wiki, in this case ''<nowiki>http://www.iceditch.nl/mediawiki</nowiki>''. You'll get the familiar "please set up the wiki first" message. Click it, and manually configure your new wiki. When you're done, move the created ''LocalSettings.php'' to ''/etc/mediawiki'' and you're set! Your new wiki is running in the default position, and as soon as you've moved it to the wikifarm, you can create yet another wiki! adf1d254a7ffe06f313be79180395419b2e786d8 2391 2390 2009-03-04T21:19:24Z Saruman! 2 /* Debian Mediawiki wikifarm structure */ added wiki user note wikitext text/x-wiki ==On Wikifarms== ===What is a Wikifarm?=== Wikifarm and the verb Wikifarming refer to the setup and operation of multiple wikis on a single server. This could be because on a single website you want to run multiple wikis (e.g. ''<nowiki>http://www.saruman.biz/linuxwiki</nowiki>'' and ''<nowiki>http://www.saruman.biz/bsdwiki</nowiki>''). Or it could be because you're running multiple websites on a single server (each behind its own IP, or all on the same IP number using virtual hosts), and more than one of these websites needs to have its own wiki. ===Types of Wikifarms=== There are multiple ways to set up a wikifarm; what is the most suitable way for you depends on how you want to use the farm. We can roughly distinguish the following type of farms: * Multiple wikis, each running '''their own code and their own database'''. This is simple to set up when you install the Wiki code base from source - funny enough, under Debian it's ''not'' easy. Also, it's not a recommendable solution from the perspective of maintenance: each wiki must be updated separately when e.g. a security patch is issued for the wiki software. * Multiple wikis, running on '''a shared code base, but each with their own database'''. This is a good solution for multiple wikis for multiple websites. * Multiple wikis, running on '''a shared code base, and on a shared database'''. This could be a good solution for multiple wikis for a single website, because a user can register on one wiki, and automatically have the same account in the other database as well. We're not going to go into the first type, since the shared codebase is more maintainable. Instead, we're going to show how you can share the Mediawiki code base under Debian, so that a Debian update to the Mediawiki package is automatically applied to all instances of your wikifarm. And we'll see that from there, the choice between separate databases or shared databases is quite trivial. ===Wikifarming under Debian=== As with most Linux-based software packages, the MediaWiki package ''mediawiki'' that Debian offers is modified to suit the Debian policies and needs. This means that it has moved all configuration files to reside under ''/etc/mediawiki'', but also that it offers a somewhat better way to include extensions. The downside of these modifications is that creating a wikifarm under Debian is somewhat more complicated than when you're using vanilla MediaWiki sources - mostly because there isn't much documentation on the Internet about it. In the following we'll be documenting one possible way to create a wikifarm. Note that our method is particularly well-suited to "small" wikifarms (a handful of wikis on a single server), and not exactly fit for "big" wikifarms (thousands of wikis on one or more servers). ==General procedure to creat a wikifarm wiki instance== Setting up a wiki under Debian is quite easy - as you might have seen from this wiki's description under entry [[Basic MediaWiki Installation]]. This is because the Debian customization includes specific changes to some MediaWiki files, and to the default configuration files. Thus, the usual methods of creating a wiki instance next to the default one run into an additional obstacle: the forementioned Debian customizations. The way around it is this: * We suppose you've already installed your first wiki. It'll probably be just as described in the [[Basic MediaWiki Installation]]. * Make sure you adapt this first wiki to support virtual hosts, as described in the section on [[Place_MediaWiki_inside_a_Virtual_Host|placing MediaWiki inside a Virtual Host]]. * If your first wiki is running OK, follow the instructions in the next set of sections to move the wiki from its default place to the wikifarm. As a result, your first wiki should still run OK, but the place where Debian expects your wiki to live is now "empty" again * Set up your second wiki as if it were the first one, and move it over to the wiki farm. * et cetera. Because of the manual work involved, this system is not very well suited to "big" wikifarms; for those instances you'd be better off with one of the scripts that creates the wikifarm instance, and populates it with a default database and default configuration file. Scripts and instructions can be found on the Internet, like this one [http://www.jirp.nl/2008/04/11/mediawiki-farm-multiple-wiki/ on jirp.nl].<br> However, the method is quite doable when you've only got a handful of wikis to create, and remains largely compatible with Debians mechanisms for updating packages. ==Debian Mediawiki wikifarm structure== ===The standard Debian MediaWiki structure=== After installation of the ''mediawiki'' package, your server will be expanded with the [[MediaWiki directory structure]]. Within this structure, there are four main branches (if you haven't installed the ''mediawiki-extensions'' package yet): * ''/etc/mediawiki'' contains the configuration files for MediaWiki. * ''/usr/share/doc/mediawiki'' contains the documentation files. * ''/usr/share/mediawiki'' contains the source code. It is not used directly, rather it is linked to from the ''/var/lib/mediawiki'' directory. * ''/var/lib/mediawiki'' contains the site, including links to the configuration files in ''/etc/mediawiki''. Within these branches, we should not delete or move any file or directory, since that will confuse our [[APT and aptitude|Debian package manager]] when an update to the ''mediawiki'' package becomes available, so we strive to minimize the changes to this structure. Furthermore, the default configuration files explicitly declare the wiki to "live" in ''/var/lib/mediawiki'', so we'll designate the wiki in that location as the "default wiki" as opposed by "wikifarm instances" that live e.g. under ''/var/wikifarm/<instancename>''.<br> Another important element of the MediaWiki structure is hidden in its use of the MySQL database: during setup, you either need to have a database user account, or a MySQL superuser account (e.g. 'root'@'localhost') so as to be able to create the wiki database and a database user account. ===Extending the structure for a wikifarm=== First we need a label <instancename>, which designates the name for each wikifarm instance, so that we can label them as we're creating them. Each name needs to be unique because we're going to create directories based on the labels. Note that this label need not be the Wiki name, as you fill it in when [[Basic_MediaWiki_Installation#Configuring_the_Wiki_instance|configuring the default wiki instance]], although you could of course use that name. In our example, we use the domain name of the website on which the wiki instance is running. Thus, this wiki named "SaruWiki" is instance "saruman.biz" in our little wikifarm. Furthermore, you need a database name for each wiki instance that gets its own database, and it should be different from the default database name "wikidb" (unless you ''want'' to put your wiki instance into this default database, together with the wiki or wikis that are already in there). You could use the label you've chosen, or different ones, or derived ones. Remember to observe the MySQL [http://dev.mysql.com/doc/refman/5.0/en/identifiers.html limits on database names] (no more than 64 characters, no slashes or dots in the name, not ending in a space et cetera).<br> In addition, you need a database user name and password. This should not be the same user name and password that you've used to set up any other wiki database, or you'd have a security risk. In the unfortunate case in which you'd feel compelled to reuse a database user name (e.g. the standard "wikiuser"), be sure to reuse the original password of "wikiuser", or risk losing access to the earlier wikis that use that same user. Thus, you could have labels, database names and database username/passwords like this: * saruman.biz and saruman-biz-wiki and saruwikiuser/Gp5Zmull01 * iceditch.nl and iceditchNLwiki and icewikiuser/Br3thReeka1 * ann.example.org and wiki-ann and ann/Tr4p7qqhl2 * bob.example.org and wiki-bob and bobwiki/Gnff3Prkks * charles.example.org and wikiCharles and charles/Pzmel55Fgzxm And remember, they are just labels. You could just as easily use user names, numbers or whatever. For maintainability though, we recommend a consistent scheme with recognizable labels. On the other hand, there are a number of labels you must avoid, because they will come to conflict with directories that already exist: most notably ''config'', ''extensions'' and ''images''. So before you begin, sit down and write out what your label and database name convention will be. This is trivial if you have just a handful of wikis, but can become very important should you ever grow to hundreds of instances. Each wikifarm will need its own set of configuration files, so for each new wiki instance we'll create directories under ''/etc/mediawiki'' using the chosen wiki labels: * ''/etc/mediawiki/saruman.biz'' * ''/etc/mediawiki/iceditch.nl'' * et cetera. Make each of these directories owned by the Apache2 user (''chmod www-data:www-data saruman.biz'' et cetera). Each wikifarm will need its own code base, so for each new wiki instance we'll create directories under ''/opt/mediawikifarm'' using the wiki labels: * ''/opt/mediawikifarm/saruman.biz'' * ''/opt/mediawikifarm/iceditch.nl'' * et cetera. The choice for ''/opt/mediawikifarm'' is quite arbitrary; one could make a case to use ''/var/www'' or ''/var/lib/mediawikifarm/'' or anything like this, but ''/opt'' is meant for optional software, which under Debian is software that's not in the standard repositories. And since the wikifarm isn't, it makes sense to create the links to the codebase there. Each wikifarm may have its own upload directory for images. This directory should not be placed under ''/opt'', but rather in a place where you expect data, e.g. ''/data'' if you have that, or ''/var/www'', or something like this. We have chosen for ''/data/wikifarm/<wikilabel>/images''. ==Linking to the shared code base== As you can see from the [[MediaWiki directory structure]], the code that is actually served in the webserver is in two separate trees: by default the webserver ''thinks'' the full tree is in ''/var/lib/mediawiki'', but a large part of what you find in that spot is actually symlinked to files and directories in ''/usr/share/mediawiki''. Actually, the tree ''/usr/share/mediawiki'' can be thought of as a source code library, and ''/var/lib/mediawiki'' as the instance that we're actually serving. Since an instance needs both source code and some files of its own, we find that ''/var/lib/mediawiki'' contains both links to that source code, as well as actual files and directories. Now we can create links to the code base for each wikifarm instance for themselves. You need to create symlinks in your chosen wiki directory (e.g. ''/opt/mediawikifarm/saruman.biz'') to all files and folders in ''/usr/share/mediawiki'', except the directory ''images'' and the files ''AdminSettings.php'' (if it even exists) and ''LocalSettings.php''. Such a thing can be done simplest with a little script like this: <source lang="bash"> WSRC='/usr/share/mediawiki' WDEST='/opt/mediawikifarm/saruman.biz' cd $WSRC for s in *; do ln -s $WSRC/$s $WDEST/$s done cd $WDEST unlink images unlink AdminSetings.php unlink LocalSettings.php </source> Either run this at the command prompt, or bake it into a little Bash script (it could take the destination directory as a parameter to make it reusable). ==Recreating (moving over) your first MediaWiki instance== We'll assume you've followed the other tips in this wiki. Most notably, you've taken all steps described in the article on "how to [[Place MediaWiki inside a Virtual Host]]". The steps are simple ===Move the Wiki configuration within /etc=== Your Wiki config file will be ''/etc/mediawiki/LocalSettings.php'', and the settings for Apache2 will be in ''/etc/mediawiki/apache.conf''. We'll create a subdirectory under ''/etc/mediawiki'' that hosts the configuration of your Wiki. Suppose we name the subdirectory after the Wiki we're handling, in this example the SaruWiki. Furthermore, suppose that you also have an ''AdminSettings.php'' file. If you don't: no worries! Just skip the steps involved with that file! cd /etc/mediawiki mkdir SaruWiki mv LocalSettings.php SaruWiki mv AdminSettings.php SaruWiki mv apache.conf Saruwiki Note: make sure that after moving the files, the owner and permissions are the same. Moving a file while you are ''root'' has the effect of changing ownership to ''root''. ''LocalSettings.php'' must be owned by user:group ''www-data:www-data'' in order for Apache2 to be able to read the file. The ''AdminSettings.php'' file, if it exists, must be owned by ''root:root'' and NOT be readable by world (permissions 600) because it should contain the MySQL "root" username and password, with which maintenance scripts can perform their tasks if you instruct them to (while you are root, of course). To keep the Wiki running, we're going to need to tell Apache2 where the two files went to. In this case: * change the path to ''apache.conf'' in the ''Include'' statement in the site declaration (e.g. in ''/etc/apache2/sites-available/000-saruman.biz'', change the ''Include'' line to Include /etc/mediawiki/SaruWiki/apache.conf * change the symlink in ''/var/lib/mediawiki'' that points to ''LocalSettings.php''; and if you have one, change the ''AdminSettings.php'' symlink as well: cd /var/lib/mediawiki unlink LocalSettings.php ln -s /etc/mediawiki/SaruWiki/LocalSettings.php unlink AdminSettings.php ln -s /etc/mediawiki/SaruWiki/AdminSettings.php If you now restart Apache2, your Wiki will still work - but the two primary configuration files have moved over to a dedicated spot. Also note that you're not yet using the new codebase - that comes later. ===Move the Wiki website=== So what we now need to do, is to tell the webserver that the full tree can be served from the codebase we prepared. To this end, we need to change the apache2 configuration file ''apache.conf'' of the Wiki, that we've previously copied over to the Mediawiki configuration directory ''/etc/mediawiki/SaruWiki'' and that's included in the Virtual Host file of the saruman.biz website. This file needs to point to the new shared code location; it will look something like this: Alias /wiki /opt/mediawikifarm/saruman.biz <Directory /opt/mediawikifarm/saruman.biz/> Options +FollowSymLinks AllowOverride All order allow,deny allow from all </Directory> # some directories must be protected <Directory /opt/mediawikifarm/saruman.biz/config> Options -FollowSymLinks AllowOverride None </Directory> <Directory /opt/mediawikifarm/saruman.biz/upload> Options -FollowSymLinks AllowOverride None </Directory> Note that we haven't created the upload directory (but we can if we ever need it). Also note that we haven't created the ''config'' directory; that is because we don't need that in this wikifarm instance, because this particular instance has already been configured. Furthermore, we now need to make sure Apache2 can find the (working) ''LocalSettings.php'' from the new wiki location ''/opt/mediawikifarm/saruman.biz'', '''AND''' we need to change a setting within ''LocalSettings.php'' to reflect the new wiki location. For the first bit, we make the correct link(s): cd /opt/mediawikifarm/saruman.biz ln -s /etc/mediawiki/SaruWiki/AdminSettings.php ln -s /etc/mediawiki/SaruWiki/LocalSettings.php (even if you don't have the ''AdminSettings.php'' file yet, you can still make that link). For the second bit, we edit # We define this to allow the configuration file to be explicitly # located in /etc/mediawiki. # Change this if you are setting up multisite wikis on your server. define('MW_INSTALL_PATH','/opt/mediawikifarm/saruman.biz'); This should be enough! Restart Apache2 and test the result invoke-rc.d apache2 restart ==Adding more MediaWiki instances to your farm== So how do you now prepare the next wiki in your farm? Quite simple. We're now going to set up the next wiki in the default place, being ''/var/lib/mediawiki'', after which we can return to the previous step of [[Create_a_Wikifarm#Linking_to_the_shared_code_base|creating another copy of the code base]] and again move the new wiki over from the default location to its location in our fresh wiki farm. So we need to set up the next website with access to the (now empty) default wiki location. We say "now empty" because the default location is lacking a ''LocalSettings.php'' file. In essence then, it is again an empty wiki, for which we'll have to run through the steps of basic configuration, as described in [[Basic_MediaWiki_Installation|basic MediaWiki installation]]. First off, we'll link the next virtual website to the default wiki location. Suppose the next virtual website is called "iceditch.nl", and our wiki database will be called IceditchWiki. We'll start off by creating a location for the IceditchWiki configuration files under the MediaWiki configuration directory: cd /etc/mediawiki mkdir iceditch.nl cp apache.conf iceditch.nl/apache.conf Next, we'll instruct our virtual host to load this new MediaWiki apache configuration file: cd /etc/apache2/sites-available vi 010-iceditch.nl Inside of this virtual host file, we include the MediaWiki configuration; the virtual host file then looks something like this: <VirtualHost *:80> ServerName www.iceditch.nl ServerAdmin webmaster@iceditch.nl DocumentRoot /var/www/iceditch.nl <Directory /> Options FollowSymLinks AllowOverride None </Directory> <Directory /var/www/iceditch.nl> Options Indexes FollowSymLinks MultiViews AllowOverride None Order allow,deny allow from all </Directory> Include /etc/mediawiki/iceditch.nl/apache.conf ScriptAlias /cgi-bin/ /usr/lib/cgi-bin/ <Directory "/usr/lib/cgi-bin"> AllowOverride None Options +ExecCGI -MultiViews +SymLinksIfOwnerMatch Order allow,deny Allow from all </Directory> ErrorLog /var/appslog/apache2/iceditch.nl-error.log # Possible values include: debug, info, notice, warn, error, crit, # alert, emerg. LogLevel notice CustomLog /var/appslog/apache2/iceditch.nl-access.log combined </VirtualHost> Now restart Apache2, and visit the link designated to the new wiki, in this case ''<nowiki>http://www.iceditch.nl/mediawiki</nowiki>''. You'll get the familiar "please set up the wiki first" message. Click it, and manually configure your new wiki. When you're done, move the created ''LocalSettings.php'' to ''/etc/mediawiki'' and you're set! Your new wiki is running in the default position, and as soon as you've moved it to the wikifarm, you can create yet another wiki! 9000cf305ced701ffed85880282c2b74def852f2 2392 2391 2009-03-05T18:52:35Z Saruman! 2 Extensions section started wikitext text/x-wiki ==On Wikifarms== ===What is a Wikifarm?=== Wikifarm and the verb Wikifarming refer to the setup and operation of multiple wikis on a single server. This could be because on a single website you want to run multiple wikis (e.g. ''<nowiki>http://www.saruman.biz/linuxwiki</nowiki>'' and ''<nowiki>http://www.saruman.biz/bsdwiki</nowiki>''). Or it could be because you're running multiple websites on a single server (each behind its own IP, or all on the same IP number using virtual hosts), and more than one of these websites needs to have its own wiki. ===Types of Wikifarms=== There are multiple ways to set up a wikifarm; what is the most suitable way for you depends on how you want to use the farm. We can roughly distinguish the following type of farms: * Multiple wikis, each running '''their own code and their own database'''. This is simple to set up when you install the Wiki code base from source - funny enough, under Debian it's ''not'' easy. Also, it's not a recommendable solution from the perspective of maintenance: each wiki must be updated separately when e.g. a security patch is issued for the wiki software. * Multiple wikis, running on '''a shared code base, but each with their own database'''. This is a good solution for multiple wikis for multiple websites. * Multiple wikis, running on '''a shared code base, and on a shared database'''. This could be a good solution for multiple wikis for a single website, because a user can register on one wiki, and automatically have the same account in the other database as well. We're not going to go into the first type, since the shared codebase is more maintainable. Instead, we're going to show how you can share the Mediawiki code base under Debian, so that a Debian update to the Mediawiki package is automatically applied to all instances of your wikifarm. And we'll see that from there, the choice between separate databases or shared databases is quite trivial. ===Wikifarming under Debian=== As with most Linux-based software packages, the MediaWiki package ''mediawiki'' that Debian offers is modified to suit the Debian policies and needs. This means that it has moved all configuration files to reside under ''/etc/mediawiki'', but also that it offers a somewhat better way to include extensions. The downside of these modifications is that creating a wikifarm under Debian is somewhat more complicated than when you're using vanilla MediaWiki sources - mostly because there isn't much documentation on the Internet about it. In the following we'll be documenting one possible way to create a wikifarm. Note that our method is particularly well-suited to "small" wikifarms (a handful of wikis on a single server), and not exactly fit for "big" wikifarms (thousands of wikis on one or more servers). ==General procedure to creat a wikifarm wiki instance== Setting up a wiki under Debian is quite easy - as you might have seen from this wiki's description under entry [[Basic MediaWiki Installation]]. This is because the Debian customization includes specific changes to some MediaWiki files, and to the default configuration files. Thus, the usual methods of creating a wiki instance next to the default one run into an additional obstacle: the forementioned Debian customizations. The way around it is this: * We suppose you've already installed your first wiki. It'll probably be just as described in the [[Basic MediaWiki Installation]]. * Make sure you adapt this first wiki to support virtual hosts, as described in the section on [[Place_MediaWiki_inside_a_Virtual_Host|placing MediaWiki inside a Virtual Host]]. * If your first wiki is running OK, follow the instructions in the next set of sections to move the wiki from its default place to the wikifarm. As a result, your first wiki should still run OK, but the place where Debian expects your wiki to live is now "empty" again * Set up your second wiki as if it were the first one, and move it over to the wiki farm. * et cetera. Because of the manual work involved, this system is not very well suited to "big" wikifarms; for those instances you'd be better off with one of the scripts that creates the wikifarm instance, and populates it with a default database and default configuration file. Scripts and instructions can be found on the Internet, like this one [http://www.jirp.nl/2008/04/11/mediawiki-farm-multiple-wiki/ on jirp.nl].<br> However, the method is quite doable when you've only got a handful of wikis to create, and remains largely compatible with Debians mechanisms for updating packages. ==Debian Mediawiki wikifarm structure== ===The standard Debian MediaWiki structure=== After installation of the ''mediawiki'' package, your server will be expanded with the [[MediaWiki directory structure]]. Within this structure, there are four main branches (if you haven't installed the ''mediawiki-extensions'' package yet): * ''/etc/mediawiki'' contains the configuration files for MediaWiki. * ''/usr/share/doc/mediawiki'' contains the documentation files. * ''/usr/share/mediawiki'' contains the source code. It is not used directly, rather it is linked to from the ''/var/lib/mediawiki'' directory. * ''/var/lib/mediawiki'' contains the site, including links to the configuration files in ''/etc/mediawiki''. Within these branches, we should not delete or move any file or directory, since that will confuse our [[APT and aptitude|Debian package manager]] when an update to the ''mediawiki'' package becomes available, so we strive to minimize the changes to this structure. Furthermore, the default configuration files explicitly declare the wiki to "live" in ''/var/lib/mediawiki'', so we'll designate the wiki in that location as the "default wiki" as opposed by "wikifarm instances" that live e.g. under ''/var/wikifarm/<instancename>''.<br> Another important element of the MediaWiki structure is hidden in its use of the MySQL database: during setup, you either need to have a database user account, or a MySQL superuser account (e.g. 'root'@'localhost') so as to be able to create the wiki database and a database user account. ===Extending the structure for a wikifarm=== First we need a label <instancename>, which designates the name for each wikifarm instance, so that we can label them as we're creating them. Each name needs to be unique because we're going to create directories based on the labels. Note that this label need not be the Wiki name, as you fill it in when [[Basic_MediaWiki_Installation#Configuring_the_Wiki_instance|configuring the default wiki instance]], although you could of course use that name. In our example, we use the domain name of the website on which the wiki instance is running. Thus, this wiki named "SaruWiki" is instance "saruman.biz" in our little wikifarm. Furthermore, you need a database name for each wiki instance that gets its own database, and it should be different from the default database name "wikidb" (unless you ''want'' to put your wiki instance into this default database, together with the wiki or wikis that are already in there). You could use the label you've chosen, or different ones, or derived ones. Remember to observe the MySQL [http://dev.mysql.com/doc/refman/5.0/en/identifiers.html limits on database names] (no more than 64 characters, no slashes or dots in the name, not ending in a space et cetera).<br> In addition, you need a database user name and password. This should not be the same user name and password that you've used to set up any other wiki database, or you'd have a security risk. In the unfortunate case in which you'd feel compelled to reuse a database user name (e.g. the standard "wikiuser"), be sure to reuse the original password of "wikiuser", or risk losing access to the earlier wikis that use that same user. Thus, you could have labels, database names and database username/passwords like this: * saruman.biz and saruman-biz-wiki and saruwikiuser/Gp5Zmull01 * iceditch.nl and iceditchNLwiki and icewikiuser/Br3thReeka1 * ann.example.org and wiki-ann and ann/Tr4p7qqhl2 * bob.example.org and wiki-bob and bobwiki/Gnff3Prkks * charles.example.org and wikiCharles and charles/Pzmel55Fgzxm And remember, they are just labels. You could just as easily use user names, numbers or whatever. For maintainability though, we recommend a consistent scheme with recognizable labels. On the other hand, there are a number of labels you must avoid, because they will come to conflict with directories that already exist: most notably ''config'', ''extensions'' and ''images''. So before you begin, sit down and write out what your label and database name convention will be. This is trivial if you have just a handful of wikis, but can become very important should you ever grow to hundreds of instances. Each wikifarm will need its own set of configuration files, so for each new wiki instance we'll create directories under ''/etc/mediawiki'' using the chosen wiki labels: * ''/etc/mediawiki/saruman.biz'' * ''/etc/mediawiki/iceditch.nl'' * et cetera. Make each of these directories owned by the Apache2 user (''chmod www-data:www-data saruman.biz'' et cetera). Each wikifarm will need its own code base, so for each new wiki instance we'll create directories under ''/opt/mediawikifarm'' using the wiki labels: * ''/opt/mediawikifarm/saruman.biz'' * ''/opt/mediawikifarm/iceditch.nl'' * et cetera. The choice for ''/opt/mediawikifarm'' is quite arbitrary; one could make a case to use ''/var/www'' or ''/var/lib/mediawikifarm/'' or anything like this, but ''/opt'' is meant for optional software, which under Debian is software that's not in the standard repositories. And since the wikifarm isn't, it makes sense to create the links to the codebase there. Each wikifarm may have its own upload directory for images. This directory should not be placed under ''/opt'', but rather in a place where you expect data, e.g. ''/data'' if you have that, or ''/var/www'', or something like this. We have chosen for ''/data/wikifarm/<wikilabel>/images''. ==Linking to the shared code base== As you can see from the [[MediaWiki directory structure]], the code that is actually served in the webserver is in two separate trees: by default the webserver ''thinks'' the full tree is in ''/var/lib/mediawiki'', but a large part of what you find in that spot is actually symlinked to files and directories in ''/usr/share/mediawiki''. Actually, the tree ''/usr/share/mediawiki'' can be thought of as a source code library, and ''/var/lib/mediawiki'' as the instance that we're actually serving. Since an instance needs both source code and some files of its own, we find that ''/var/lib/mediawiki'' contains both links to that source code, as well as actual files and directories. Now we can create links to the code base for each wikifarm instance for themselves. You need to create symlinks in your chosen wiki directory (e.g. ''/opt/mediawikifarm/saruman.biz'') to all files and folders in ''/usr/share/mediawiki'', except the directory ''images'' and the files ''AdminSettings.php'' (if it even exists) and ''LocalSettings.php''. Such a thing can be done simplest with a little script like this: <source lang="bash"> WSRC='/usr/share/mediawiki' WDEST='/opt/mediawikifarm/saruman.biz' cd $WSRC for s in *; do ln -s $WSRC/$s $WDEST/$s done cd $WDEST unlink images unlink AdminSetings.php unlink LocalSettings.php </source> Either run this at the command prompt, or bake it into a little Bash script (it could take the destination directory as a parameter to make it reusable). ==Recreating (moving over) your first MediaWiki instance== We'll assume you've followed the other tips in this wiki. Most notably, you've taken all steps described in the article on "how to [[Place MediaWiki inside a Virtual Host]]". The steps are simple ===Move the Wiki configuration within /etc=== Your Wiki config file will be ''/etc/mediawiki/LocalSettings.php'', and the settings for Apache2 will be in ''/etc/mediawiki/apache.conf''. We'll create a subdirectory under ''/etc/mediawiki'' that hosts the configuration of your Wiki. Suppose we name the subdirectory after the Wiki we're handling, in this example the SaruWiki. Furthermore, suppose that you also have an ''AdminSettings.php'' file. If you don't: no worries! Just skip the steps involved with that file! cd /etc/mediawiki mkdir SaruWiki mv LocalSettings.php SaruWiki mv AdminSettings.php SaruWiki mv apache.conf Saruwiki Note: make sure that after moving the files, the owner and permissions are the same. Moving a file while you are ''root'' has the effect of changing ownership to ''root''. ''LocalSettings.php'' must be owned by user:group ''www-data:www-data'' in order for Apache2 to be able to read the file. The ''AdminSettings.php'' file, if it exists, must be owned by ''root:root'' and NOT be readable by world (permissions 600) because it should contain the MySQL "root" username and password, with which maintenance scripts can perform their tasks if you instruct them to (while you are root, of course). To keep the Wiki running, we're going to need to tell Apache2 where the two files went to. In this case: * change the path to ''apache.conf'' in the ''Include'' statement in the site declaration (e.g. in ''/etc/apache2/sites-available/000-saruman.biz'', change the ''Include'' line to Include /etc/mediawiki/SaruWiki/apache.conf * change the symlink in ''/var/lib/mediawiki'' that points to ''LocalSettings.php''; and if you have one, change the ''AdminSettings.php'' symlink as well: cd /var/lib/mediawiki unlink LocalSettings.php ln -s /etc/mediawiki/SaruWiki/LocalSettings.php unlink AdminSettings.php ln -s /etc/mediawiki/SaruWiki/AdminSettings.php If you now restart Apache2, your Wiki will still work - but the two primary configuration files have moved over to a dedicated spot. Also note that you're not yet using the new codebase - that comes later. ===Move the Wiki website=== So what we now need to do, is to tell the webserver that the full tree can be served from the codebase we prepared. To this end, we need to change the apache2 configuration file ''apache.conf'' of the Wiki, that we've previously copied over to the Mediawiki configuration directory ''/etc/mediawiki/SaruWiki'' and that's included in the Virtual Host file of the saruman.biz website. This file needs to point to the new shared code location; it will look something like this: Alias /wiki /opt/mediawikifarm/saruman.biz <Directory /opt/mediawikifarm/saruman.biz/> Options +FollowSymLinks AllowOverride All order allow,deny allow from all </Directory> # some directories must be protected <Directory /opt/mediawikifarm/saruman.biz/config> Options -FollowSymLinks AllowOverride None </Directory> <Directory /opt/mediawikifarm/saruman.biz/upload> Options -FollowSymLinks AllowOverride None </Directory> Note that we haven't created the upload directory (but we can if we ever need it). Also note that we haven't created the ''config'' directory; that is because we don't need that in this wikifarm instance, because this particular instance has already been configured. Furthermore, we now need to make sure Apache2 can find the (working) ''LocalSettings.php'' from the new wiki location ''/opt/mediawikifarm/saruman.biz'', '''AND''' we need to change a setting within ''LocalSettings.php'' to reflect the new wiki location. For the first bit, we make the correct link(s): cd /opt/mediawikifarm/saruman.biz ln -s /etc/mediawiki/SaruWiki/AdminSettings.php ln -s /etc/mediawiki/SaruWiki/LocalSettings.php (even if you don't have the ''AdminSettings.php'' file yet, you can still make that link). For the second bit, we edit # We define this to allow the configuration file to be explicitly # located in /etc/mediawiki. # Change this if you are setting up multisite wikis on your server. define('MW_INSTALL_PATH','/opt/mediawikifarm/saruman.biz'); This should be enough! Restart Apache2 and test the result invoke-rc.d apache2 restart ==Adding more MediaWiki instances to your farm== So how do you now prepare the next wiki in your farm? Quite simple. We're now going to set up the next wiki in the default place, being ''/var/lib/mediawiki'', after which we can return to the previous step of [[Create_a_Wikifarm#Linking_to_the_shared_code_base|creating another copy of the code base]] and again move the new wiki over from the default location to its location in our fresh wiki farm. So we need to set up the next website with access to the (now empty) default wiki location. We say "now empty" because the default location is lacking a ''LocalSettings.php'' file. In essence then, it is again an empty wiki, for which we'll have to run through the steps of basic configuration, as described in [[Basic_MediaWiki_Installation|basic MediaWiki installation]]. First off, we'll link the next virtual website to the default wiki location. Suppose the next virtual website is called "iceditch.nl", and our wiki database will be called IceditchWiki. We'll start off by creating a location for the IceditchWiki configuration files under the MediaWiki configuration directory: cd /etc/mediawiki mkdir iceditch.nl cp apache.conf iceditch.nl/apache.conf Next, we'll instruct our virtual host to load this new MediaWiki apache configuration file: cd /etc/apache2/sites-available vi 010-iceditch.nl Inside of this virtual host file, we include the MediaWiki configuration; the virtual host file then looks something like this: <VirtualHost *:80> ServerName www.iceditch.nl ServerAdmin webmaster@iceditch.nl DocumentRoot /var/www/iceditch.nl <Directory /> Options FollowSymLinks AllowOverride None </Directory> <Directory /var/www/iceditch.nl> Options Indexes FollowSymLinks MultiViews AllowOverride None Order allow,deny allow from all </Directory> Include /etc/mediawiki/iceditch.nl/apache.conf ScriptAlias /cgi-bin/ /usr/lib/cgi-bin/ <Directory "/usr/lib/cgi-bin"> AllowOverride None Options +ExecCGI -MultiViews +SymLinksIfOwnerMatch Order allow,deny Allow from all </Directory> ErrorLog /var/appslog/apache2/iceditch.nl-error.log # Possible values include: debug, info, notice, warn, error, crit, # alert, emerg. LogLevel notice CustomLog /var/appslog/apache2/iceditch.nl-access.log combined </VirtualHost> Now restart Apache2, and visit the link designated to the new wiki, in this case ''<nowiki>http://www.iceditch.nl/mediawiki</nowiki>''. You'll get the familiar "please set up the wiki first" message. Click it, and manually configure your new wiki. When you're done, move the created ''LocalSettings.php'' to ''/etc/mediawiki'' and you're set! Your new wiki is running in the default position, and as soon as you've moved it to the wikifarm, you can create yet another wiki! ==Debian extensions and your wiki farm== So how about those interesting MediaWiki extensions? Well, if you've [[Mediawiki-extensions_under_Debian|installed package ''mediawiki-extensions'']] then you've got a default structure for handling extensions, that's slightly more intelligent than the standard MediaWiki way, ''and'' helps us a long way towards different extension configurations for our wikis in the farm. In advance we offer you the following information: after installation of ''mediawiki-extensions'', the Debian version of MediaWiki allows you to enable and disable extensions by simply running the command ''mwenext <extension>'' or ''mwdisext <extension>'', e.g. mwenext ConfirmEdit.php It does this by having a directory with symlinks to all availabe extensions, and another directory where you can symlink those extensions that you want enabled. Now this mechanism can be extended to the wikifarm in two different ways: # Per wiki a different selection of all installed extensions is made available. Per wiki in the farm, a selection of those extensions ''that are available to THAT wiki instance'' can be enabled. # All extensions that are installed are available to all wikis in the wikifarm, but for each wiki a different selection can be enabled. We will not describe the first case, but rather the second one. d3aa1f15586320eb058ba61da03fa763dd874926 0 1476 2393 2004 2009-03-30T20:08:34Z Saruman! 2 Added manual Zaptel compilation wikitext text/x-wiki =Zaptel driver= ==Prerequisites== To compile the Zaptel driver, we first install support for certain functions (a.o. deflate compression method): sudo apt-get install zlib1g-dev libssl-dev bison debhelper Specifically the last one (''debhelper'') can bring a whole slew of extra packages with it, a.o. ''build-essential'', ''po-debconf'', ''liburi-perl'' and ''patch'', just to name a few. ==Debian version of Zaptel== Next up is to get the zaptel source code, as is delivered with Debian Lenny. Note, however, that as of march 2009, this driver has a little bug in the ''ztdummy'' driver that prevents the driver to compile under a 2.6.28 kernel. If you have a custom kernel (i.e. not the Debian stock kernel) then skip down to the ''next'' section! For plain Debian Lenny: sudo apt-get install zaptel-source If there are any dependencies not yet satisfied, you'll see those packages come with the source code (e.g. ''module-assistant''). Once the Zaptel source code is on our system, it is up to us to create the driver. Debian can't handle this for us, as the Zaptel driver has to precisely match both our hardware platform and the Linux kernel we're using. So we're going to compile our own driver - yippee!<br> Debian has placed the source file package in ''/usr/src'', and it's named ''zaptel.tar.bz2''. Normally you would think about unpacking it with ''sudo tar xjvf'' and get going with the code that's in it. HOWEVER Debian has a really cool utility called the ''module-assistant''. This program is the command-line tool for handling module-source packages that have been prepared for the Debian distribution. It helps users to build and install module packages easily for one or more kernels, even custom ones. We start from the beginning: * boot your system under the kernel for which you want to create the Zaptel drivers, if you haven't already done so * as root, run ''module-assistant prepare''. This checks the availability of your kernel source header files, creates a symlink ''/usr/src/linux'' that points to your kernel source files, and checks if you have all Debian packages you're going to need (e.g. ''build-essentials''). * Then, again as root, run ''module-assistant auto-install zaptel'' (or abbreviate it to ''m-a a-i zaptel''). After a while (may be multiple minutes) the command completes.The output hopefully ends with something like "Setting up zaptel-modules-2.6.27.5 (1:1.4.11~dfsg-2) ..." - note: the number before the parenthesis should match the kernel version for which you're compiling the module - in this case we're running kernel 2.6.27.5, and the Zaptel module we've compiled is for this specific kernel. * Some howto's now instruct you to run ''update-modules'', but with modern Debian distributions like 4.0 "Etch" or 5.0 "Lenny" this is not the case; running it won't harm you, because there's a pseudo-command installed, but it won't do a single thing either... * If you have hardware installed, you now run ''genzaptelconf -svdM''. It will stop any Asterisk you might have running, be verbose, detect any modules on your hardware, update ''/etc/modules'', and finally create your hardware config file ''/etc/zaptel.conf''; it probably will give you a nice error message too about not being able to write in the ''/etc/asterisk'' directory - that's simply because we haven't installed asterisk itself yet! Note: if you live outside the U.S.A., you might want to specify which country you live in, to get the correct dialing tones etcetera. It is as simple as specifying your country (two-letter code): ''genzaptelconf -svdM -c nl''. The output is pretty clear in what the command finds, and what it does with that information. * You may want to now edit the configuration file that's created for the channels. The configuration file should be ''/etc/zaptel.conf'', and its contents could look like the file given below. However, you rarely need to edit this file by hand: ''genzaptelconf'' can handle this bit usually better than we can. # Span 1: WCTDM/0 "Wildcard TDM410P Board 1" (MASTER) fxols=1 fxols=2 fxsks=3 # channel 4, WCTDM/0/3, no module. # Global data loadzone = us defaultzone = us * If you wish, you can create directory ''/etc/asterisk'', and run the ''genzaptelconf'' again; that way you can see the ''zapata-channels.conf'' file that is created as well. * If you now reboot (into the same kernel), then the ''dmesg'' command should confirm the presence of your Zaptel drivers with a short section like this: Zapata Telephony Interface Registered on major 196 Zaptel Version: 1.4.11 Zaptel Echo Canceller: MG2 Furthermore, you can find lines like these, if you have hardware installed: ACPI: PCI Interrupt 0000:03:07.0[A] -> GSI 21 (level, low) -> IRQ 21 Port 1: Installed -- AUTO FXS/DPO Port 2: Installed -- AUTO FXS/DPO Port 3: Installed -- AUTO FXO (FCC mode) Port 4: Not installed VPM100: Not Present Found a Wildcard TDM: Wildcard TDM410P (4 modules) ==Digium Zaptel driver for your custom kernel== In March 2009 I decided to upgrade my custom-configured vanilla kernel from 2.6.27.5 to 2.6.28.9. After that, I found I couldn't compile the Debian Zaptel driver, because of an error in the compilation of ''ztdummy''. The error looked something like this: CC [M] /usr/src/modules/zaptel/kernel/ztdummy.o /usr/src/modules/zaptel/kernel/ztdummy.c: In function 'ztdummy_hr_int': /usr/src/modules/zaptel/kernel/ztdummy.c:203: error: 'struct hrtimer' has no member named 'expires' make[4]: *** [/usr/src/modules/zaptel/kernel/ztdummy.o] Error 1 make[3]: *** [_module_/usr/src/modules/zaptel/kernel] Error 2 make[3]: Leaving directory `/usr/src/linux-2.6.28' make[2]: *** [modules] Error 2 make[2]: Leaving directory `/usr/src/modules/zaptel' make[1]: *** [binary-modules] Error 2 make[1]: Leaving directory `/usr/src/modules/zaptel' make: *** [kdist_build] Error 2 The solution to this was either to: * go back to a 2.6.27 kernel (I didn't want to), * get my hands on an updated Debian Zaptel package that was not released yet (''zaptel 1:1.4.11~dfsg-4'') (couldn't get it), * find a way to patch the Debian Zaptel source code (couldn't figure out how), * or use the latest Digium Zaptel driver from [http://downloads.digium.com/pub/zaptel/ their website]. It turned out that even the latest Zaptel driver from Digium (version 1.4.12.1) couldn't compile because of this error. But after a while I found this solution: I downloaded the latest ''SVN snapshot'' from the Digium website (release r4636), instead of the tarball with the latest stable release (revision r4504), and manually compiled and installed that. The way I did that was (with only a little explanation): # Get Subversion, and make sure we have three necessary packages apt-get install subversion apt-get install build-essential libnewt-dev libusb-dev # Go to /usr/src and get the 1.4 branch for Zaptel from Digium, in # the right revision cd /usr/src svn co --revision 4636 http://svn.digium.com/svn/zaptel/branches/1.4 mv 1.4 zaptel # go in the source directory, and compile cd zaptel ./install_prereq test ./install_prereq install ./configure make make install # Make a configuration if it doesn't exist already, and load the drivers make config modprobe zaptel modprobe wctdm24xxp # Of course the last driver is specific to my TDM410p =Zaptel tools= Next up, if you haven't yet done so during the preceding step, you now need to install the ''zaptel'' userland tools (v1.4.11 under Debian 5.0), which will in turn require ''fxload'' and ''libtonezone1''. Installation is simply performed by sudo apt-get install zaptel fxload libtonezone1 After installation, the ''zaptel'' driver checks for the existance of ''/etc/zaptel.conf''. When you've never before had Zaptel on your system, or haven't finished configuration in the preceding step, then you probably get the message zaptel : /etc/zaptel.conf fails test for exists and readable This is in fact a friendly reminder that you first have to create this file, before you try to load the driver. =libpri installation= Asterisk needs the ''libpri'' package; not only to handle ISDN-cards, but also for some other functions (although currently I don't know which ones :-). Before installing Asterisk, you could start by installing this package. In Debian 5.0 "Lenny", the packages is named ''libpri1.0'': apt-get install libpri1.0 b7787a127f4293ba8be7070c1aa79c42a8fb452b 0 1409 2394 1630 2009-04-18T19:22:35Z Insomnia 3 /* Partitioning */ added varlog LV wikitext text/x-wiki <big>'''Debian Lenny Base Server setup'''</big> ==Getting the hardware== {| class="wikitable" border="1" |- |Note: in the following we're assuming you'll be assembling an x86 or x64 type of machine, as it has about the best price/performance ratio you could wish. Hardware costs for other platforms, e.g. IBM's Series p or HP 9000, can be much higher, while platforms like ARM are just not very powerful. Also, the availability of components and of help can be less than with the ubiquietous x86/x64 platforms. |} Naturally, before we can begin to install the operating system, we need to obtain the necessary hardware. Which hardware you require depends on what you want the server for; a testserver on which you will test only a single feature for a short while does not need the same quality of hardware as does a server that's supposed to act as a homeserver for many tasks for a long time. We'll assume your server will be like ours: a home server that must perform many tasks with sufficient performance for a few users, that's reliable and will last for a couple of years. So build or obtain a server with at least the following hardware: * a spacious casing with big, quiet cooling fans, like the [http://www.coolermaster.com/products/product.php?act=detail&id=317 one we have]; * an efficient, heavy-duty power supply that's rated high enough for your devices, and has a decent efficiency. For example, a [http://www.corsair.com/products/power_supplies.aspx Corsair HX520] power supply; * a server class motherboard, e.g. an [http://www.intel.com/products/server/index.htm?iid=home+hdr_nav2_server Intel] or [http://uk.asus.com/products.aspx?l1=9&l2=39&l3=263 AMD] based single-processor motherboard. DO NOT go for the cheapest motherboard you can find: if you pay peanuts, that's what you get. Server class motherboards have the quality, stability and durability you'll need from it, and usually also most of the needed peripherals, like multiple ethernet network cards on-board. Usually a Linux server doesn not require much in the way of video performance (and the screen will be used rarely, if ever), so any old integrated graphics will do. * a matching CPU - or multiple, if you think you need the power and the selected motherboard has the sockets. Furthermore, it pays to think about the energy use of your server CPU. For instance, you could choose an AMD Athlon X2 5600+, running at 2,8 Ghz and 89W maximum, but you can also go for an AMD Athlon X2 4850E, which is dualcore at 2,5GHz, but uses only 45W maximum - almost half of the former! And over a one year period, this choice can save up to 385 kWH. With electricity costing close to €0,20 per kWH (at least for some of us), that could save you €77,- a year. All I'm saying is: think about power use. * a CD-ROM- or DVD-player - although you might not need it any more after installation. * ''multiple'' harddisks - you'll want redundancy, because every harddisk fails at some time. The drive with your data on it will fail fatally when it is most inconvenient to you, and any data on it that you consider valuable will likely be lost forever. To make Murphy's work somewhat harder for him, we're going to store our data redundantly, so that if any drive in the server fails, we'll not lose our data or our server. Thus, get yourself at least two harddisks for your operating system, at least 40GiB in size (don't think you'll be able to buy smaller ones nowadays), and spanking new (NEVER use old harddisks for your production server, new ones are just too cheap to run that risk!). * (multipe) network card(s) (NICs) if your motherboard does not have enough NICs integrated on-board. You'll want a NIC for your network, and another one for your Internet connection; and possible a third one for the wireless segment of your network. Now build a machine out of the above, or have someone build it for you. ==Preparation of the hardware== (Note: in the following we're again assuming you're running an x86/x64 type of machine. Hardware requirements and preparation for other platforms, e.g. IBM's Series p or HP 9000, can differ significantly) Next, check the assembled hardware: * is the configuration complete? If it does not have a CD/DVDplayer from which it can boot, then installing the software gets more difficult - at least get an USB external DVDdrive or something like that. * are all components connected properly (memory DIMMs seated correctly in their sockets, AGP card inserted correctly into the AGP slot, et cetera) and are all cable connections made (multiple power cables to the motherboard, one power cable plus one data cable to each hard disk, etcetera)? Following this, you may hook up the machine. It's going to need power, and you will need at least a keyboard and a monitor attached. And if you want to use a Graphic User Interface to install, a mouse is required also. When you've ensured that everything is safe, you can turn on the machine, and continue to check it: * do all fans start to run when you turn on the machine? (if not, then '''quickly''' turn off your machine and correct the problem!) * does/do the hard disk(s) spin up? * do the power button and reset button operate correctly? * are the power led, HDD led and other display gadgetry functional? * when you let the machine power up, does it emit a single beep? And does it then show a Power-On Self Test screen (POST)? * Does it show the correct amount of memory in the POST screen? The correct number & speed of the CPU(s)? * Does the machine recognise all controller cards (SCSI, S-ATA etc)? And all attached DVD-drives and hard disks? * are all BIOSes/firmwares up to date? * If you have a hardware RAID controller, are your RAID arrays built already? * does the machine attempt to boot from at least the hard disk? ...et cetera. If there is any problem, or you want to update the BIOS or firmwares, it's best to do it before the operating system is installed. This Wiki, however, is not the place (yet) to get the information on how to accomplish these type of tasks. The last steps in the preparation of the hardware, are * to ensure that the machine can boot from CD/DVD, so that you can start installing Debian from it. It is possible to install Debian over the network, but that requires setting up a [http://www.debian-administration.org/articles/478 PXE Boot server] which is (currently) outside the scope of this wiki. * to connect the hardware to the Internet, so that it can get all required updates etcetera; please do ''not'' connect the box ''straight'' to the Internet, but make sure that it's safely behind a firewall, or failing that, a NAT router. By now the system should be almost ready to receive it's Operating System. But first we have an issue to tackle: that of redundancy. ==Software or hardware RAID== Your hard disks will fail. They absolutely will. It is never a question of "if", only of "when". So what will you do when the hard disk containing your complete operating system fails (besides pulling your hair out, that is)? What we propose is this: hard disks are pretty cheap nowadays, so let's use [http://en.wikipedia.org/wiki/Redundant_array_of_independent_disks RAID technology] to make our hard drive space resilient against failure of a whole drive. So first make sure that you have ''two'' disks of equal size instead of only one. Had you already been planning to use multiple disks already, then make sure you have at least ''one'' disk more than your space requirements prescribe; the space on that extra drive will provide the needed redundancy. Next, [[RAID fundamentals under Linux | click here]] to learn a bit more about RAID, to make the decision to use hardware-based and/or software-based RAID, and to plan your RAID arrays. In this example, we'll assume you're using hardware RAID on a RAID controller that's supported by the Debian installation software. This means that the installation software will "see" your RAID array(s) and present them as usable drives. ==Planning your network names== If your machine must become a part of an existing network, then it's almost certain that you already have a DNS domain in place; in that case: obtain the DNS suffix your machine will get (the DNS domain your machine will "belong" to). However, it's also possible that this machine is going to be the first machine in your new network, in which case the whole issue of DNS suffixes is wide open. If you need more information on DNS, go [[http://www.isc.org/sw/bind/arm95/Bv9ARM-all.html#id2564824 here]]. For now we'll assume you have (or will quickly obtain) a working knowledge of the DNS system. Here is our tip on choosing a DNS domain for your home network: * do '''not''' use a publicly registered domain name (e.g. "cocacola.com") for any machine that's not primarily intended to serve the public on the Internet; * for machines serving a private network, we urge you to use Top Level Domain name "lan" (to signify your machine is on a Local Area Network or LAN) * for the Domain Name itself, we suggest you use a level 2 name, like "saruman.lan", and not a level 3 name, like "mister.saruman.lan". This is only a short section on DNS, but remember that once a proper DNS system is in place, it's pretty much work to change it. At any rate, this section has most likely showed you that you need to put some thought into the DNS Domain Name design of your home network. OK, with this out of the way, we can get to installing the OS. ==Operating System installation== To install an Operating System (OS), it's kinda instrumental that you have one. Here, we're going to use [http://www.debian.org/intro/about Debian], the biggest [http://www.debian.org/intro/about#free Free] OS that we know of. Free stands for Freedom, but incidentally that Freedom also means it's gratis, an appealing aspect of Free. To get your own copy of Debian, go to their [http://www.debian.org/distrib/ download site] and obtain the latest [http://www.debian.org/releases/ Stable] image - in this wiki it's Debian 5.0, or "Lenny" as it's also known (although it wasn't stable at the time of writing this). Besides the choice which release of Debian you want to run, you also have to know for which platform you're downloading (in our case: either ''amd64'' or ''i386'' depending on your hardware platform) and what kind of install you wish - if you have a working, fast Internet connection available at the time of install, then we recommend getting the [[http://www.debian.org/CD/netinst/ netinst] CD image; it's a relatively small CD, that'll be able to get you going, but gets most of the software you'll need straight from the 'net at install time. In the example at hand we're installing on an AMD Athlon x2-based server, on which we wish to install 64-bits software. We'll download [http://cdimage.debian.org/cdimage/weekly-builds/amd64/iso-cd/debian-testing-amd64-CD-1.iso debian-testing-amd64-CD-1.iso], which is Lenny, not yet stable at the time of writing. Burn this to a CD-recordable and boot your prepared hardware platform from this CD. After booting from the CD, a friendly prompt invites you to indicate how you want to start installing (image 1). Your choices are listed under &lt;F3&gt;; we're going to use the standard Command Line installation, so we choose "install" and hit &lt;enter&gt;. {| class="wikitable" border="1" |- |We could easily use "Graphic install", in which case we'd have a nice fresh Graphical User Interface for our installation. ''We're'' not going to, because we're real men, and [http://isg.ee.ethz.ch/tools/realmen/ Real Men Don't Click]. Also, we've found that from the GUI it's hard to switch to a second console and then back. We could also go to the Advanced options (image 2), and opt for "Expert install" or "Graphical expert install" as installation method, because it gives a much finer grain of control; however we usually don't need that control, and can do without the barrage of extra questions that the "expert" installation method pose. |} After the Linux kernel finishes initializing the machine, a simple text-based installer appears (image 3) that immediately starts asking questions. Answer them according to your needs. Our example system uses the following choices: * Language: english * country: other &gt; Netherlands * keymap: American English (since we have a keyboard with US layout) Some installation software loads, and we get to the next phase: if you have multiple NICs in your machine (which we believe you ''should'' have!!), and if they're detected properly, then you're required to indicate which of the detected network interface cards (NIC) is going to be the "primary" NIC. {| class="wikitable" border="1" |- |Here, trouble could begin. If your machine has only network cards that are '''not''' supported, then you'll see '''no''' cards here - but then how are you going to do a NetInstall? A solution would be to (temporarily) install a NIC that ''is'' supported, like a cheap Realtek card, or an old 3Com 905 card. Then, when the whole system is installed, up and running, you could compile a new kernel that contains support for your actual NICs, and when these work, remove the temporary NIC. For now, we'll assume that at least one of your NICs is recognised properly by the Debian installation routine. |} Select the card that's connected and has (indirect) access to Internet (again: it should ''not'' be connected straight to the wild wild web, but sit safely behind a firewall, at least until we've installed our own firewall); if at all possible, let it be the NIC that'll be connected to your home network itself, on the ''inside'' of your server. Let's assume that this NIC is designated ''eth0'' by the Debian installation. This card will now be configured using DHCP, so if you're on a network with a DHCP-server, the network will work straight away. If it's not, you can either configure the network manually or fix your DHCP-server and connection between it and ''eth0''. Next is one of the hardest questions that any OS installation is going to ask you: what will be the host name of the system? You could change it at any time in the future, but with lots of hassle, so you better choose wisely. Here are our tips: * do '''not''' name your machine after the user that's going to use it, e.g. "bernie-pc" (at some time in the future, Bernie's machine will be moved to Alice, so then Alice is working on "bernie-pc" which makes the situation quite unclear); * do '''not''' name your machine after the department or workgroup that's using it most, e.g. "accounting-srv" (same reasoning); * do '''not''' name your machine after it's main function, e.g. "printserver" (at some time in the future, the main function is moved to another machine, and/or an alternative function will become the main function of the machine); * do '''not''' name your machine after it's location, e.g. "srv-boston" (at some time in the future, the box will be moved to another location); * do '''not''' name your machine after it's hardware configuration, e.g. "ibmx346" (at some time in the future, either another xSeries x346 will be wheeled in, or the machine will be upgraded to accomodate increased use or overcome hardware problems - your "ibmx346" could suddenly be running on an xSeries x3650). What we feel are safe names for ''any'' machine in your network are true names, perhaps linked to a common theme: names of European cities, names of movie characters, names of countries or holiday destinations et cetera. Immediately following comes the question of the Domain Name. This is about a DNS domain, so effectively the installation program is asking which DNS suffix the host name should have; if the DHCP-server already provided something it'll be suggested, but you can override it if need be. In the preparatory phase, you'll have decided on continuation of your current DNS schema, or starting a new one. Either way, put the chosen DNS suffix in and press &lt;enter&gt;. ==Partitioning== Next comes the question of partitioning, or how to divide the available disk space into chunks for the server to use. This is a tricky subject, because if you put all storage space into one partition, then some day a runaway process will fill up the entire disk with useless logs, and the system will crash. On the other hand, if you divvy up all space into little chunks, then some application is going to need space in one of those partitions where there is none, even though there may be plenty in other partitions. To prevent both problems from occuring, we're going to use [http://tldp.org/HOWTO/LVM-HOWTO/whatisvolman.html Logical Volume Management (LVM)] so that we can provision enough space to start our server, but keep some space in reserve to apply when needed, where it'll be needed. So, we at Saruman.biz have put together a recommended standard partitioning scheme. The basis is this: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Partition !style="background:#ffdead;"|MD !style="background:#ffdead;"|LVG !style="background:#ffdead;"|LV-name !style="background:#ffdead;"|Size <br> (physical machine) !style="background:#ffdead;"|Size (VM) !style="background:#ffdead;"|File System !style="background:#ffdead;"|Mount point |- | 1 | /dev/md0 | &nbsp; | &nbsp; | 100MiB | 100MiB | ext3 | /boot |- | 2 | /dev/md1 | &nbsp; | &nbsp; | 3GiB | 1GiB | ext3 | / |- | rowspan="8" valign="top" | 3 | rowspan="8" valign="top" | /dev/md2 | rowspan="8" valign="top" style="background:lightgrey"| system | style="background:lightgrey" | swap | 1GiB<ref name="swap">Rule of thumb: twice the size of the machine's RAM, but no less than 256MiB and no more than 2GiB</ref> | 256MiB<ref name="swap"/> | swap | &nbsp; |- | style="background:lightgrey" | var | 1GiB | 512MiB | ext3 | /var |- | style="background:lightgrey" | varlog | 1GiB | 512MiB | ext3 | /var/log |- | style="background:lightgrey" | appslog | 3GiB | -<ref>Yes, we think a separate ''appslog'' is a very good idea, but when creating a minimal VM, we have to save disk space ''somewhere''...</ref> | ext3 | /var/appslog |- | style="background:lightgrey" | home | 1GiB<ref name="home">Note that this heavily depends on the purpose of the machine; if it is not to house any users, then (almost) no space is needed for /home. But on the other hand if e.g. a virtual user is to be used for keeping mailstores, or other service users need home space, then /home needs to be big enough for that.</ref> | 512MiB<ref name="home"/> | ext3 | /home |- | style="background:lightgrey" | usr | 3GiB | 3GiB | ext3 | /usr |- | style="background:lightgrey" | tmp | 1GiB | 512MiB | ext3 | /tmp |- | style="background:lightgrey" | opt | 1GiB | - | ext3 | /opt |- ! colspan="4" style="text-align:right"| Total ! 18.1GiB ! 6.9GiB ! colspan="2" | |- |} As you can see, the partition table works as follows: we assume that we wind up with 3 partitions, either on three separate software RAID arrays (''md0'' through ''md2'') or on one single hardware RAID array (in which case the 2nd column ''MD'' does not apply). The size of the partitions depends on your machine's make: for standard physical machines the 5th column does sensible suggestions, even though you could choose to have different sizes and of course different divisions altogether. If your machine happens to be a virtual one, running inside a [http://www.vmware.com/products/server/ VMware Server] or [http://www.vmware.com/products/vi/esx/ VMware ESX host], or the like, then you might want to start out with more modest partitions. The same holds for small servers that must run off Flash drives. Anyways, we're now at the Debian installation screen that lets us partition our disks. We're ''not'' going to use any of the "guided" partitionings, we go for "manual". Choosing that brings us to a screen showing all drives that the installation routine has detected, and all partitions on those drives that the installer can "see". We're going to do some assuming here once more: let's assume the drive(s) on which you want to install are visible, and are empty (containing no other partitions). <references/> ===Software RAID partitioning=== If you're to use software RAID, you now have to select the free space on the first drive, press &lt;enter&gt;, and then tell what you want to do with the free space: create a new partition, tell which size you want it to be (see table above), give the type of partition (primary), and give where on the disk it'll sit (the beginning). Next, a screen comes up that details how the partition you're requesting will be created. Here we make some changes: under "use as" we're going to select "physical volume for RAID". This clears all the other options in this screen, except for the "bootable" flag, which must be "on" for the first partition that we'll mount as ''/boot''. Now select "Done setting up the partition". Next, go to the free space on the second disk, and do ''exactly'' the same, to create an identical physical volume for RAID - if it's the first partition, select the "bootable" flag as well (we'll want to be able to boot from this second disk if the first disk fails, right?). Then go back to the rest of the free space on the first disk, make the second physical volume for RAID, duplicate it on the second disk. Then, go back to the rest of the free space on the first disk, make the third physical volume for RAID, and again duplicate it on the second disk. If you now go back to the "partition disks" overview, you'll see all the partitions you've specified listed on their respective disks. But at the top an extra option has appeared, called "configure software RAID". When you now select this option, the installer will ask if it may write the changes you've made to disk. This actually creates the partition tables on the disks. Note that at the end of configuring your partitions, an extra screen may appear (image 4): this asks if you care to identify which MD RAID devices must be started in order to be able to mount the root filesystem. Answering this question with a list of MD's like "md0 md1 md2" or simply "all" will let your server start the listed MD's very early in the boot sequence. ===Hardware RAID partitioning=== Now, if you have hardware RAID, then on your first (boot) disk just make 3 partitions, in the following manner: Select the free space on the intended boot disk, press &lt;enter&gt;, select "create a new partition", and fill out the desired size (100MB). Type is primary, location is beginning of the disk, and in the details of the partition, we only need to change the Mount point to "/boot", and set the Bootable flag to "On". Then we're "Done setting up this partition". The second partition is made the same way, but the desired size is 3GB, the Mount point is "/", and the Bootable flag remains off. Again, we're "Done setting up this partition". The third partition is again a primary partition, it takes up the entire rest of the disk, but the type is not ext3, but "physical volume for LVM". Again, we're "Done setting up this partition". But now from the main partitioner screen, we can access "Configure the Logical Volume Manager". The installer asks if it can write out the choices made to the disk, and then enters the LVM setup screen, which begins with a summary explaining that you have one Free Physical Volume, and nothing more. We now create a Volume Group (VG), which (in accordance to our partitioning standard) we'll call "system". In this VG, we'll add all Physical Volumes (being the one partition we've designated so in the previous step) using the space bar. Now we repeat the following process seven times: * select "Create Logical Volume" * select Volume Group "System" * give the LV Name (from the table, e.g. swap, var etc) * give the LV size (from the table, e.g. 1GB for swap etc) After this, we can select "Finish", the partitioner creates the seven LVs, and we're back at the partitioner screen, where there are now 7 extra "disks", with names such as ''LVM VG system, LV appslog - 3.2GB Linux device mapper''. Each of these "disks" has one block of empty space, which we now assign: seven times we repeat the following process: * select the unassigned chunk of empty space of an LV (e.g. appslog) and press &lt;enter&gt;; * Change "Use as: do not use" into the desired filesystem (ext3 - only the LV "swap" gets as filesystem type "swap area") * Change the mount point from "none" to the one corresponding with the name of the LV (note: the swap LV has no mountpoint; the appslog mountpoint must be entered manually as "/var/appslog") * If so desired, a label can be assigned to the partition (we usually don't) * select "Done setting up the partition" Once all this is done, we can look over the configuration once more, and then select "Finish partitioning and write changes to disk". A summary configuration screen will show, and we'll affirm with "yes" that these partitions can indeed be formatted. After some formatting screens flashing by (unless your partitions are particularly big, your system is particularly slow, or something goes wrong) the installation procedure continues. ==Final installer steps== Next comes one '''VERY''' important question: what to use as root password? We cannot stress this enough: choose a SAFE password! Do NOT go for an easy-to-remember one, go for STRONG and SAFE. There are tools to help you generate strong passwords, like [http://www.pctools.com/guides/password/ this page]: use them! We strongly suggest 10 characters or more, including letters, mixed case, and numbers, so something like ''SuCRe4hecH'' (do NOT use this, generate your own!). Next, give the full name of the principal user of this server (your own, we assume), give the login-name (your given name, we assume), and a corresponding password. Again, use a SAFE password. As long as you don't make your principal user equivalent to root, you might go for a slightly weaker password (8 characters instead of 10), but we rather suggest you make the password just as strong (and different from!) the root password. After entering the details of these two users "root" and "you", the Debian installer will ask you how it can contact the Debian archives, in the dialoge "configure the package manager". For the NetInstall version of Debian, this is as good as mandatory. So here, we say "yes, use a Network Mirror", and in the following list select the country in which we are (in our case: the Netherlands), so the installer can present us with a number of network mirrors "close by". We select ftp.nl.debian.org. Next screen: should you be behind a proxy server, then it's possible to specify that here. And then the test: the system will say "scanning the mirror..." and try to contact the specified mirror. If it does not succeed, then there is either a network problem, a problem with this box's network card, or you've not specified the mirror or proxy correctly - so fix it. You'll know the network mirror has succesfully been contacted when the next dialogue appears - currently "configuring popularity-contest". Answer this question as you please. And then one of the last "big" questions: Software Selection. In this dialogue, you can easily select bundles of software to be installed. The choices are currently: * Desktop environment * Web server * Print server * DNS server * File server * Mail server * SQL database * Laptop * Standard system (selected by default) We have to make a little confession here: we've never before used this option in the installer. In fact, we even deselect the Standard System, so as to minimize the number of software packages that the base installation of our server contains. This makes it more work to manually add packages later, but we feel it gives us more control and understanding of our systems. So if you are like us: deselect the Standard System entry, and select Continue. The next dialogue handles the installation of the [http://www.gnu.org/software/grub/ ''grub'' bootloader]. Unless your disks weren't empty and you're attempting to make this system multiboot, you'll most likely get a question if you'll allow the installer to install ''grub'' into the boot sector of the first hard disk. We'll confirm with "Yes". After the installation of grub is completed, the CD-ROM is ejected, and the system is ready to reboot into Debian Etch. Remove the CD and select "Continue" ==Finishing up the installation== The system should reboot into Debian. This means you should see the following boot sequence: * your machine's standard POST messages * then, a blue grub menu on a black screen, with two entries: ** Debian GNU/Linux, kernel 2.6.&lt;something&gt; ** Debian GNU/Linux, kernel 2.6.&lt;something&gt (single-user mode); * then, after a default time-out, the first grub option will go into effect, and the Linux kernel is started. Lots of cryptic messages in grey-on-black will scroll by, until the last few lines read: "Debian GNU/Linux 4.0 &lt;hostname&gt; tty1" and "&lt;hostname&gt; login:" If your system does not reach this login, and/or some horrible error messages appear anywhere in this boot sequence, then you've got some extra work ahead. For now we'll assume you've reached the login prompt without problem. Log in as the principal user (try to avoid logging in as root! That's BAD practice!). Once logged in, save a copy of the boot messages using ''sudo dmesg > boot.txt'' or whatever you like. Then look through the boot messages, e.g. with ''vi -R boot.txt''. Furthermore, [[APT_and_aptitude | use Aptitude]] to make sure ''all'' your software is updated to the latest version. Done! Your base system is ready. You probably now want to [[essential system software | install essential software]], [[roll your own kernel]] and [[connect your server to the Internet]]. 435149ab067cd3ac532c385d7c2b4dc5fe6517ce 0 1488 2395 2094 2009-04-29T15:17:28Z 217.128.70.172 0 /* CA.sh - certificate creation made easy */ wikitext text/x-wiki ==Preparing for certificate creation== When we're going to create certificates, we're going to use the ''openssl'' command twice: * once to create a "certificate signing request", in which we define all information to be included in the certificate, and actually generate the public and private key parts of the key pair, and * once to instruct the OpenSSL package to sign the certificate with our CA root certificate. The first step thus '''creates''' the actual keypair, and the second step '''signs''' the public key. However, we're going to need to input a lot of parameters on the ''openssl'' command line. We can make things a bit easier for us by specifying these in the ''openssl.cnf'' file, just as we have added some values when creating the CA itself. To be precise, we're going to add '''X.509 V3 extensions''' By default OpenSSL generates V1 certificates, but if we're not extremely worried about offending certain ancient web browsers, we can add V3 extensions, and even make ''openssl'' do that by default. To do this, we find in ''openssl.cnf'' the following line in the section ''[ req ]'', which is likely present but commented out: req_extensions = v3_req # The extensions to add to a certificate request Simply remove the # sign in front of it, so that it appears as given above. This by default enables V3 extensions. Furthermore, check the section ''[ v3_req ]''. It should look like this: [ v3_req ] # Extensions to add to a certificate request basicConstraints = CA:FALSE keyUsage = nonRepudiation, digitalSignature, keyEncipherment subjectKeyIdentifier = hash What is added is the last line, with ''subjectKeyIdentifier''; this line specifies how to identify the public key being certified, so that distinct keys used by the same subject can be differentiated (e.g. as key updating occurs, for example). Four values are possible, but the IETF Public Key Infrastructure (PKIX) working group recommends the setting ''subjectKeyIdentifier=hash'' ==Creating an SSL certificate== Now we can create an SSL certificate for a web server. For the Common Name of the certificate, we need the '''exact''' name of the web server that'll offer the SSL connections. However, some servers run different websites as Virtual Hosts, so they could be running, for example, www.saruman.biz, as well as shop.saruman.biz. That might present a problem, because if the certificate is issued for www.saruman.biz, then each visitor of shop.saruman.biz will get a warning along the lines of "Warning: The website you're trying to visit is shop.saruman.biz, but the certificate offered is for www.saruman.biz". To prevent that, we could use the wildcard character in the name of the certificate, so as to generate a certificate for *.saruman.biz. === CA.sh - certificate creation made easy=== Since we have the ''openssl.cnf'' set up just right, and the ''CA.sh'' script primed, generating an SSL certificate is not very hard. From any old directory, run as root /usr/lib/ssl/misc/CA.sh -newreq This will create the signing request. The questions it'll ask, are * a PEM passphrase, with which to protect the private key of the key pair. Note: you cannot generate a signing request without passphrase, so the private key you'll generate will ''always'' have a passphrase. If this is not what you want, do not despair: you can easily remove the passphrase from the private key after it's been generated (see further down). So just use a passphrase, even if you don't need one. * Country/State/Locality/Organization/Organizational Unit; just as with the CA root certificate creation, these have your preprogrammed defaults that you may or may not change. * Common Name; here we MUST give the DNS name of the host that is going to use the certificate, e.g. ''shop.saruman.biz'', or ''*.saruman.biz''. * Challenge password; leave it blank, it's just to protect your signing request while en-route to the CA - but that's you anyway :-) * Optional company name; leave that blank too, it's also extra information for the CA. Now your private key and your certificate signing request (CSR) are ready; they're called ''newkey.pem'' and ''newreq.pem'' by default, and are located in your working directory. Time to do some signing! From that same working directory, run /usr/lib/ssl/misc/CA.sh -sign The script will show that it's using the config file ''/usr/lib/ssl/openssl.cnf'' (as we indeed wish), and then ask for the super-duper-secret passphrase to the CA private key (provided you've left that in directory ''/etc/ssl/ca/private''). Feed the script the passphrase, and it'll get to work. It'll check the request, then show you the details of the certificate you're about to sign. An example would be Certificate Details: Serial Number: 1 (0x1) Validity Not Before: Oct 27 09:34:00 2008 GMT Not After : Nov 1 09:34:00 2009 GMT Subject: countryName = NL stateOrProvinceName = Utrecht organizationName = Saruman.biz organizationalUnitName = Internet Dept. commonName = shop.saruman.biz emailAddress = webmaster@saruman.biz X509v3 extensions: X509v3 Basic Constraints: CA:FALSE Netscape Comment: OpenSSL Generated Certificate X509v3 Subject Key Identifier: 30:F2:61:80:AA:CF:1B:F0:3E:44:41:D6:38:CC:31:F0:94:28:BD:2B X509v3 Authority Key Identifier: keyid:80:41:F8:A5:1F:C2:27:6E:CF:A9:28:8E:8A:EF:83:E7:FD:8A:D5:26 Certificate is to be certified until Nov 1 09:34:00 2009 GMT (370 days) Sign the certificate? [y/n]: After doing your CA duty and diligently checking all the data, just press ''y''. The script certifies the request, and asks if it is to commit the request. This means it'll update it's own database, by saving a copy of the signed certificate in ''/etc/ssl/ca/newcerts'' named after its serial number (''01.pem'' for this example). Furthermore the script will record the serial and ID's of the generated certificate so that the next certificate will have a new serial number. And now: hey presto! We have a ''newcert.pem'' in our working directory! For good measure: * delete ''newreq.pem'' * rename the generated private key ''newkey.pem'' to ''shop.saruman.biz.seckey.pem'' * rename the generated public certificate ''newcert.pem'' to ''shop.saruman.biz.pem'' To remove the passphrase from the private key, use a command like this: openssl rsa -in shop.saruman.biz.seckey.key -out shop.saruman.biz.key.key This will make ''openssl'' ask for your passphrase, and then create the unsecured ''shop.saruman.biz.key.pem'' key file. Best practice: ALWAYS use a passphrase-protected key, unless the application cannot support it (e.g. Postfix). Save the secure private key and its PEM passphrase in a safe place (e.g. Keepass database). And if you removed the passphrase from the private key, then store it in an even safer place! Now you can deploy your certificate. (more on that in another section). === openssl - the hard way to certificate creation=== We don't actually need to use the ''CA.sh'' script, because we can do manually what the ''CA.sh'' script does. That gives us more control, but also more work. Let's see what we've got to do. We will now perform the first step in our "manual" certificate generation: we create a signing request with all the information that we want in our SSL certificate. We run the magic incantation - note how we already openssl req -new -nodes -keyout webmail.saruman.biz.key.pem -out webmail.saruman.biz.req.pem This generates a new private key (named ''webmail.saruman.biz.key.pem''), and a new, non-encrypted (because of ''-nodes''), key signing request named ''webmail.saruman.biz.req.pem''. We can leave out terms like ''-newkey rsa:2048'' and ''-days 370'' since we've put that in the configuration file. And naturally you're free to choose your own names for the keys. FIXME - need the full process here === Validating the generated certificates=== Again, we can use the ''openssl'' command to validate the keys we've generated. For instance, the ''CA.sh'' generated certificate, after renaming, is verified with openssl x509 -in shop.saruman.biz.pem -noout -purpose Certificate purposes: SSL client : Yes SSL client CA : No SSL server : Yes SSL server CA : No Netscape SSL server : Yes Netscape SSL server CA : No S/MIME signing : Yes S/MIME signing CA : No S/MIME encryption : Yes S/MIME encryption CA : No CRL signing : Yes CRL signing CA : No Any Purpose : Yes Any Purpose CA : Yes OCSP helper : Yes OCSP helper CA : No Notice that the certificate is valid for everything except CA tasks. Likewise, using ''-dates'' instead of ''-purpose'' lets you see the validity time period, and ''-text'' gives the whole text of the certificate. Note the line marked "issuer", and see how your own CA is referenced there. a1a1caf35f66cccec138e937c57d8e3c2961093a 0 1499 2396 2106 2009-05-07T09:29:36Z 149.156.96.14 0 Fixed bug in export $MW_INSTALL_PATH - should be export MW_INSTALL_PATH wikitext text/x-wiki ==Installing Semantic MediaWiki (SMW) under Debian== Installation consists of these simple steps: 1) Use Aptitude to install package ''mediawiki-semediawiki'' (under Lenny that's version 1.2-1) 2) Adjust your namespaces - since we haven't modified the MediaWiki namespaces relative to the original Debian installation, we don't need that. 3) Edit the file ''/etc/mediawiki-extensions/extensions-available/SemanticMediaWiki.php''. All you need to do is change the string for ''enableSemantics'' from ''localhost'' to the hostname of your server: <?php include_once('extensions/SemanticMediaWiki/includes/SMW_Settings.php'); enableSemantics('dworkin.saruman.biz'); ?> Actually, the string for ''enableSemantics'' is an identifier, needed to identify any exported data. The [http://semantic-mediawiki.org/wiki/Help:Installation Semantic MediaWiki website] suggests using the server's host name for this purpose (if you have multiple hostnames, just pick any one of them). 4) Enable the SMW extension, by creating a link to it under ''/etc/mediawiki-extensions/extensions-enabled'': cd /etc/mediawiki-extensions/extensions-enabled/ ln -s ../extensions-available/SemanticMediaWiki.php By the way, this should also work with the MediaWiki extension enabler command: mwenext SemanticMediaWiki.php 5) We now run the maintenance script that creates the necessary tables in your MySQL MediaWiki database. This is a two-step affair:<br> - first set the MW_INSTALL_PATH environment variable to the root of the MediaWiki installation. This path is where ''LocalSettings.php'' and ''index.php'' are located; most likely it's ''/usr/share/mediawiki''.<br> - then go to the directory where the SMW maintenance scripts are located, and execute ''SMW_setup.php''.<br> The sequence will thus look something like this: MW_INSTALL_PATH=/usr/share/mediawiki export MW_INSTALL_PATH cd /usr/share/mediawiki-semediawiki/maintenance php SMW_setup.php The php-script should report setting up some nine tables, named ''smw_ids'', ''smw_redi2'' et cetera. These are the extra MySQL tables that SMW needs. 6) Next, log into your MediaWiki with an account with administrative rights. If you now visit your ''Special pages'', you'll find taht under the section ''Restricted special pages'' there is now an entry titled ''Admin functions for Semantic MediaWiki''. Open it, and find two sections: * '''Preparing database for Semantic MediaWiki'''<br>Here you'll have to press the button labeled ''Initialise or upgrade tables''; this will initialise the newly created tables. A dull page should appear, reporting actions for each of the nine new tables, and ending with the status message ''The storage engine was set up successfully.'' * '''Announce your wiki'''<br>Clicking this button is optional; what it will do is post the URL of your wiki on the [http://semantic-mediawiki.org/wiki/Special:SMWRegistry SMW Registry page] over on the SMW site. <br> <br> That's it! You can now start [http://semantic-mediawiki.org/wiki/Help:User_manual using SMW]. b34100d8bd6b90881324d345945f2ae94babb8cd 0 1431 2398 1634 2009-05-17T10:16:50Z Saruman! 2 added multitail, corrected unzoo wikitext text/x-wiki All utilities listed below are command line utilities; install them using ''apt-get install'' or ''aptitude''. ''apticron'' checks your system daily, and mails you when there are updates for packages<br> ''arj'' is a file compressor/decompressor for the .arj file format<br> ''bzip2'' is a file compressor/decompressor<br> ''ccze'' can "colorize" output, e.g. ''tail -f /var/log/syslog | ccze''<br> ''ipcalc'' is an IP address/mask calculator<br> (''[[IProute | iproute]]'' helps viewing and setting the [http://lartc.org/ IP configuration] - under Lenny it's installed by default, under Etch you'll have to do it yourself)<br> ''iptraf'' is an IP traffic monitor<br> ''less'' is a utility [http://blog.platinumsolutions.com/node/47 to view text files];<br> ''lsof'' can show all open files<br> ''multitail'' can follow multiple (log)files in one terminal<br> ''pwgen'' is a password generator<br> ''[[Sudo | sudo]]'' enables you to execute commands with another user's credentials<br> ''[[TCPdump | tcpdump]] is a network sniffer<br> ''pciutils'' contains the ''lspci'' command, which can be useful to review your hardware<br> ''unzip'' is a file decompressor for the .zip file format<br> ''zoo'' is a file compressor/decompressor for the .zoo file format<br> 588116a132ea67f9be0609a28cfafa1e2257901c 2401 2398 2009-05-25T08:13:16Z Saruman! 2 added ethtool wikitext text/x-wiki All utilities listed below are command line utilities; install them using ''apt-get install'' or ''aptitude''. ''apticron'' checks your system daily, and mails you when there are updates for packages<br> ''arj'' is a file compressor/decompressor for the .arj file format<br> ''bzip2'' is a file compressor/decompressor<br> ''ccze'' can "colorize" output, e.g. ''tail -f /var/log/syslog | ccze''<br> ''[http://packages.debian.org/ethtool ethtool]'' can change settings for ethernet cards, like speed and duplex<br> ''ipcalc'' is an IP address/mask calculator<br> (''[[IProute | iproute]]'' helps viewing and setting the [http://lartc.org/ IP configuration] - under Lenny it's installed by default, under Etch you'll have to do it yourself)<br> ''iptraf'' is an IP traffic monitor<br> ''less'' is a utility [http://blog.platinumsolutions.com/node/47 to view text files];<br> ''lsof'' can show all open files<br> ''multitail'' can follow multiple (log)files in one terminal<br> ''pwgen'' is a password generator<br> ''[[Sudo | sudo]]'' enables you to execute commands with another user's credentials<br> ''[[TCPdump | tcpdump]] is a network sniffer<br> ''pciutils'' contains the ''lspci'' command, which can be useful to review your hardware<br> ''unzip'' is a file decompressor for the .zip file format<br> ''zoo'' is a file compressor/decompressor for the .zoo file format<br> 36e033b61255982cd2739f533c1c55ade17c73e1 0 1422 2402 1672 2009-05-26T18:41:49Z Saruman! 2 small addition wikitext text/x-wiki ==Introduction== The screen-oriented text editor ''vim'' stems from ''vi'', written in '76 for an early BSD Unix release by [http://www.engin.umich.edu/alumni/engineer/04SS/achievements/advances.html#joy Bill Joy]. ''vi'' is old, nonintuitive, and complex. However, it was the successor of the [http://www.wisegeek.com/what-is-a-line-editor.htm line editor] [http://www.apl.jhu.edu/Misc/Unix-info/unixintro/chap9.html ex]; the very name ''vi'' stands for "'''vi'''sual", and in the seventies, going from ''ex'' to ''vi'' was a big improvement indeed.<br> ''[http://en.wikipedia.org/wiki/Vim_%28text_editor%29 vim]'' stems from 1991, and stands for '''''V'''i '''IM'''proved'', but its improvements do not lessen it's nonintuitivity or complexity. So why do we feel that ''vim'' is an essential system tool? Well, it's because * vi can be found on just about any Linux and Unix system * vi is very powerful * with some practice, it's even quite usable but most importantly * if something goes horribly wrong, ''vi'' might just be the only means left to change your configuration files ===About vi as a modal editor=== ''vi'' is a modal editor; this type of editors will operate differently depending on which mode is selected. A ''vi'' session knows two modes: # ''insert mode'', where typed text is added into the document at the place of the prompt, and # ''normal mode'' or command mode, where keystrokes are interpreted as commands that control the session, or act on the document (depending on the command). ''vi'' begins in normal mode, but several commands (notably ''i'' and ''a'') will switch it to insert mode. Once in insert mode, most anything you type becomes part of your document. Only when you press <esc> does your ''vi'' return to normal mode. ==Installation and configuration== To get ''vim'', simply use ''sudo apt-get install vim'' or ''sudo aptitude'', and find ''vim'' in the available packages. Nice to know: when you install ''vim'', you also get ''xxd'', a tool to make a hexdump, or convert a hex dump back to it's original binary form. In Debian Etch, the default editor is nano instead of vim. This can be changed in the following way: which vim.basic sudo update-alternatives --set editor /usr/bin/vim.basic (The first line is to check that you really have vim.basic in place) Now '''all''' commands that invoke an editor will use ''vim'' instead of ''nano''. Is that a good thing? We're not sure, but we do want to keep our ''vi'' skills up to par, so we do this. ==Using vim== Vim operates in two modes: a command mode and an insert mode. You start in command mode, so almost every key is a command. Several commands you can issue will bring you into '''--INSERT--''' moode, e.g. ''i'' or ''a''; to return in command mode press ''&lt;esc&gt;'' or ( ''&lt;ctrl&gt; ['' ). It can be confusing to remember if you're in command mode or insert mode (even though there's a bright marker in the left bottom of the ''vim'' screen :-). So remember: when you're in insert mode, ''&lt;esc&gt;'' will bring you to command mode; when you're already in command mode, ''&lt;esc&gt;'' does nothing (no harm done). So press ''&lt;esc&gt;'' two or three times, and you're sure to be in command mode. Another thing to remember: if you're in command mode and you start entering a number ''before'' a command, the command will get repeated that many times. The most used feature of this is deleting lines. Deleting the current line is done with the command ''dd''; deleting (for example) twelve lines can be accomplished using ''12dd''. Another example is the use of a number in front of G: command ''12G'' (use &lt;shift&gt;-g) will bring you to the beginning of the 12th line. A special number is zero; pressing 0 as the first character in a command means immediately going to the beginning of the line. ===Opening and saving files=== {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Command !style="background:#ffdead;"|Output |- |:o ''filename'' |open file |- |:o ''directory'' |open file within ''directory'' interactively |- |:w |Save |- |:w ''filename'' |Save with this filename |} ===Exiting vim=== {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Command !style="background:#ffdead;"|Output |- |:q |quit vim |- |:q! |quit without save |- |:wq |save and quit |- |ZZ |''also'' save and quit (no colon, just two caps) |} ===Cursor positioning=== {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Key(s) !style="background:#ffdead;"|Movement |- |h |one character back |- |j |down one line, same column |- |k |up one line, same column |- |l,&lt;space&gt; |one character forward |- |b |one word back (to beginning of previous word) |- |e |one word back (to end of previous word) |- |w |one word forward |- |&lt;enter&gt; |beginning of next line |- |^, 0 (zero) |beginning of line |- |$ |end of line |- |G, 0G |to the beginning of the last line of the file |- |''n''G |to the beginning of line ''n'' |- |:''n'' |also to beginning of line ''n'' (but this is visible as command) |- |gg, 0G |to the first line |- |} Note that h,j,k,l is one block on your (US) keyboard ===Searching=== {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Key(s) !style="background:#ffdead;"|Search |- |/''pattern'' |Moves the cursor to the next occurrence of ''pattern''; will wrap around to the beginning of the file from the last occurence |- |?''pattern'' |Moves the cursor backward to the previous occurrence of ''pattern''; will wrap around to the end of the file from the first occurence |- |n |repeats last pattern search (either forward or backward) |- |} <br> ===Search and replace=== If you think searching is fun, then search-and-replace is even more fun! Check out the "substitute" command! :[range]s[ubstitute]/{pattern}/{string}/[&][c][e][g][p][r][i][I] [count] For each line in [range] replace a match of {pattern} with {string}. For the {pattern} see |pattern|. {string} can be a literal string, or something special; see |sub-replace-special|. When [range] and [count] are omitted, replace in the current line only. When [count] is given, replace in [count] lines, starting with the last line in [range]. When [range] is omitted start in the current line. [range] can be something like<br> % = whole file<br> 1,$ = also whole file<br> 3,7 = lines 3 through 7<br> .,+5 = current line (denoted with the period) through the next five lines<br> 'a,'b = between marks ''a'' and ''b''.<br> Well that sounds wonderful, but how do you use this in practice? Usually something like this: :%s/{pattern}/{string}/gic This means: search the whole file for case-insensitive occurrances of {pattern}, and replace each occurrance (even multiple on a single line) with {string} ''after'' confirmation of each replacement. ===Switching to and from insert mode=== {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Key(s) !style="background:#ffdead;"|Effect |- |a |appends text after cursor & switches to Insert mode |- |A |appends text at the '''end''' of the line & switches to Insert mode |- |i |inserts text before cursor & switches to Insert mode |- |I |inserts text at the '''beginning''' of the line & switches to Insert mode |- |o |opens new line below the current line for text insertion & switches to Insert mode |- |O |opens new line '''above''' the current line for text insertion & switches to Insert mode |- |&lt;backspace&gt; |removes last character during text insertion |- |&lt;del&gt; |removes next character during text insertion |- |&lt;esc&gt; |stops text insertion. The escape key on the DECstations is the &lt;F11&gt; key |- |} ===Text cutting (deletion)=== {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Key(s) !style="background:#ffdead;"|Effect |- |x |cut character under the cursor |- |dw |cut word under the cursor |- |dd |cut current line |- |''n''dd |cut ''n'' lines starting with the current one |- |d), d$ |cut to the end of the current sentence (up to and including the dot) |- |D |deletes to the end of the current line |- |d$ |same (deletes to the end of the current line) |- |} ===Text pasting (insertion)=== {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Key(s) !style="background:#ffdead;"|Effect |- |p |"paste", puts the buffer (e.g. text from the previous deletion) after the position of the cursor |- |P |"Paste", puts the buffer (e.g. text from the previous deletion) '''before''' the position of the cursor |- |} 9d416a90ae44e7b2ce61f2ecfad97b734296cad3 0 1416 2404 1456 2009-06-14T14:17:09Z Saruman! 2 added run-parts name restriction wikitext text/x-wiki Linux has it's own scheduler, named cron (derived from Greek chronos (χρόνος), meaning time). The Debian package contains the version written by Paul Vixie. Cron operates by having a daemon ''crond'' running in the background, that checks once every minute to see if there are scheduled tasks to run. Tasks can be scheduled by each user by making entries in a file named a ''crontab''. Each user has his own crontab, that cron saves in ''/var/spool/cron/crontabs/&lt;username&gt;''. Furthermore, there's a general crontab in ''/etc'', aptly named ''crontab''. This crontab under Debian has 3 default entries: # /etc/crontab: system-wide crontab # Unlike any other crontab you don't have to run the `crontab' # command to install the new version when you edit this file # and files in /etc/cron.d. These files also have username fields, # that none of the other crontabs do. SHELL=/bin/sh PATH=/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin # m h dom mon dow user command 17 * * * * root cd / && run-parts --report /etc/cron.hourly 25 6 * * * root test -x /usr/sbin/anacron || ( cd / && run-parts --report /etc/cron.daily ) 47 6 * * 7 root test -x /usr/sbin/anacron || ( cd / && run-parts --report /etc/cron.weekly ) 52 6 1 * * root test -x /usr/sbin/anacron || ( cd / && run-parts --report /etc/cron.monthly ) # You can schedule a repetitive task directly in the three ''cron.*'' folders; it will get run as user ''root''. To this end, place a suitable script in the folder that matches your need (daily, weekly or monthly). Note, that the script must be named according to the strict rules that ''run-parts'' uses: according to the man page, ''"the names must consist entirely of upper and lower case letters, digits, underscores, and hyphens"'. This means no dot, so do not create a script ''backup.sh'', because it will not get executed. You can also schedule a task to run as a particular user by adding a line to the ''/etc/crontab'' file, specifying the date-and-time pattern, as well as the user under which the script must run. To see the current user's crontab >crontab -l To see a different user's crontab (works only when you're root) >crontab -u 'username' -l To edit the current users crontab >crontab -e Now you can schedule your task # +---------------- minute (0 - 59) # | +------------- hour (0 - 23) # | | +---------- day of month (1 - 31) # | | | +------- month (1 - 12) # | | | | +---- day of week (0 - 6) (Sunday=0 or 7) # | | | | | * * * * * command to be executed (full path to command/script) bec1065284cdc2bcddab579acf783ed3f9f719b1 0 1483 2405 1978 2009-06-14T21:04:09Z Insomnia 3 /* Hardware */ wikitext text/x-wiki We want to build a wireless access point (AP) on a debian based server. You can use any wireless pci adapter as long as it supports ''iwconfig ath0 mode master'' If you get a error try another driver. I use the madwifi driver for my atheros based card. == Hardware == Requirements wireless-tools (for iwconfig) Bridge-utils Hostapd Hostap-utils ?? I used an old netgear wireless pci card. To see wich chipset it has type lspci 00:0e.0 Ethernet controller: Atheros Communications Inc. AR5212/AR5213 Multiprotocol MAC/baseband processor (rev 01) The atheros chip uses the madwifi driver http://sourceforge.net Download the driver and compile the module. Or use the 2.6.27.2 kernel where the atheros chip is supported as a module. Use modprobe ath9k make install modprobe ath_pci To enable ath9k, you must first enable mac80211: Networking ---> Wireless ---> <M> Improved wireless configuration API <M> Generic IEEE 802.11 Networking Stack (mac80211) You can then enable ath9k in the kernel configuration under Device Drivers ---> [*] Network device support ---> Wireless LAN ---> <M> Atheros 802.11n wireless cards support Now you should see the card thinner:/# iwconfig lo no wireless extensions. eth0 no wireless extensions. eth1 no wireless extensions. wifi0 no wireless extensions. ath0 IEEE 802.11g ESSID:"" Nickname:"" Mode:Managed Frequency:2.437 GHz Access Point: Not-Associated Bit Rate:0 kb/s Tx-Power:14 dBm Sensitivity=1/1 Retry:off RTS thr:off Fragment thr:off Encryption key:off Power Management:off Link Quality=0/70 Signal level=-96 dBm Noise level=-96 dBm Rx invalid nwid:4378 Rx invalid crypt:0 Rx invalid frag:0 Tx excessive retries:0 Invalid misc:0 Missed beacon:0 To bring the card up #ifconfig ath0 up And to scan for networks #wlanconfig ath0 list scan And for more info #iwlist ath0 scan #wlanconfig ath0 destroy #wlanconfig ath0 create wlandev wifi0 wlanmode ap ath0 IEEE 802.11g ESSID:"" Nickname:"" Mode:Master Frequency:2.412 GHz Access Point: 00:09:5B:C3:97:3E Now create a new text file named /etc/hostapd/wpa_psk and paste your pass phrase as: 00:00:00:00:00:00 PASSPHRASE Turn on the routing engine echo 1 > /proc/sys/net/ipv4/ip_forward Create the routing rule route add -net 192.168.70.0 netmask 255.255.255.0 gateway 192.168.70.7 dev eth0 == Firmware update == Prism2/2.5/3 cards and Host AP driver support two different mechanism of upgrading the card firmware. Firmware images (primary and station) can be downloaded either into volatile memory (RAM download) or non-volatile memory (flash upgrade). Firmware images downloaded into volatile memory are lost when the card is resetted, so they are quite safe. Flash upgrade with incorrect images may cause permanent problems (i.e., render the card useless), so certain amount of caution is always recommended for this. Check your existing firmware hostap_diag wlan0 53e79b9ccc192fdb4a7834cee261fff53c96c6eb 0 1482 2408 2009 2009-06-25T07:09:14Z Insomnia 3 /* Make DVD */ wikitext text/x-wiki == NDISwrapper == NDISwrapper is a free software driver wrapper that enables the use of Microsoft Windows drivers for wireless network devices. Download the windows driver wich contains the .inf file<br> Install with ndiswrapper -i drivername.inf<br> check the device id with lsusb or lspci -n<br> Now execute with ndiswrapper -a deviceid driver ndiswrapper -a 0bda:8197 net8187b check the installed drivers ndiswrapper -l Write the configuration for modprobe ndiswrapper -m And use the module modprobe ndiswrapper == Compiz == To enable compiz install the Nvidia drivers and install CompizConfig Settings Manager sudo apt-get install simple-ccsm Now navigate to system > preferences > Appereance And go to the Visual effects tab. Choose custum there {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Desktop Effects !style="background:#ffdead;"|Keyboard Shortcuts |- |Rotate Cube Manually |Ctrl + Alt + Left Mouse Button |- |Expo |Super + E (toggle) |- |Rotate Cube |Mousewheel on Desktop |- |Film Effect |Ctrl + Alt + Down Arrow |- |Scale Windows |Alt + Shift + Up Arrow |- |Ring Switcher |Super + Tab - overrides Shift Switcher |} Super key is the windows key :-) == Mount Network Share == First install smbfs apt-get install smbfs Then create a folder inside of the /media directory to mount the share on or choose you're own directory sudo mkdir /media/Storage Create a credentials file in /root so that you can save your password and have it protected by the root account: sudo gedit /root/.cifscredentials Add this to the file username=Guest password= sudo vi /etc/fstab Add the following line //192.168.0.10/SHARENAME /media/Storage cifs auto,iocharset=utf8,uid=USER,gid=users,credentials=/root/.cifscredentials,file_mode=0775,dir_mode=0775 0 0 To check if the file works sudo mount -a And you should see you're drives on the desktop Ik you get error when you shut down the pc ''CIFS VFS: server not responding'' then you have to unmount first. Do this with the following ln -s /etc/init.d/umountnfs.sh /etc/rc0.d/K15umountnfs.sh ln -s /etc/init.d/umountnfs.sh /etc/rc6.d/K15umountnfs.sh == Citrix Ica client == Download the Linux citrix ica client from Citrix http://citrix.com/English/SS/downloads/details.asp?downloadID=3323&productID=-1 Unpack the package and execute the installation script ./setupwfc Find the plugin directory of firefox. Probably is /usr/lib/firefox/plugins/ otherwise use find / -name plugins | grep -i "netscape\|firefox\|mozilla" Create a symlink to the citrix ica library ln –s /usr/lib/ICAClient/npica.so npica.so If you open a connection to your citrix server. The browser will ask you if you want to open or save the session. Browse to the ica client /usr/lib/ICAClient/wfica and tell it to use it for all applications. When you get a ssl error "you have not chosen to thrust....." Then copy the certificate in this location. /usr/lib/ICAClient/keystore/cacerts/ == Make DVD == To make a video DVD you can burn you're image on the dvd. If you just have the VIDEO_TS files then the easiest way is to convert these into a iso. mkisofs -dvd-video -o ~/moviename.iso /path/to/the/VIDEO_TS /path/to/the/VIDEO_TS path is for example /moviename not /moviename/VIDEO_TS b485c650bc5c3bdc73c2e0cbd5edfd70c638ff61 0 1483 2409 2405 2009-06-27T19:17:05Z Insomnia 3 /* Firmware update */ wikitext text/x-wiki We want to build a wireless access point (AP) on a debian based server. You can use any wireless pci adapter as long as it supports ''iwconfig ath0 mode master'' If you get a error try another driver. I use the madwifi driver for my atheros based card. == Hardware == Requirements wireless-tools (for iwconfig) Bridge-utils Hostapd Hostap-utils ?? I used an old netgear wireless pci card. To see wich chipset it has type lspci 00:0e.0 Ethernet controller: Atheros Communications Inc. AR5212/AR5213 Multiprotocol MAC/baseband processor (rev 01) The atheros chip uses the madwifi driver http://sourceforge.net Download the driver and compile the module. Or use the 2.6.27.2 kernel where the atheros chip is supported as a module. Use modprobe ath9k make install modprobe ath_pci To enable ath9k, you must first enable mac80211: Networking ---> Wireless ---> <M> Improved wireless configuration API <M> Generic IEEE 802.11 Networking Stack (mac80211) You can then enable ath9k in the kernel configuration under Device Drivers ---> [*] Network device support ---> Wireless LAN ---> <M> Atheros 802.11n wireless cards support Now you should see the card thinner:/# iwconfig lo no wireless extensions. eth0 no wireless extensions. eth1 no wireless extensions. wifi0 no wireless extensions. ath0 IEEE 802.11g ESSID:"" Nickname:"" Mode:Managed Frequency:2.437 GHz Access Point: Not-Associated Bit Rate:0 kb/s Tx-Power:14 dBm Sensitivity=1/1 Retry:off RTS thr:off Fragment thr:off Encryption key:off Power Management:off Link Quality=0/70 Signal level=-96 dBm Noise level=-96 dBm Rx invalid nwid:4378 Rx invalid crypt:0 Rx invalid frag:0 Tx excessive retries:0 Invalid misc:0 Missed beacon:0 To bring the card up #ifconfig ath0 up And to scan for networks #wlanconfig ath0 list scan And for more info #iwlist ath0 scan #wlanconfig ath0 destroy #wlanconfig ath0 create wlandev wifi0 wlanmode ap ath0 IEEE 802.11g ESSID:"" Nickname:"" Mode:Master Frequency:2.412 GHz Access Point: 00:09:5B:C3:97:3E Now create a new text file named /etc/hostapd/wpa_psk and paste your pass phrase as: 00:00:00:00:00:00 PASSPHRASE Turn on the routing engine echo 1 > /proc/sys/net/ipv4/ip_forward Create the routing rule route add -net 192.168.70.0 netmask 255.255.255.0 gateway 192.168.70.7 dev eth0 == Firmware update == Prism2/2.5/3 cards and Host AP driver support two different mechanism of upgrading the card firmware. Firmware images (primary and station) can be downloaded either into volatile memory (RAM download) or non-volatile memory (flash upgrade). Firmware images downloaded into volatile memory are lost when the card is resetted, so they are quite safe. Flash upgrade with incorrect images may cause permanent problems (i.e., render the card useless), so certain amount of caution is always recommended for this. Check your existing firmware hostap_diag wlan0 I downloaded the softmac firmware and placed it in mv 2.13.12.0.arm /usr/lib/hotplug/firmware/isl3890 def110b98aa90a76e99d27208164a82a6b92a13f 0 1482 2410 2408 2009-06-29T10:21:01Z Insomnia 3 /* Citrix Ica client */ wikitext text/x-wiki == NDISwrapper == NDISwrapper is a free software driver wrapper that enables the use of Microsoft Windows drivers for wireless network devices. Download the windows driver wich contains the .inf file<br> Install with ndiswrapper -i drivername.inf<br> check the device id with lsusb or lspci -n<br> Now execute with ndiswrapper -a deviceid driver ndiswrapper -a 0bda:8197 net8187b check the installed drivers ndiswrapper -l Write the configuration for modprobe ndiswrapper -m And use the module modprobe ndiswrapper == Compiz == To enable compiz install the Nvidia drivers and install CompizConfig Settings Manager sudo apt-get install simple-ccsm Now navigate to system > preferences > Appereance And go to the Visual effects tab. Choose custum there {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Desktop Effects !style="background:#ffdead;"|Keyboard Shortcuts |- |Rotate Cube Manually |Ctrl + Alt + Left Mouse Button |- |Expo |Super + E (toggle) |- |Rotate Cube |Mousewheel on Desktop |- |Film Effect |Ctrl + Alt + Down Arrow |- |Scale Windows |Alt + Shift + Up Arrow |- |Ring Switcher |Super + Tab - overrides Shift Switcher |} Super key is the windows key :-) == Mount Network Share == First install smbfs apt-get install smbfs Then create a folder inside of the /media directory to mount the share on or choose you're own directory sudo mkdir /media/Storage Create a credentials file in /root so that you can save your password and have it protected by the root account: sudo gedit /root/.cifscredentials Add this to the file username=Guest password= sudo vi /etc/fstab Add the following line //192.168.0.10/SHARENAME /media/Storage cifs auto,iocharset=utf8,uid=USER,gid=users,credentials=/root/.cifscredentials,file_mode=0775,dir_mode=0775 0 0 To check if the file works sudo mount -a And you should see you're drives on the desktop Ik you get error when you shut down the pc ''CIFS VFS: server not responding'' then you have to unmount first. Do this with the following ln -s /etc/init.d/umountnfs.sh /etc/rc0.d/K15umountnfs.sh ln -s /etc/init.d/umountnfs.sh /etc/rc6.d/K15umountnfs.sh == Citrix Ica client == Download the Linux citrix ica client from Citrix http://citrix.com/English/SS/downloads/details.asp?downloadID=3323&productID=-1 Install the 32bits libraries if youŕe working on a 64bits platform apt-get install ia32-libs Install the Open-motif libraries apt-get install libmotif3 Unpack the package and execute the installation script ./setupwfc Find the plugin directory of firefox. Probably is /usr/lib/firefox/plugins/ otherwise use find / -name plugins | grep -i "netscape\|firefox\|mozilla" Create a symlink to the citrix ica library ln –s /usr/lib/ICAClient/npica.so npica.so If you open a connection to your citrix server. The browser will ask you if you want to open or save the session. Browse to the ica client /usr/lib/ICAClient/wfica and tell it to use it for all applications. When you get a ssl error "you have not chosen to thrust....." Then copy the certificate in this location. /usr/lib/ICAClient/keystore/cacerts/ == Make DVD == To make a video DVD you can burn you're image on the dvd. If you just have the VIDEO_TS files then the easiest way is to convert these into a iso. mkisofs -dvd-video -o ~/moviename.iso /path/to/the/VIDEO_TS /path/to/the/VIDEO_TS path is for example /moviename not /moviename/VIDEO_TS 86e3faaef657d23e1e6832849c48316fff5d6dd0 2411 2410 2009-06-29T13:04:25Z 193.67.158.162 0 /* Citrix Ica client */ wikitext text/x-wiki == NDISwrapper == NDISwrapper is a free software driver wrapper that enables the use of Microsoft Windows drivers for wireless network devices. Download the windows driver wich contains the .inf file<br> Install with ndiswrapper -i drivername.inf<br> check the device id with lsusb or lspci -n<br> Now execute with ndiswrapper -a deviceid driver ndiswrapper -a 0bda:8197 net8187b check the installed drivers ndiswrapper -l Write the configuration for modprobe ndiswrapper -m And use the module modprobe ndiswrapper == Compiz == To enable compiz install the Nvidia drivers and install CompizConfig Settings Manager sudo apt-get install simple-ccsm Now navigate to system > preferences > Appereance And go to the Visual effects tab. Choose custum there {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Desktop Effects !style="background:#ffdead;"|Keyboard Shortcuts |- |Rotate Cube Manually |Ctrl + Alt + Left Mouse Button |- |Expo |Super + E (toggle) |- |Rotate Cube |Mousewheel on Desktop |- |Film Effect |Ctrl + Alt + Down Arrow |- |Scale Windows |Alt + Shift + Up Arrow |- |Ring Switcher |Super + Tab - overrides Shift Switcher |} Super key is the windows key :-) == Mount Network Share == First install smbfs apt-get install smbfs Then create a folder inside of the /media directory to mount the share on or choose you're own directory sudo mkdir /media/Storage Create a credentials file in /root so that you can save your password and have it protected by the root account: sudo gedit /root/.cifscredentials Add this to the file username=Guest password= sudo vi /etc/fstab Add the following line //192.168.0.10/SHARENAME /media/Storage cifs auto,iocharset=utf8,uid=USER,gid=users,credentials=/root/.cifscredentials,file_mode=0775,dir_mode=0775 0 0 To check if the file works sudo mount -a And you should see you're drives on the desktop Ik you get error when you shut down the pc ''CIFS VFS: server not responding'' then you have to unmount first. Do this with the following ln -s /etc/init.d/umountnfs.sh /etc/rc0.d/K15umountnfs.sh ln -s /etc/init.d/umountnfs.sh /etc/rc6.d/K15umountnfs.sh == Citrix Ica client == Download the Linux citrix ica client from Citrix http://citrix.com/English/SS/downloads/details.asp?downloadID=3323&productID=-1 Install the 32bits libraries if youŕe working on a 64bits platform apt-get install ia32-libs Install the Open-motif libraries apt-get install libmotif3 Unpack the package and execute the installation script ./setupwfc Find the plugin directory of firefox. Probably is /usr/lib/firefox/plugins/ otherwise use find / -name plugins | grep -i "netscape\|firefox\|mozilla" Create a symlink to the citrix ica library ln –s /usr/lib/ICAClient/npica.so npica.so If you open a connection to your citrix server. The browser will ask you if you want to open or save the session. Browse to the ica client /usr/lib/ICAClient/wfica and tell it to use it for all applications. When you get a ssl error "you have not chosen to thrust....." Then copy the certificate in this location. /usr/lib/ICAClient/keystore/cacerts/ For 64Bits OS Install Needed 32-bit Open Motif libraries to /usr/lib32 Setup a temporary environment mkdir -p ~/tmp/Citrix cd ~/tmp/Citrix Download a recent i386 libmotif3 .deb package to the above folder wget http://mirrors.kernel.org/ubuntu/pool/multiverse/o/openmotif/libmotif3_2.2.3-1.4_i386.deb Use dpkg to extract the package dpkg -x libmotif3*i386.deb libmotif Copy the libraries to /usr/lib32 sudo cp libmotif/usr/lib/*.so.* /usr/lib32/ sudo cp -r libmotif/usr/lib/X11/bindings /usr/lib32/X11/ == Make DVD == To make a video DVD you can burn you're image on the dvd. If you just have the VIDEO_TS files then the easiest way is to convert these into a iso. mkisofs -dvd-video -o ~/moviename.iso /path/to/the/VIDEO_TS /path/to/the/VIDEO_TS path is for example /moviename not /moviename/VIDEO_TS 7abaab0ea067bba2695e43039e8888f2814e0227 2412 2411 2009-07-01T06:29:08Z Insomnia 3 /* Compiz */ wikitext text/x-wiki == NDISwrapper == NDISwrapper is a free software driver wrapper that enables the use of Microsoft Windows drivers for wireless network devices. Download the windows driver wich contains the .inf file<br> Install with ndiswrapper -i drivername.inf<br> check the device id with lsusb or lspci -n<br> Now execute with ndiswrapper -a deviceid driver ndiswrapper -a 0bda:8197 net8187b check the installed drivers ndiswrapper -l Write the configuration for modprobe ndiswrapper -m And use the module modprobe ndiswrapper == Compiz == To enable compiz install the Nvidia drivers and install CompizConfig Settings Manager sudo apt-get install simple-ccsm Now navigate to system > preferences > Appereance And go to the Visual effects tab. Choose custum there On Kubuntu change the default windows manager System Settings -> Default Applications -> Windows manager {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Desktop Effects !style="background:#ffdead;"|Keyboard Shortcuts |- |Rotate Cube Manually |Ctrl + Alt + Left Mouse Button |- |Expo |Super + E (toggle) |- |Rotate Cube |Mousewheel on Desktop |- |Film Effect |Ctrl + Alt + Down Arrow |- |Scale Windows |Alt + Shift + Up Arrow |- |Ring Switcher |Super + Tab - overrides Shift Switcher |} Super key is the windows key :-) == Mount Network Share == First install smbfs apt-get install smbfs Then create a folder inside of the /media directory to mount the share on or choose you're own directory sudo mkdir /media/Storage Create a credentials file in /root so that you can save your password and have it protected by the root account: sudo gedit /root/.cifscredentials Add this to the file username=Guest password= sudo vi /etc/fstab Add the following line //192.168.0.10/SHARENAME /media/Storage cifs auto,iocharset=utf8,uid=USER,gid=users,credentials=/root/.cifscredentials,file_mode=0775,dir_mode=0775 0 0 To check if the file works sudo mount -a And you should see you're drives on the desktop Ik you get error when you shut down the pc ''CIFS VFS: server not responding'' then you have to unmount first. Do this with the following ln -s /etc/init.d/umountnfs.sh /etc/rc0.d/K15umountnfs.sh ln -s /etc/init.d/umountnfs.sh /etc/rc6.d/K15umountnfs.sh == Citrix Ica client == Download the Linux citrix ica client from Citrix http://citrix.com/English/SS/downloads/details.asp?downloadID=3323&productID=-1 Install the 32bits libraries if youŕe working on a 64bits platform apt-get install ia32-libs Install the Open-motif libraries apt-get install libmotif3 Unpack the package and execute the installation script ./setupwfc Find the plugin directory of firefox. Probably is /usr/lib/firefox/plugins/ otherwise use find / -name plugins | grep -i "netscape\|firefox\|mozilla" Create a symlink to the citrix ica library ln –s /usr/lib/ICAClient/npica.so npica.so If you open a connection to your citrix server. The browser will ask you if you want to open or save the session. Browse to the ica client /usr/lib/ICAClient/wfica and tell it to use it for all applications. When you get a ssl error "you have not chosen to thrust....." Then copy the certificate in this location. /usr/lib/ICAClient/keystore/cacerts/ For 64Bits OS Install Needed 32-bit Open Motif libraries to /usr/lib32 Setup a temporary environment mkdir -p ~/tmp/Citrix cd ~/tmp/Citrix Download a recent i386 libmotif3 .deb package to the above folder wget http://mirrors.kernel.org/ubuntu/pool/multiverse/o/openmotif/libmotif3_2.2.3-1.4_i386.deb Use dpkg to extract the package dpkg -x libmotif3*i386.deb libmotif Copy the libraries to /usr/lib32 sudo cp libmotif/usr/lib/*.so.* /usr/lib32/ sudo cp -r libmotif/usr/lib/X11/bindings /usr/lib32/X11/ == Make DVD == To make a video DVD you can burn you're image on the dvd. If you just have the VIDEO_TS files then the easiest way is to convert these into a iso. mkisofs -dvd-video -o ~/moviename.iso /path/to/the/VIDEO_TS /path/to/the/VIDEO_TS path is for example /moviename not /moviename/VIDEO_TS 8330bf531eafe82fbafcbe53ca6b23c6ab3106e2 2463 2412 2009-10-05T11:17:37Z Insomnia 3 /* Citrix Ica client */ wikitext text/x-wiki == NDISwrapper == NDISwrapper is a free software driver wrapper that enables the use of Microsoft Windows drivers for wireless network devices. Download the windows driver wich contains the .inf file<br> Install with ndiswrapper -i drivername.inf<br> check the device id with lsusb or lspci -n<br> Now execute with ndiswrapper -a deviceid driver ndiswrapper -a 0bda:8197 net8187b check the installed drivers ndiswrapper -l Write the configuration for modprobe ndiswrapper -m And use the module modprobe ndiswrapper == Compiz == To enable compiz install the Nvidia drivers and install CompizConfig Settings Manager sudo apt-get install simple-ccsm Now navigate to system > preferences > Appereance And go to the Visual effects tab. Choose custum there On Kubuntu change the default windows manager System Settings -> Default Applications -> Windows manager {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Desktop Effects !style="background:#ffdead;"|Keyboard Shortcuts |- |Rotate Cube Manually |Ctrl + Alt + Left Mouse Button |- |Expo |Super + E (toggle) |- |Rotate Cube |Mousewheel on Desktop |- |Film Effect |Ctrl + Alt + Down Arrow |- |Scale Windows |Alt + Shift + Up Arrow |- |Ring Switcher |Super + Tab - overrides Shift Switcher |} Super key is the windows key :-) == Mount Network Share == First install smbfs apt-get install smbfs Then create a folder inside of the /media directory to mount the share on or choose you're own directory sudo mkdir /media/Storage Create a credentials file in /root so that you can save your password and have it protected by the root account: sudo gedit /root/.cifscredentials Add this to the file username=Guest password= sudo vi /etc/fstab Add the following line //192.168.0.10/SHARENAME /media/Storage cifs auto,iocharset=utf8,uid=USER,gid=users,credentials=/root/.cifscredentials,file_mode=0775,dir_mode=0775 0 0 To check if the file works sudo mount -a And you should see you're drives on the desktop Ik you get error when you shut down the pc ''CIFS VFS: server not responding'' then you have to unmount first. Do this with the following ln -s /etc/init.d/umountnfs.sh /etc/rc0.d/K15umountnfs.sh ln -s /etc/init.d/umountnfs.sh /etc/rc6.d/K15umountnfs.sh == Citrix Ica client == Download the Linux citrix ica client from Citrix http://citrix.com/English/SS/downloads/details.asp?downloadID=3323&productID=-1 Install the 32bits libraries if youŕe working on a 64bits platform apt-get install ia32-libs Install the Open-motif libraries apt-get install libmotif3 citrix 11 requires openmotif 2.3.1 Download the rpm package for openmotif 2.3.1, I used: ftp://ftp.ics.com/openmotif/2.3/2.3.1/openmotif-2.3.1-1.RHEL3.0.i386.rpm To convert a rpm package to a debian package. Use alien to convert the rpm to a deb package alien -d openmotif-2.3.1-1.RHEL3.0.i386.rpm Then install the package in the usual way. Note, before installing the alien'ed package it is best to uninstall the previous version of motif, as this will not update the existing motif package. dpkg -i openmotif_2.3.1-2_i386.deb Unpack the package and execute the installation script ./setupwfc Find the plugin directory of firefox. Probably is /usr/lib/firefox/plugins/ otherwise use find / -name plugins | grep -i "netscape\|firefox\|mozilla" Create a symlink to the citrix ica library ln –s /usr/lib/ICAClient/npica.so npica.so If you open a connection to your citrix server. The browser will ask you if you want to open or save the session. Browse to the ica client /usr/lib/ICAClient/wfica and tell it to use it for all applications. When you get a ssl error "you have not chosen to thrust....." Then copy the certificate in this location. /usr/lib/ICAClient/keystore/cacerts/ For 64Bits OS Install Needed 32-bit Open Motif libraries to /usr/lib32 Setup a temporary environment mkdir -p ~/tmp/Citrix cd ~/tmp/Citrix Download a recent i386 libmotif3 .deb package to the above folder wget http://mirrors.kernel.org/ubuntu/pool/multiverse/o/openmotif/libmotif3_2.2.3-1.4_i386.deb Use dpkg to extract the package dpkg -x libmotif3*i386.deb libmotif Copy the libraries to /usr/lib32 sudo cp libmotif/usr/lib/*.so.* /usr/lib32/ sudo cp -r libmotif/usr/lib/X11/bindings /usr/lib32/X11/ == Make DVD == To make a video DVD you can burn you're image on the dvd. If you just have the VIDEO_TS files then the easiest way is to convert these into a iso. mkisofs -dvd-video -o ~/moviename.iso /path/to/the/VIDEO_TS /path/to/the/VIDEO_TS path is for example /moviename not /moviename/VIDEO_TS ad46ce37eae7245702afef00514096b51221ede6 0 1480 2413 1829 2009-07-13T08:09:54Z Insomnia 3 /* sip.conf */ xs4all sip.conf wikitext text/x-wiki = Asterisk basic configuration principles = In this section we'll have a look at the basic configuration of an Asterisk PBX. Contrary to the TFOT-book, we'll be looking at it from the theory side, and from there go to an example configuration. For this example configuration, we'll start from a server with on the "outside" a POTS line and a SIP account with an Internet provider, and on the "inside" two analogue telephones and a SIP softphone. Our goal is to let the PBX behave as if we don't even have a PBX, but a standard home situation: for an incoming call, all phones ring; and every internal phone can make calls to the outside. = Asterisk channel configuration basics = The first thing to realise is that Asterisk sees each connected telephony device as a "channel". But what is a Channel? To Asterisk, a channel is a connection which brings in a call to the Asterisk PBX. A channel could be a connection to an ordinary telephone handset or an ordinary telephone line, or to a logical call (like an Internet phone call). Asterisk makes no distinction between "FXO" and "FXS" style channels (that is, it doesn't distinguish between telephone lines and telephones). Every call is placed or received on a distinct channel. The second thing to realise, is that every type of device attached to the Asterisk PBX have their own specific configuration files. Correctly setting up each (set of) telephony devices makes them available in our Asterisk PBX as channels. Thus, the device configuration files serve as a kind of abstraction layer, and simplify our final Asterisk configuration by putting "channel-specific" information in separate files. If you've followed the previous Asterisk sections in this Wiki, or followed the first four chapters of the TFOT-book, then you've encountered the following configuration files: * ''zaptel.conf'' - in this file, you can set up the most basic parameters for your Zap-type hardware channels, most notably Digium telephony cards. You're configuring the hardware itself, via its driver. You could think of this file as belonging to the hardware, not Asterisk. If you'd have other software on your machine besides Asterisk that could make use of your telephony hardware, then that'd be influenced as well when you change ''zaptel.conf''. * ''zapata.conf'' (and possibly ''zapata-channels.conf'' if you're on Debian) - this file handles the Asterisk-specific configuration of the hardware telephony channels. It thus "sets up the Zap channels" that Asterisk sees - for incoming and outgoing calls. All parameters that set up the channel are specified here. * ''vpb.conf'' - this file is used to configure [http://www.voicetronix.com/ Voicetronix] cards with Asterisk. If you've a Voicetronix card in use, then you've also installed the Voicetronix drivers. This makes the card(s) useable under Linux. But to have Asterisk use the card(s), you need this ''vpb.conf'' file. It thus serves the same purpose as ''zapata.conf''. * ''sip.conf'' - this file contains all information on all SIP devices that we want to connect to our Asterisk server; be it one or more SIP accounts with Internet providers, or SIP capable telephones (hardware or software). When ''sip.conf'' has been set up correctly, we can refer to a SIP device by a friendly name like [1000] or [Jane]. * ''iax.conf'' - this file is just the same as the ''sip.conf'' file, only it handles devices that talk IAX2 protocol instead of the SIP protocol. These five files define all channels that our basic Asterisk PBX might handle (well, it won't even handle the last one, since we're not connecting any other Asterisk boxes or IAX-(soft)phones to our PBX, and it won't handle the third one if you don't have a Voicetronix card). As a reference, we're going to list the contents of four example files, and explain what they do in the way of preparing channels for our simple Asterisk server.: ==zaptel.conf== # Autogenerated by ./genzaptelconf -- do not hand edit # Zaptel Configuration File # # This file is parsed by the Zaptel Configurator, ztcfg # # It must be in the module loading order # Span 1: WCTDM/0 "Wildcard TDM410P Board 1" (MASTER) fxoks=1 fxoks=2 fxsks=3 # channel 4, WCTDM, no module. # Global data loadzone = nl defaultzone = nl This is a relatively simple file, configuring three Digium modules. As you can see, the ''genzaptelconf'' command has generated it for us. It belongs with a Digium TDM410P card, which has two FXS modules in positions 1 and 2, and one FXO module in position 3. The first two non-commented lines define the protocol that the FXS modules must "talk" with the attached devices, which "naturally" is the FXO protocol (yes, FXS talks FXO, and FXO talks FXS... a bit like electric current flowing from negative to positive. It's just a matter of definitions).<br> The third line defines that the FXO module talks FXS protocol.<br> The fourth line configures a set of indications to use for the defined channels. Since we're loading "nl", we're configuring Dutch dialtones etcetera for the channels.<br> Finally, the last line tell the server that any channel that does not have a zone assigned to it, should have the specified default zone configured - Dutch as well in this example.<br> With this simple file, the driver for our example card (''wctdm24xxp'', by the way) can set up the hardware just as we want it. Now to tell Asterisk how to use it... ==zapata-channels.conf== ; Autogenerated by ./genzaptelconf -- do not hand edit ; Zaptel Channels Configurations (zapata.conf) ; ; This is not intended to be a complete zapata.conf. Rather, it is intended ; to be #include-d by /etc/zapata.conf that will include the global settings ; ; Span 1: WCTDM/0 "Wildcard TDM410P Board 1" (MASTER) ;;; line="1 WCTDM/0/0" signalling=fxo_ks callerid="Channel 1" <6001> mailbox=6001 group=5 context=from-internal channel => 1 callerid= mailbox= group= context=default ;;; line="2 WCTDM/0/1" signalling=fxo_ks callerid="Channel 2" <6002> mailbox=6002 group=5 context=from-internal channel => 2 callerid= mailbox= group= context=default ;;; line="3 WCTDM/0/2" signalling=fxs_ks callerid=asreceived group=0 context=from-pstn channel => 3 context=default This second file is also auto-generated. It sets up three channels, associated with the three Digium hardware modules that we've configured with ''zaptel.conf''. Here, we also see how the channel numbers get assigned to the physical ports. The first module gets to be Zap channel 1 ('''Zap/1'''), the second '''Zap/2''' and so on. So if we would like our FXO module to be channel 1, and our FXS modules 2 and three, we could rotate the three channel numbers in this file. Probably we'd then also want to rotate the ''callerid''`s though... Furthermore, we don't think it's a good idea to assign channels to Zap devices in a different order than the devices are found in the system - meaning "stick with the default numbering as much as possible". Note that the way ''zapata-channels.conf'' is interpreted, means that any statement like ''signalling=fxs_ks'' actually ''sets'' the ''signalling'' parameter; when the ''channel => 1'' line is reached, then all preceding parameter assignments are applied to that particular channel. This also means that if you somewhere have set a channel to belong to context "foo", and then never set a context again, then every next channel also gets assigned to "foo". So remember: if you don't see a parameter being set with a specific channel, you CANNOT assume that it then has it's default value; if a preceding channel has set that parameter to value "bar", then for your specific channel, it is "bar" also. An interesting thing to see here is how ''genzaptelconf'' deals with the above concept. After defining each channel, it resets the most important parameters (a.o. the ones that should be unique with a channel) to empty or "default". This means that if you yourself are very meticulous, you could do without that safety net, and rewrite the above configuration file as: signalling=fxo_ks callerid="Channel 1" <6001> mailbox=6001 group=5 context=from-internal channel => 1 signalling=fxo_ks callerid="Channel 2" <6002> mailbox=6002 group=5 context=from-internal channel => 2 signalling=fxs_ks callerid=asreceived group=0 context=from-pstn channel => 3 Note: we like the thoroughnes of the ''genzaptelconf'' configuration, but we like the readability of the second file more. ==zapata.conf== [trunkgroups] [channels] switchtype=national rxwink=300 ; Atlas seems to use long (250ms) winks usecallerid=yes hidecallerid=no callwaiting=yes usecallingpres=yes callwaitingcallerid=yes threewaycalling=yes transfer=yes canpark=yes cancallforward=yes callreturn=yes echocancel=yes echocancelwhenbridged=yes rxgain=0.0 txgain=0.0 callgroup=1 pickupgroup=1 immediate=no #include zapata-channels.conf Under Debian, ==sip.conf== This is a sample configuration for VOIP with XS4ALL ;;/etc/asterisk/sip.conf;; [general] context=default externip=82.161.20.132 dtfmmode=inband localnet=192.168.70.0/24 port=5060 bindaddr=0.0.0.0 disallow=all allow=alaw allow=ulaw registerattempts=0 defaultexpiry=7200 register => 08787XXXXX:PASSWORD@sip.xs4all.nl/08787XXXXX [xs4all] type=friend username=08787XXXXX fromuser=08787XXXXX fromdomain=sip.xs4all.nl secret=PASSWORD host=sip.xs4all.nl insecure=invite context=fromxs4all canreinvite=no dtmfmode=inband disallow=all allow=alaw allow=ulaw = Asterisk dialplans - contexts = A dial plan consists of a number of extensions. Each extensions consists of a number of priorities. Extensions are grouped in contexts. For each priority, an application is called. [context] exten => id, priority, command When Asterisk receives an incoming connection on a channel, Asterisk looks at the context defined for that channel for commands telling Asterisk what it should do. The context defines different sets of commands depending on what extension the user has dialed. For example, a context might provide one set of commands for what to do if the user dials "123", and another set of commands for what to do if the user dials "9", and another set of commands for what to do if the user dials any number beginning with "555". For some kinds of connections — such incoming calls from an outside telephone line — the user has not dialed an extension. In that case, Asterisk behaves as if the user had dialed a special extension named "s" (for Start). Asterisk will look for an extension "number" s in the definition of the context for that channel for instructions about what it should do to handle the call. Let's say, for example, that you have a channel "Zap/1" which is a connection to a telephone handset in your building. And let's say that in the configuration file for Zap channels (zapata.conf), you have defined context=john for Zap channel 1. So when you use that handset to dial a number, Asterisk looks for a context with the name "john" in extensions.conf to find out what it should do. You begin the definition of a context in extensions.conf by putting the name of the context in square brackets on a line by itself, like this: [john] ef1a63ff9e0a1dfc45151ac7ca9c64790c4914e7 2414 2413 2009-07-13T08:10:55Z Insomnia 3 /* sip.conf */ wikitext text/x-wiki = Asterisk basic configuration principles = In this section we'll have a look at the basic configuration of an Asterisk PBX. Contrary to the TFOT-book, we'll be looking at it from the theory side, and from there go to an example configuration. For this example configuration, we'll start from a server with on the "outside" a POTS line and a SIP account with an Internet provider, and on the "inside" two analogue telephones and a SIP softphone. Our goal is to let the PBX behave as if we don't even have a PBX, but a standard home situation: for an incoming call, all phones ring; and every internal phone can make calls to the outside. = Asterisk channel configuration basics = The first thing to realise is that Asterisk sees each connected telephony device as a "channel". But what is a Channel? To Asterisk, a channel is a connection which brings in a call to the Asterisk PBX. A channel could be a connection to an ordinary telephone handset or an ordinary telephone line, or to a logical call (like an Internet phone call). Asterisk makes no distinction between "FXO" and "FXS" style channels (that is, it doesn't distinguish between telephone lines and telephones). Every call is placed or received on a distinct channel. The second thing to realise, is that every type of device attached to the Asterisk PBX have their own specific configuration files. Correctly setting up each (set of) telephony devices makes them available in our Asterisk PBX as channels. Thus, the device configuration files serve as a kind of abstraction layer, and simplify our final Asterisk configuration by putting "channel-specific" information in separate files. If you've followed the previous Asterisk sections in this Wiki, or followed the first four chapters of the TFOT-book, then you've encountered the following configuration files: * ''zaptel.conf'' - in this file, you can set up the most basic parameters for your Zap-type hardware channels, most notably Digium telephony cards. You're configuring the hardware itself, via its driver. You could think of this file as belonging to the hardware, not Asterisk. If you'd have other software on your machine besides Asterisk that could make use of your telephony hardware, then that'd be influenced as well when you change ''zaptel.conf''. * ''zapata.conf'' (and possibly ''zapata-channels.conf'' if you're on Debian) - this file handles the Asterisk-specific configuration of the hardware telephony channels. It thus "sets up the Zap channels" that Asterisk sees - for incoming and outgoing calls. All parameters that set up the channel are specified here. * ''vpb.conf'' - this file is used to configure [http://www.voicetronix.com/ Voicetronix] cards with Asterisk. If you've a Voicetronix card in use, then you've also installed the Voicetronix drivers. This makes the card(s) useable under Linux. But to have Asterisk use the card(s), you need this ''vpb.conf'' file. It thus serves the same purpose as ''zapata.conf''. * ''sip.conf'' - this file contains all information on all SIP devices that we want to connect to our Asterisk server; be it one or more SIP accounts with Internet providers, or SIP capable telephones (hardware or software). When ''sip.conf'' has been set up correctly, we can refer to a SIP device by a friendly name like [1000] or [Jane]. * ''iax.conf'' - this file is just the same as the ''sip.conf'' file, only it handles devices that talk IAX2 protocol instead of the SIP protocol. These five files define all channels that our basic Asterisk PBX might handle (well, it won't even handle the last one, since we're not connecting any other Asterisk boxes or IAX-(soft)phones to our PBX, and it won't handle the third one if you don't have a Voicetronix card). As a reference, we're going to list the contents of four example files, and explain what they do in the way of preparing channels for our simple Asterisk server.: ==zaptel.conf== # Autogenerated by ./genzaptelconf -- do not hand edit # Zaptel Configuration File # # This file is parsed by the Zaptel Configurator, ztcfg # # It must be in the module loading order # Span 1: WCTDM/0 "Wildcard TDM410P Board 1" (MASTER) fxoks=1 fxoks=2 fxsks=3 # channel 4, WCTDM, no module. # Global data loadzone = nl defaultzone = nl This is a relatively simple file, configuring three Digium modules. As you can see, the ''genzaptelconf'' command has generated it for us. It belongs with a Digium TDM410P card, which has two FXS modules in positions 1 and 2, and one FXO module in position 3. The first two non-commented lines define the protocol that the FXS modules must "talk" with the attached devices, which "naturally" is the FXO protocol (yes, FXS talks FXO, and FXO talks FXS... a bit like electric current flowing from negative to positive. It's just a matter of definitions).<br> The third line defines that the FXO module talks FXS protocol.<br> The fourth line configures a set of indications to use for the defined channels. Since we're loading "nl", we're configuring Dutch dialtones etcetera for the channels.<br> Finally, the last line tell the server that any channel that does not have a zone assigned to it, should have the specified default zone configured - Dutch as well in this example.<br> With this simple file, the driver for our example card (''wctdm24xxp'', by the way) can set up the hardware just as we want it. Now to tell Asterisk how to use it... ==zapata-channels.conf== ; Autogenerated by ./genzaptelconf -- do not hand edit ; Zaptel Channels Configurations (zapata.conf) ; ; This is not intended to be a complete zapata.conf. Rather, it is intended ; to be #include-d by /etc/zapata.conf that will include the global settings ; ; Span 1: WCTDM/0 "Wildcard TDM410P Board 1" (MASTER) ;;; line="1 WCTDM/0/0" signalling=fxo_ks callerid="Channel 1" <6001> mailbox=6001 group=5 context=from-internal channel => 1 callerid= mailbox= group= context=default ;;; line="2 WCTDM/0/1" signalling=fxo_ks callerid="Channel 2" <6002> mailbox=6002 group=5 context=from-internal channel => 2 callerid= mailbox= group= context=default ;;; line="3 WCTDM/0/2" signalling=fxs_ks callerid=asreceived group=0 context=from-pstn channel => 3 context=default This second file is also auto-generated. It sets up three channels, associated with the three Digium hardware modules that we've configured with ''zaptel.conf''. Here, we also see how the channel numbers get assigned to the physical ports. The first module gets to be Zap channel 1 ('''Zap/1'''), the second '''Zap/2''' and so on. So if we would like our FXO module to be channel 1, and our FXS modules 2 and three, we could rotate the three channel numbers in this file. Probably we'd then also want to rotate the ''callerid''`s though... Furthermore, we don't think it's a good idea to assign channels to Zap devices in a different order than the devices are found in the system - meaning "stick with the default numbering as much as possible". Note that the way ''zapata-channels.conf'' is interpreted, means that any statement like ''signalling=fxs_ks'' actually ''sets'' the ''signalling'' parameter; when the ''channel => 1'' line is reached, then all preceding parameter assignments are applied to that particular channel. This also means that if you somewhere have set a channel to belong to context "foo", and then never set a context again, then every next channel also gets assigned to "foo". So remember: if you don't see a parameter being set with a specific channel, you CANNOT assume that it then has it's default value; if a preceding channel has set that parameter to value "bar", then for your specific channel, it is "bar" also. An interesting thing to see here is how ''genzaptelconf'' deals with the above concept. After defining each channel, it resets the most important parameters (a.o. the ones that should be unique with a channel) to empty or "default". This means that if you yourself are very meticulous, you could do without that safety net, and rewrite the above configuration file as: signalling=fxo_ks callerid="Channel 1" <6001> mailbox=6001 group=5 context=from-internal channel => 1 signalling=fxo_ks callerid="Channel 2" <6002> mailbox=6002 group=5 context=from-internal channel => 2 signalling=fxs_ks callerid=asreceived group=0 context=from-pstn channel => 3 Note: we like the thoroughnes of the ''genzaptelconf'' configuration, but we like the readability of the second file more. ==zapata.conf== [trunkgroups] [channels] switchtype=national rxwink=300 ; Atlas seems to use long (250ms) winks usecallerid=yes hidecallerid=no callwaiting=yes usecallingpres=yes callwaitingcallerid=yes threewaycalling=yes transfer=yes canpark=yes cancallforward=yes callreturn=yes echocancel=yes echocancelwhenbridged=yes rxgain=0.0 txgain=0.0 callgroup=1 pickupgroup=1 immediate=no #include zapata-channels.conf Under Debian, ==sip.conf== This is a sample configuration for VOIP with XS4ALL ;;/etc/asterisk/sip.conf;; [general] context=default externip=82.161.20.132 dtfmmode=inband localnet=192.168.70.0/24 port=5060 bindaddr=0.0.0.0 disallow=all allow=alaw allow=ulaw registerattempts=0 defaultexpiry=7200 register => 08787XXXXX:PASSWORD@sip.xs4all.nl/08787XXXXX [xs4all] type=friend username=08787XXXXX fromuser=08787XXXXX fromdomain=sip.xs4all.nl secret=PASSWORD host=sip.xs4all.nl insecure=invite context=fromxs4all canreinvite=no dtmfmode=inband disallow=all allow=alaw allow=ulaw = Asterisk dialplans - contexts = A dial plan consists of a number of extensions. Each extensions consists of a number of priorities. Extensions are grouped in contexts. For each priority, an application is called. [context] exten => id, priority, command When Asterisk receives an incoming connection on a channel, Asterisk looks at the context defined for that channel for commands telling Asterisk what it should do. The context defines different sets of commands depending on what extension the user has dialed. For example, a context might provide one set of commands for what to do if the user dials "123", and another set of commands for what to do if the user dials "9", and another set of commands for what to do if the user dials any number beginning with "555". For some kinds of connections — such incoming calls from an outside telephone line — the user has not dialed an extension. In that case, Asterisk behaves as if the user had dialed a special extension named "s" (for Start). Asterisk will look for an extension "number" s in the definition of the context for that channel for instructions about what it should do to handle the call. Let's say, for example, that you have a channel "Zap/1" which is a connection to a telephone handset in your building. And let's say that in the configuration file for Zap channels (zapata.conf), you have defined context=john for Zap channel 1. So when you use that handset to dial a number, Asterisk looks for a context with the name "john" in extensions.conf to find out what it should do. You begin the definition of a context in extensions.conf by putting the name of the context in square brackets on a line by itself, like this: [john] 38c4a6920a7321aebc879c9bab4c6877ce254c61 2415 2414 2009-07-13T08:15:16Z Insomnia 3 /* Asterisk dialplans - contexts */ wikitext text/x-wiki = Asterisk basic configuration principles = In this section we'll have a look at the basic configuration of an Asterisk PBX. Contrary to the TFOT-book, we'll be looking at it from the theory side, and from there go to an example configuration. For this example configuration, we'll start from a server with on the "outside" a POTS line and a SIP account with an Internet provider, and on the "inside" two analogue telephones and a SIP softphone. Our goal is to let the PBX behave as if we don't even have a PBX, but a standard home situation: for an incoming call, all phones ring; and every internal phone can make calls to the outside. = Asterisk channel configuration basics = The first thing to realise is that Asterisk sees each connected telephony device as a "channel". But what is a Channel? To Asterisk, a channel is a connection which brings in a call to the Asterisk PBX. A channel could be a connection to an ordinary telephone handset or an ordinary telephone line, or to a logical call (like an Internet phone call). Asterisk makes no distinction between "FXO" and "FXS" style channels (that is, it doesn't distinguish between telephone lines and telephones). Every call is placed or received on a distinct channel. The second thing to realise, is that every type of device attached to the Asterisk PBX have their own specific configuration files. Correctly setting up each (set of) telephony devices makes them available in our Asterisk PBX as channels. Thus, the device configuration files serve as a kind of abstraction layer, and simplify our final Asterisk configuration by putting "channel-specific" information in separate files. If you've followed the previous Asterisk sections in this Wiki, or followed the first four chapters of the TFOT-book, then you've encountered the following configuration files: * ''zaptel.conf'' - in this file, you can set up the most basic parameters for your Zap-type hardware channels, most notably Digium telephony cards. You're configuring the hardware itself, via its driver. You could think of this file as belonging to the hardware, not Asterisk. If you'd have other software on your machine besides Asterisk that could make use of your telephony hardware, then that'd be influenced as well when you change ''zaptel.conf''. * ''zapata.conf'' (and possibly ''zapata-channels.conf'' if you're on Debian) - this file handles the Asterisk-specific configuration of the hardware telephony channels. It thus "sets up the Zap channels" that Asterisk sees - for incoming and outgoing calls. All parameters that set up the channel are specified here. * ''vpb.conf'' - this file is used to configure [http://www.voicetronix.com/ Voicetronix] cards with Asterisk. If you've a Voicetronix card in use, then you've also installed the Voicetronix drivers. This makes the card(s) useable under Linux. But to have Asterisk use the card(s), you need this ''vpb.conf'' file. It thus serves the same purpose as ''zapata.conf''. * ''sip.conf'' - this file contains all information on all SIP devices that we want to connect to our Asterisk server; be it one or more SIP accounts with Internet providers, or SIP capable telephones (hardware or software). When ''sip.conf'' has been set up correctly, we can refer to a SIP device by a friendly name like [1000] or [Jane]. * ''iax.conf'' - this file is just the same as the ''sip.conf'' file, only it handles devices that talk IAX2 protocol instead of the SIP protocol. These five files define all channels that our basic Asterisk PBX might handle (well, it won't even handle the last one, since we're not connecting any other Asterisk boxes or IAX-(soft)phones to our PBX, and it won't handle the third one if you don't have a Voicetronix card). As a reference, we're going to list the contents of four example files, and explain what they do in the way of preparing channels for our simple Asterisk server.: ==zaptel.conf== # Autogenerated by ./genzaptelconf -- do not hand edit # Zaptel Configuration File # # This file is parsed by the Zaptel Configurator, ztcfg # # It must be in the module loading order # Span 1: WCTDM/0 "Wildcard TDM410P Board 1" (MASTER) fxoks=1 fxoks=2 fxsks=3 # channel 4, WCTDM, no module. # Global data loadzone = nl defaultzone = nl This is a relatively simple file, configuring three Digium modules. As you can see, the ''genzaptelconf'' command has generated it for us. It belongs with a Digium TDM410P card, which has two FXS modules in positions 1 and 2, and one FXO module in position 3. The first two non-commented lines define the protocol that the FXS modules must "talk" with the attached devices, which "naturally" is the FXO protocol (yes, FXS talks FXO, and FXO talks FXS... a bit like electric current flowing from negative to positive. It's just a matter of definitions).<br> The third line defines that the FXO module talks FXS protocol.<br> The fourth line configures a set of indications to use for the defined channels. Since we're loading "nl", we're configuring Dutch dialtones etcetera for the channels.<br> Finally, the last line tell the server that any channel that does not have a zone assigned to it, should have the specified default zone configured - Dutch as well in this example.<br> With this simple file, the driver for our example card (''wctdm24xxp'', by the way) can set up the hardware just as we want it. Now to tell Asterisk how to use it... ==zapata-channels.conf== ; Autogenerated by ./genzaptelconf -- do not hand edit ; Zaptel Channels Configurations (zapata.conf) ; ; This is not intended to be a complete zapata.conf. Rather, it is intended ; to be #include-d by /etc/zapata.conf that will include the global settings ; ; Span 1: WCTDM/0 "Wildcard TDM410P Board 1" (MASTER) ;;; line="1 WCTDM/0/0" signalling=fxo_ks callerid="Channel 1" <6001> mailbox=6001 group=5 context=from-internal channel => 1 callerid= mailbox= group= context=default ;;; line="2 WCTDM/0/1" signalling=fxo_ks callerid="Channel 2" <6002> mailbox=6002 group=5 context=from-internal channel => 2 callerid= mailbox= group= context=default ;;; line="3 WCTDM/0/2" signalling=fxs_ks callerid=asreceived group=0 context=from-pstn channel => 3 context=default This second file is also auto-generated. It sets up three channels, associated with the three Digium hardware modules that we've configured with ''zaptel.conf''. Here, we also see how the channel numbers get assigned to the physical ports. The first module gets to be Zap channel 1 ('''Zap/1'''), the second '''Zap/2''' and so on. So if we would like our FXO module to be channel 1, and our FXS modules 2 and three, we could rotate the three channel numbers in this file. Probably we'd then also want to rotate the ''callerid''`s though... Furthermore, we don't think it's a good idea to assign channels to Zap devices in a different order than the devices are found in the system - meaning "stick with the default numbering as much as possible". Note that the way ''zapata-channels.conf'' is interpreted, means that any statement like ''signalling=fxs_ks'' actually ''sets'' the ''signalling'' parameter; when the ''channel => 1'' line is reached, then all preceding parameter assignments are applied to that particular channel. This also means that if you somewhere have set a channel to belong to context "foo", and then never set a context again, then every next channel also gets assigned to "foo". So remember: if you don't see a parameter being set with a specific channel, you CANNOT assume that it then has it's default value; if a preceding channel has set that parameter to value "bar", then for your specific channel, it is "bar" also. An interesting thing to see here is how ''genzaptelconf'' deals with the above concept. After defining each channel, it resets the most important parameters (a.o. the ones that should be unique with a channel) to empty or "default". This means that if you yourself are very meticulous, you could do without that safety net, and rewrite the above configuration file as: signalling=fxo_ks callerid="Channel 1" <6001> mailbox=6001 group=5 context=from-internal channel => 1 signalling=fxo_ks callerid="Channel 2" <6002> mailbox=6002 group=5 context=from-internal channel => 2 signalling=fxs_ks callerid=asreceived group=0 context=from-pstn channel => 3 Note: we like the thoroughnes of the ''genzaptelconf'' configuration, but we like the readability of the second file more. ==zapata.conf== [trunkgroups] [channels] switchtype=national rxwink=300 ; Atlas seems to use long (250ms) winks usecallerid=yes hidecallerid=no callwaiting=yes usecallingpres=yes callwaitingcallerid=yes threewaycalling=yes transfer=yes canpark=yes cancallforward=yes callreturn=yes echocancel=yes echocancelwhenbridged=yes rxgain=0.0 txgain=0.0 callgroup=1 pickupgroup=1 immediate=no #include zapata-channels.conf Under Debian, ==sip.conf== This is a sample configuration for VOIP with XS4ALL ;;/etc/asterisk/sip.conf;; [general] context=default externip=82.161.20.132 dtfmmode=inband localnet=192.168.70.0/24 port=5060 bindaddr=0.0.0.0 disallow=all allow=alaw allow=ulaw registerattempts=0 defaultexpiry=7200 register => 08787XXXXX:PASSWORD@sip.xs4all.nl/08787XXXXX [xs4all] type=friend username=08787XXXXX fromuser=08787XXXXX fromdomain=sip.xs4all.nl secret=PASSWORD host=sip.xs4all.nl insecure=invite context=fromxs4all canreinvite=no dtmfmode=inband disallow=all allow=alaw allow=ulaw = Asterisk dialplans - contexts = A dial plan consists of a number of extensions. Each extensions consists of a number of priorities. Extensions are grouped in contexts. For each priority, an application is called. [context] exten => id, priority, command When Asterisk receives an incoming connection on a channel, Asterisk looks at the context defined for that channel for commands telling Asterisk what it should do. The context defines different sets of commands depending on what extension the user has dialed. For example, a context might provide one set of commands for what to do if the user dials "123", and another set of commands for what to do if the user dials "9", and another set of commands for what to do if the user dials any number beginning with "555". For some kinds of connections — such incoming calls from an outside telephone line — the user has not dialed an extension. In that case, Asterisk behaves as if the user had dialed a special extension named "s" (for Start). Asterisk will look for an extension "number" s in the definition of the context for that channel for instructions about what it should do to handle the call. Let's say, for example, that you have a channel "Zap/1" which is a connection to a telephone handset in your building. And let's say that in the configuration file for Zap channels (zapata.conf), you have defined context=john for Zap channel 1. So when you use that handset to dial a number, Asterisk looks for a context with the name "john" in extensions.conf to find out what it should do. You begin the definition of a context in extensions.conf by putting the name of the context in square brackets on a line by itself, like this: [john] == extensions.conf == [globals] [general] autofallthrough=yes [default] include => fromxs4all [fromxs4all] exten => 0878767430,1,Dial(DAHDI/2) exten => 0878767430,n,Hangup() [outgoing] exten => _X.,1,Dial(sip/xs4all/${EXTEN},60,r) [internal] exten => 6004,1,Dial(sip/6004) exten => 6003,1,Dial(sip/6003) exten => 6005,1,Dial(DAHDI/2) exten => 6006,1,Answer() exten => 6006,n,Playback(hello-world) exten => 6006,n,Hangup() [phones] include => internal include => fromxs4all include => outgoing 921e11e0a6d9109d74096280d41892b74fb9df99 2417 2415 2009-07-13T09:32:13Z Insomnia 3 /* Asterisk channel configuration basics */ wikitext text/x-wiki = Asterisk basic configuration principles = In this section we'll have a look at the basic configuration of an Asterisk PBX. Contrary to the TFOT-book, we'll be looking at it from the theory side, and from there go to an example configuration. For this example configuration, we'll start from a server with on the "outside" a POTS line and a SIP account with an Internet provider, and on the "inside" two analogue telephones and a SIP softphone. Our goal is to let the PBX behave as if we don't even have a PBX, but a standard home situation: for an incoming call, all phones ring; and every internal phone can make calls to the outside. = Asterisk channel configuration basics = The first thing to realise is that Asterisk sees each connected telephony device as a "channel". But what is a Channel? To Asterisk, a channel is a connection which brings in a call to the Asterisk PBX. A channel could be a connection to an ordinary telephone handset or an ordinary telephone line, or to a logical call (like an Internet phone call). Asterisk makes no distinction between "FXO" and "FXS" style channels (that is, it doesn't distinguish between telephone lines and telephones). Every call is placed or received on a distinct channel. The second thing to realise, is that every type of device attached to the Asterisk PBX have their own specific configuration files. Correctly setting up each (set of) telephony devices makes them available in our Asterisk PBX as channels. Thus, the device configuration files serve as a kind of abstraction layer, and simplify our final Asterisk configuration by putting "channel-specific" information in separate files. If you've followed the previous Asterisk sections in this Wiki, or followed the first four chapters of the TFOT-book, then you've encountered the following configuration files: * ''zaptel.conf'' - in this file, you can set up the most basic parameters for your Zap-type hardware channels, most notably Digium telephony cards. You're configuring the hardware itself, via its driver. You could think of this file as belonging to the hardware, not Asterisk. If you'd have other software on your machine besides Asterisk that could make use of your telephony hardware, then that'd be influenced as well when you change ''zaptel.conf''. * ''zapata.conf'' (and possibly ''zapata-channels.conf'' if you're on Debian) - this file handles the Asterisk-specific configuration of the hardware telephony channels. It thus "sets up the Zap channels" that Asterisk sees - for incoming and outgoing calls. All parameters that set up the channel are specified here. * ''vpb.conf'' - this file is used to configure [http://www.voicetronix.com/ Voicetronix] cards with Asterisk. If you've a Voicetronix card in use, then you've also installed the Voicetronix drivers. This makes the card(s) useable under Linux. But to have Asterisk use the card(s), you need this ''vpb.conf'' file. It thus serves the same purpose as ''zapata.conf''. * ''sip.conf'' - this file contains all information on all SIP devices that we want to connect to our Asterisk server; be it one or more SIP accounts with Internet providers, or SIP capable telephones (hardware or software). When ''sip.conf'' has been set up correctly, we can refer to a SIP device by a friendly name like [1000] or [Jane]. * ''iax.conf'' - this file is just the same as the ''sip.conf'' file, only it handles devices that talk IAX2 protocol instead of the SIP protocol. These five files define all channels that our basic Asterisk PBX might handle (well, it won't even handle the last one, since we're not connecting any other Asterisk boxes or IAX-(soft)phones to our PBX, and it won't handle the third one if you don't have a Voicetronix card). As a reference, we're going to list the contents of four example files, and explain what they do in the way of preparing channels for our simple Asterisk server.: ==zaptel.conf== # Autogenerated by ./genzaptelconf -- do not hand edit # Zaptel Configuration File # # This file is parsed by the Zaptel Configurator, ztcfg # # It must be in the module loading order # Span 1: WCTDM/0 "Wildcard TDM410P Board 1" (MASTER) fxoks=1 fxoks=2 fxsks=3 # channel 4, WCTDM, no module. # Global data loadzone = nl defaultzone = nl This is a relatively simple file, configuring three Digium modules. As you can see, the ''genzaptelconf'' command has generated it for us. It belongs with a Digium TDM410P card, which has two FXS modules in positions 1 and 2, and one FXO module in position 3. The first two non-commented lines define the protocol that the FXS modules must "talk" with the attached devices, which "naturally" is the FXO protocol (yes, FXS talks FXO, and FXO talks FXS... a bit like electric current flowing from negative to positive. It's just a matter of definitions).<br> The third line defines that the FXO module talks FXS protocol.<br> The fourth line configures a set of indications to use for the defined channels. Since we're loading "nl", we're configuring Dutch dialtones etcetera for the channels.<br> Finally, the last line tell the server that any channel that does not have a zone assigned to it, should have the specified default zone configured - Dutch as well in this example.<br> With this simple file, the driver for our example card (''wctdm24xxp'', by the way) can set up the hardware just as we want it. Now to tell Asterisk how to use it... ==zapata-channels.conf== ; Autogenerated by ./genzaptelconf -- do not hand edit ; Zaptel Channels Configurations (zapata.conf) ; ; This is not intended to be a complete zapata.conf. Rather, it is intended ; to be #include-d by /etc/zapata.conf that will include the global settings ; ; Span 1: WCTDM/0 "Wildcard TDM410P Board 1" (MASTER) ;;; line="1 WCTDM/0/0" signalling=fxo_ks callerid="Channel 1" <6001> mailbox=6001 group=5 context=from-internal channel => 1 callerid= mailbox= group= context=default ;;; line="2 WCTDM/0/1" signalling=fxo_ks callerid="Channel 2" <6002> mailbox=6002 group=5 context=from-internal channel => 2 callerid= mailbox= group= context=default ;;; line="3 WCTDM/0/2" signalling=fxs_ks callerid=asreceived group=0 context=from-pstn channel => 3 context=default This second file is also auto-generated. It sets up three channels, associated with the three Digium hardware modules that we've configured with ''zaptel.conf''. Here, we also see how the channel numbers get assigned to the physical ports. The first module gets to be Zap channel 1 ('''Zap/1'''), the second '''Zap/2''' and so on. So if we would like our FXO module to be channel 1, and our FXS modules 2 and three, we could rotate the three channel numbers in this file. Probably we'd then also want to rotate the ''callerid''`s though... Furthermore, we don't think it's a good idea to assign channels to Zap devices in a different order than the devices are found in the system - meaning "stick with the default numbering as much as possible". Note that the way ''zapata-channels.conf'' is interpreted, means that any statement like ''signalling=fxs_ks'' actually ''sets'' the ''signalling'' parameter; when the ''channel => 1'' line is reached, then all preceding parameter assignments are applied to that particular channel. This also means that if you somewhere have set a channel to belong to context "foo", and then never set a context again, then every next channel also gets assigned to "foo". So remember: if you don't see a parameter being set with a specific channel, you CANNOT assume that it then has it's default value; if a preceding channel has set that parameter to value "bar", then for your specific channel, it is "bar" also. An interesting thing to see here is how ''genzaptelconf'' deals with the above concept. After defining each channel, it resets the most important parameters (a.o. the ones that should be unique with a channel) to empty or "default". This means that if you yourself are very meticulous, you could do without that safety net, and rewrite the above configuration file as: signalling=fxo_ks callerid="Channel 1" <6001> mailbox=6001 group=5 context=from-internal channel => 1 signalling=fxo_ks callerid="Channel 2" <6002> mailbox=6002 group=5 context=from-internal channel => 2 signalling=fxs_ks callerid=asreceived group=0 context=from-pstn channel => 3 Note: we like the thoroughnes of the ''genzaptelconf'' configuration, but we like the readability of the second file more. ==zapata.conf== [trunkgroups] [channels] switchtype=national rxwink=300 ; Atlas seems to use long (250ms) winks usecallerid=yes hidecallerid=no callwaiting=yes usecallingpres=yes callwaitingcallerid=yes threewaycalling=yes transfer=yes canpark=yes cancallforward=yes callreturn=yes echocancel=yes echocancelwhenbridged=yes rxgain=0.0 txgain=0.0 callgroup=1 pickupgroup=1 immediate=no #include zapata-channels.conf Under Debian, ==sip.conf== This is a sample configuration for VOIP with XS4ALL ;;/etc/asterisk/sip.conf;; [general] context=default externip=82.161.20.132 dtfmmode=inband localnet=192.168.70.0/24 port=5060 bindaddr=0.0.0.0 disallow=all allow=alaw allow=ulaw registerattempts=0 defaultexpiry=7200 register => 08787XXXXX:PASSWORD@sip.xs4all.nl/08787XXXXX [xs4all] type=friend username=08787XXXXX fromuser=08787XXXXX fromdomain=sip.xs4all.nl secret=PASSWORD host=sip.xs4all.nl insecure=invite context=fromxs4all canreinvite=no dtmfmode=inband disallow=all allow=alaw allow=ulaw == DAHDI == From asterisk version 1.4 zaptel is renamed in DAHDI witch stands for Digium Asterisk Hardware Device Interface. If you installed the dahdi-tools (highly recommended) then you can configure you're hardware Conversion from zaptel /etc/zaptel.conf Becomes /etc/dahdi/system.conf /etc/asterisk/zapata.conf Becomes /etc/asterisk/chan_dahdi.conf Lets look at what we have #dahdi_tool This will give a overview of the hardware and if it is configured or not. It will all so show alarms on the hardware. Now lets configure the card. First edit /etc/dadi/genconf_parameters. This file is used with dahdi_genconf and will produce /etc/dahdi-system.conf *lc_country nl You can also set the echo cancelation here MG2 is default #dahdi_genconf #dahdi_cfg -vv DAHDI Tools Version - 2.2.0 DAHDI Version: 2.2.0.1 Echo Canceller(s): MG2 Configuration ====================== Channel map: Channel 01: FXO Kewlstart (Default) (Echo Canceler: mg2) (Slaves: 01) Channel 02: FXO Kewlstart (Default) (Echo Canceler: mg2) (Slaves: 02) 2 channels to configure. Setting echocan for channel 1 to mg2 Setting echocan for channel 2 to mg2 Check if the right module is loaded. #cat /etc/dahdi/modules You can configure the options of dahdi in /etc/asterisk/chan_dahdi.conf for example turn off the echo cancelation = Asterisk dialplans - contexts = A dial plan consists of a number of extensions. Each extensions consists of a number of priorities. Extensions are grouped in contexts. For each priority, an application is called. [context] exten => id, priority, command When Asterisk receives an incoming connection on a channel, Asterisk looks at the context defined for that channel for commands telling Asterisk what it should do. The context defines different sets of commands depending on what extension the user has dialed. For example, a context might provide one set of commands for what to do if the user dials "123", and another set of commands for what to do if the user dials "9", and another set of commands for what to do if the user dials any number beginning with "555". For some kinds of connections — such incoming calls from an outside telephone line — the user has not dialed an extension. In that case, Asterisk behaves as if the user had dialed a special extension named "s" (for Start). Asterisk will look for an extension "number" s in the definition of the context for that channel for instructions about what it should do to handle the call. Let's say, for example, that you have a channel "Zap/1" which is a connection to a telephone handset in your building. And let's say that in the configuration file for Zap channels (zapata.conf), you have defined context=john for Zap channel 1. So when you use that handset to dial a number, Asterisk looks for a context with the name "john" in extensions.conf to find out what it should do. You begin the definition of a context in extensions.conf by putting the name of the context in square brackets on a line by itself, like this: [john] == extensions.conf == [globals] [general] autofallthrough=yes [default] include => fromxs4all [fromxs4all] exten => 0878767430,1,Dial(DAHDI/2) exten => 0878767430,n,Hangup() [outgoing] exten => _X.,1,Dial(sip/xs4all/${EXTEN},60,r) [internal] exten => 6004,1,Dial(sip/6004) exten => 6003,1,Dial(sip/6003) exten => 6005,1,Dial(DAHDI/2) exten => 6006,1,Answer() exten => 6006,n,Playback(hello-world) exten => 6006,n,Hangup() [phones] include => internal include => fromxs4all include => outgoing e6cbbb4a511200aab50531cb86816e51658b44e6 2418 2417 2009-07-13T09:40:47Z Insomnia 3 /* extensions.conf */ wikitext text/x-wiki = Asterisk basic configuration principles = In this section we'll have a look at the basic configuration of an Asterisk PBX. Contrary to the TFOT-book, we'll be looking at it from the theory side, and from there go to an example configuration. For this example configuration, we'll start from a server with on the "outside" a POTS line and a SIP account with an Internet provider, and on the "inside" two analogue telephones and a SIP softphone. Our goal is to let the PBX behave as if we don't even have a PBX, but a standard home situation: for an incoming call, all phones ring; and every internal phone can make calls to the outside. = Asterisk channel configuration basics = The first thing to realise is that Asterisk sees each connected telephony device as a "channel". But what is a Channel? To Asterisk, a channel is a connection which brings in a call to the Asterisk PBX. A channel could be a connection to an ordinary telephone handset or an ordinary telephone line, or to a logical call (like an Internet phone call). Asterisk makes no distinction between "FXO" and "FXS" style channels (that is, it doesn't distinguish between telephone lines and telephones). Every call is placed or received on a distinct channel. The second thing to realise, is that every type of device attached to the Asterisk PBX have their own specific configuration files. Correctly setting up each (set of) telephony devices makes them available in our Asterisk PBX as channels. Thus, the device configuration files serve as a kind of abstraction layer, and simplify our final Asterisk configuration by putting "channel-specific" information in separate files. If you've followed the previous Asterisk sections in this Wiki, or followed the first four chapters of the TFOT-book, then you've encountered the following configuration files: * ''zaptel.conf'' - in this file, you can set up the most basic parameters for your Zap-type hardware channels, most notably Digium telephony cards. You're configuring the hardware itself, via its driver. You could think of this file as belonging to the hardware, not Asterisk. If you'd have other software on your machine besides Asterisk that could make use of your telephony hardware, then that'd be influenced as well when you change ''zaptel.conf''. * ''zapata.conf'' (and possibly ''zapata-channels.conf'' if you're on Debian) - this file handles the Asterisk-specific configuration of the hardware telephony channels. It thus "sets up the Zap channels" that Asterisk sees - for incoming and outgoing calls. All parameters that set up the channel are specified here. * ''vpb.conf'' - this file is used to configure [http://www.voicetronix.com/ Voicetronix] cards with Asterisk. If you've a Voicetronix card in use, then you've also installed the Voicetronix drivers. This makes the card(s) useable under Linux. But to have Asterisk use the card(s), you need this ''vpb.conf'' file. It thus serves the same purpose as ''zapata.conf''. * ''sip.conf'' - this file contains all information on all SIP devices that we want to connect to our Asterisk server; be it one or more SIP accounts with Internet providers, or SIP capable telephones (hardware or software). When ''sip.conf'' has been set up correctly, we can refer to a SIP device by a friendly name like [1000] or [Jane]. * ''iax.conf'' - this file is just the same as the ''sip.conf'' file, only it handles devices that talk IAX2 protocol instead of the SIP protocol. These five files define all channels that our basic Asterisk PBX might handle (well, it won't even handle the last one, since we're not connecting any other Asterisk boxes or IAX-(soft)phones to our PBX, and it won't handle the third one if you don't have a Voicetronix card). As a reference, we're going to list the contents of four example files, and explain what they do in the way of preparing channels for our simple Asterisk server.: ==zaptel.conf== # Autogenerated by ./genzaptelconf -- do not hand edit # Zaptel Configuration File # # This file is parsed by the Zaptel Configurator, ztcfg # # It must be in the module loading order # Span 1: WCTDM/0 "Wildcard TDM410P Board 1" (MASTER) fxoks=1 fxoks=2 fxsks=3 # channel 4, WCTDM, no module. # Global data loadzone = nl defaultzone = nl This is a relatively simple file, configuring three Digium modules. As you can see, the ''genzaptelconf'' command has generated it for us. It belongs with a Digium TDM410P card, which has two FXS modules in positions 1 and 2, and one FXO module in position 3. The first two non-commented lines define the protocol that the FXS modules must "talk" with the attached devices, which "naturally" is the FXO protocol (yes, FXS talks FXO, and FXO talks FXS... a bit like electric current flowing from negative to positive. It's just a matter of definitions).<br> The third line defines that the FXO module talks FXS protocol.<br> The fourth line configures a set of indications to use for the defined channels. Since we're loading "nl", we're configuring Dutch dialtones etcetera for the channels.<br> Finally, the last line tell the server that any channel that does not have a zone assigned to it, should have the specified default zone configured - Dutch as well in this example.<br> With this simple file, the driver for our example card (''wctdm24xxp'', by the way) can set up the hardware just as we want it. Now to tell Asterisk how to use it... ==zapata-channels.conf== ; Autogenerated by ./genzaptelconf -- do not hand edit ; Zaptel Channels Configurations (zapata.conf) ; ; This is not intended to be a complete zapata.conf. Rather, it is intended ; to be #include-d by /etc/zapata.conf that will include the global settings ; ; Span 1: WCTDM/0 "Wildcard TDM410P Board 1" (MASTER) ;;; line="1 WCTDM/0/0" signalling=fxo_ks callerid="Channel 1" <6001> mailbox=6001 group=5 context=from-internal channel => 1 callerid= mailbox= group= context=default ;;; line="2 WCTDM/0/1" signalling=fxo_ks callerid="Channel 2" <6002> mailbox=6002 group=5 context=from-internal channel => 2 callerid= mailbox= group= context=default ;;; line="3 WCTDM/0/2" signalling=fxs_ks callerid=asreceived group=0 context=from-pstn channel => 3 context=default This second file is also auto-generated. It sets up three channels, associated with the three Digium hardware modules that we've configured with ''zaptel.conf''. Here, we also see how the channel numbers get assigned to the physical ports. The first module gets to be Zap channel 1 ('''Zap/1'''), the second '''Zap/2''' and so on. So if we would like our FXO module to be channel 1, and our FXS modules 2 and three, we could rotate the three channel numbers in this file. Probably we'd then also want to rotate the ''callerid''`s though... Furthermore, we don't think it's a good idea to assign channels to Zap devices in a different order than the devices are found in the system - meaning "stick with the default numbering as much as possible". Note that the way ''zapata-channels.conf'' is interpreted, means that any statement like ''signalling=fxs_ks'' actually ''sets'' the ''signalling'' parameter; when the ''channel => 1'' line is reached, then all preceding parameter assignments are applied to that particular channel. This also means that if you somewhere have set a channel to belong to context "foo", and then never set a context again, then every next channel also gets assigned to "foo". So remember: if you don't see a parameter being set with a specific channel, you CANNOT assume that it then has it's default value; if a preceding channel has set that parameter to value "bar", then for your specific channel, it is "bar" also. An interesting thing to see here is how ''genzaptelconf'' deals with the above concept. After defining each channel, it resets the most important parameters (a.o. the ones that should be unique with a channel) to empty or "default". This means that if you yourself are very meticulous, you could do without that safety net, and rewrite the above configuration file as: signalling=fxo_ks callerid="Channel 1" <6001> mailbox=6001 group=5 context=from-internal channel => 1 signalling=fxo_ks callerid="Channel 2" <6002> mailbox=6002 group=5 context=from-internal channel => 2 signalling=fxs_ks callerid=asreceived group=0 context=from-pstn channel => 3 Note: we like the thoroughnes of the ''genzaptelconf'' configuration, but we like the readability of the second file more. ==zapata.conf== [trunkgroups] [channels] switchtype=national rxwink=300 ; Atlas seems to use long (250ms) winks usecallerid=yes hidecallerid=no callwaiting=yes usecallingpres=yes callwaitingcallerid=yes threewaycalling=yes transfer=yes canpark=yes cancallforward=yes callreturn=yes echocancel=yes echocancelwhenbridged=yes rxgain=0.0 txgain=0.0 callgroup=1 pickupgroup=1 immediate=no #include zapata-channels.conf Under Debian, ==sip.conf== This is a sample configuration for VOIP with XS4ALL ;;/etc/asterisk/sip.conf;; [general] context=default externip=82.161.20.132 dtfmmode=inband localnet=192.168.70.0/24 port=5060 bindaddr=0.0.0.0 disallow=all allow=alaw allow=ulaw registerattempts=0 defaultexpiry=7200 register => 08787XXXXX:PASSWORD@sip.xs4all.nl/08787XXXXX [xs4all] type=friend username=08787XXXXX fromuser=08787XXXXX fromdomain=sip.xs4all.nl secret=PASSWORD host=sip.xs4all.nl insecure=invite context=fromxs4all canreinvite=no dtmfmode=inband disallow=all allow=alaw allow=ulaw == DAHDI == From asterisk version 1.4 zaptel is renamed in DAHDI witch stands for Digium Asterisk Hardware Device Interface. If you installed the dahdi-tools (highly recommended) then you can configure you're hardware Conversion from zaptel /etc/zaptel.conf Becomes /etc/dahdi/system.conf /etc/asterisk/zapata.conf Becomes /etc/asterisk/chan_dahdi.conf Lets look at what we have #dahdi_tool This will give a overview of the hardware and if it is configured or not. It will all so show alarms on the hardware. Now lets configure the card. First edit /etc/dadi/genconf_parameters. This file is used with dahdi_genconf and will produce /etc/dahdi-system.conf *lc_country nl You can also set the echo cancelation here MG2 is default #dahdi_genconf #dahdi_cfg -vv DAHDI Tools Version - 2.2.0 DAHDI Version: 2.2.0.1 Echo Canceller(s): MG2 Configuration ====================== Channel map: Channel 01: FXO Kewlstart (Default) (Echo Canceler: mg2) (Slaves: 01) Channel 02: FXO Kewlstart (Default) (Echo Canceler: mg2) (Slaves: 02) 2 channels to configure. Setting echocan for channel 1 to mg2 Setting echocan for channel 2 to mg2 Check if the right module is loaded. #cat /etc/dahdi/modules You can configure the options of dahdi in /etc/asterisk/chan_dahdi.conf for example turn off the echo cancelation = Asterisk dialplans - contexts = A dial plan consists of a number of extensions. Each extensions consists of a number of priorities. Extensions are grouped in contexts. For each priority, an application is called. [context] exten => id, priority, command When Asterisk receives an incoming connection on a channel, Asterisk looks at the context defined for that channel for commands telling Asterisk what it should do. The context defines different sets of commands depending on what extension the user has dialed. For example, a context might provide one set of commands for what to do if the user dials "123", and another set of commands for what to do if the user dials "9", and another set of commands for what to do if the user dials any number beginning with "555". For some kinds of connections — such incoming calls from an outside telephone line — the user has not dialed an extension. In that case, Asterisk behaves as if the user had dialed a special extension named "s" (for Start). Asterisk will look for an extension "number" s in the definition of the context for that channel for instructions about what it should do to handle the call. Let's say, for example, that you have a channel "Zap/1" which is a connection to a telephone handset in your building. And let's say that in the configuration file for Zap channels (zapata.conf), you have defined context=john for Zap channel 1. So when you use that handset to dial a number, Asterisk looks for a context with the name "john" in extensions.conf to find out what it should do. You begin the definition of a context in extensions.conf by putting the name of the context in square brackets on a line by itself, like this: [john] == extensions.conf == [globals] [general] autofallthrough=yes [default] include => fromxs4all [fromxs4all] exten => 08787XXXXX,1,Dial(DAHDI/2) exten => 08787XXXXX,n,Hangup() [outgoing] exten => _X.,1,Dial(sip/xs4all/${EXTEN},60,r) [internal] exten => 6004,1,Dial(sip/6004) exten => 6003,1,Dial(sip/6003) exten => 6005,1,Dial(DAHDI/2) exten => 6006,1,Answer() exten => 6006,n,Playback(hello-world) exten => 6006,n,Hangup() [phones] include => internal include => fromxs4all include => outgoing 833aab822d5085092b6894c343b6130667f410e0 2419 2418 2009-07-13T09:42:01Z Insomnia 3 /* sip.conf */ wikitext text/x-wiki = Asterisk basic configuration principles = In this section we'll have a look at the basic configuration of an Asterisk PBX. Contrary to the TFOT-book, we'll be looking at it from the theory side, and from there go to an example configuration. For this example configuration, we'll start from a server with on the "outside" a POTS line and a SIP account with an Internet provider, and on the "inside" two analogue telephones and a SIP softphone. Our goal is to let the PBX behave as if we don't even have a PBX, but a standard home situation: for an incoming call, all phones ring; and every internal phone can make calls to the outside. = Asterisk channel configuration basics = The first thing to realise is that Asterisk sees each connected telephony device as a "channel". But what is a Channel? To Asterisk, a channel is a connection which brings in a call to the Asterisk PBX. A channel could be a connection to an ordinary telephone handset or an ordinary telephone line, or to a logical call (like an Internet phone call). Asterisk makes no distinction between "FXO" and "FXS" style channels (that is, it doesn't distinguish between telephone lines and telephones). Every call is placed or received on a distinct channel. The second thing to realise, is that every type of device attached to the Asterisk PBX have their own specific configuration files. Correctly setting up each (set of) telephony devices makes them available in our Asterisk PBX as channels. Thus, the device configuration files serve as a kind of abstraction layer, and simplify our final Asterisk configuration by putting "channel-specific" information in separate files. If you've followed the previous Asterisk sections in this Wiki, or followed the first four chapters of the TFOT-book, then you've encountered the following configuration files: * ''zaptel.conf'' - in this file, you can set up the most basic parameters for your Zap-type hardware channels, most notably Digium telephony cards. You're configuring the hardware itself, via its driver. You could think of this file as belonging to the hardware, not Asterisk. If you'd have other software on your machine besides Asterisk that could make use of your telephony hardware, then that'd be influenced as well when you change ''zaptel.conf''. * ''zapata.conf'' (and possibly ''zapata-channels.conf'' if you're on Debian) - this file handles the Asterisk-specific configuration of the hardware telephony channels. It thus "sets up the Zap channels" that Asterisk sees - for incoming and outgoing calls. All parameters that set up the channel are specified here. * ''vpb.conf'' - this file is used to configure [http://www.voicetronix.com/ Voicetronix] cards with Asterisk. If you've a Voicetronix card in use, then you've also installed the Voicetronix drivers. This makes the card(s) useable under Linux. But to have Asterisk use the card(s), you need this ''vpb.conf'' file. It thus serves the same purpose as ''zapata.conf''. * ''sip.conf'' - this file contains all information on all SIP devices that we want to connect to our Asterisk server; be it one or more SIP accounts with Internet providers, or SIP capable telephones (hardware or software). When ''sip.conf'' has been set up correctly, we can refer to a SIP device by a friendly name like [1000] or [Jane]. * ''iax.conf'' - this file is just the same as the ''sip.conf'' file, only it handles devices that talk IAX2 protocol instead of the SIP protocol. These five files define all channels that our basic Asterisk PBX might handle (well, it won't even handle the last one, since we're not connecting any other Asterisk boxes or IAX-(soft)phones to our PBX, and it won't handle the third one if you don't have a Voicetronix card). As a reference, we're going to list the contents of four example files, and explain what they do in the way of preparing channels for our simple Asterisk server.: ==zaptel.conf== # Autogenerated by ./genzaptelconf -- do not hand edit # Zaptel Configuration File # # This file is parsed by the Zaptel Configurator, ztcfg # # It must be in the module loading order # Span 1: WCTDM/0 "Wildcard TDM410P Board 1" (MASTER) fxoks=1 fxoks=2 fxsks=3 # channel 4, WCTDM, no module. # Global data loadzone = nl defaultzone = nl This is a relatively simple file, configuring three Digium modules. As you can see, the ''genzaptelconf'' command has generated it for us. It belongs with a Digium TDM410P card, which has two FXS modules in positions 1 and 2, and one FXO module in position 3. The first two non-commented lines define the protocol that the FXS modules must "talk" with the attached devices, which "naturally" is the FXO protocol (yes, FXS talks FXO, and FXO talks FXS... a bit like electric current flowing from negative to positive. It's just a matter of definitions).<br> The third line defines that the FXO module talks FXS protocol.<br> The fourth line configures a set of indications to use for the defined channels. Since we're loading "nl", we're configuring Dutch dialtones etcetera for the channels.<br> Finally, the last line tell the server that any channel that does not have a zone assigned to it, should have the specified default zone configured - Dutch as well in this example.<br> With this simple file, the driver for our example card (''wctdm24xxp'', by the way) can set up the hardware just as we want it. Now to tell Asterisk how to use it... ==zapata-channels.conf== ; Autogenerated by ./genzaptelconf -- do not hand edit ; Zaptel Channels Configurations (zapata.conf) ; ; This is not intended to be a complete zapata.conf. Rather, it is intended ; to be #include-d by /etc/zapata.conf that will include the global settings ; ; Span 1: WCTDM/0 "Wildcard TDM410P Board 1" (MASTER) ;;; line="1 WCTDM/0/0" signalling=fxo_ks callerid="Channel 1" <6001> mailbox=6001 group=5 context=from-internal channel => 1 callerid= mailbox= group= context=default ;;; line="2 WCTDM/0/1" signalling=fxo_ks callerid="Channel 2" <6002> mailbox=6002 group=5 context=from-internal channel => 2 callerid= mailbox= group= context=default ;;; line="3 WCTDM/0/2" signalling=fxs_ks callerid=asreceived group=0 context=from-pstn channel => 3 context=default This second file is also auto-generated. It sets up three channels, associated with the three Digium hardware modules that we've configured with ''zaptel.conf''. Here, we also see how the channel numbers get assigned to the physical ports. The first module gets to be Zap channel 1 ('''Zap/1'''), the second '''Zap/2''' and so on. So if we would like our FXO module to be channel 1, and our FXS modules 2 and three, we could rotate the three channel numbers in this file. Probably we'd then also want to rotate the ''callerid''`s though... Furthermore, we don't think it's a good idea to assign channels to Zap devices in a different order than the devices are found in the system - meaning "stick with the default numbering as much as possible". Note that the way ''zapata-channels.conf'' is interpreted, means that any statement like ''signalling=fxs_ks'' actually ''sets'' the ''signalling'' parameter; when the ''channel => 1'' line is reached, then all preceding parameter assignments are applied to that particular channel. This also means that if you somewhere have set a channel to belong to context "foo", and then never set a context again, then every next channel also gets assigned to "foo". So remember: if you don't see a parameter being set with a specific channel, you CANNOT assume that it then has it's default value; if a preceding channel has set that parameter to value "bar", then for your specific channel, it is "bar" also. An interesting thing to see here is how ''genzaptelconf'' deals with the above concept. After defining each channel, it resets the most important parameters (a.o. the ones that should be unique with a channel) to empty or "default". This means that if you yourself are very meticulous, you could do without that safety net, and rewrite the above configuration file as: signalling=fxo_ks callerid="Channel 1" <6001> mailbox=6001 group=5 context=from-internal channel => 1 signalling=fxo_ks callerid="Channel 2" <6002> mailbox=6002 group=5 context=from-internal channel => 2 signalling=fxs_ks callerid=asreceived group=0 context=from-pstn channel => 3 Note: we like the thoroughnes of the ''genzaptelconf'' configuration, but we like the readability of the second file more. ==zapata.conf== [trunkgroups] [channels] switchtype=national rxwink=300 ; Atlas seems to use long (250ms) winks usecallerid=yes hidecallerid=no callwaiting=yes usecallingpres=yes callwaitingcallerid=yes threewaycalling=yes transfer=yes canpark=yes cancallforward=yes callreturn=yes echocancel=yes echocancelwhenbridged=yes rxgain=0.0 txgain=0.0 callgroup=1 pickupgroup=1 immediate=no #include zapata-channels.conf Under Debian, ==sip.conf== This is a sample configuration for VOIP with XS4ALL ;;/etc/asterisk/sip.conf;; [general] context=default externip=setyoureiphere dtfmmode=inband localnet=192.168.70.0/24 port=5060 bindaddr=0.0.0.0 disallow=all allow=alaw allow=ulaw registerattempts=0 defaultexpiry=7200 register => 08787XXXXX:PASSWORD@sip.xs4all.nl/08787XXXXX [xs4all] type=friend username=08787XXXXX fromuser=08787XXXXX fromdomain=sip.xs4all.nl secret=PASSWORD host=sip.xs4all.nl insecure=invite context=fromxs4all canreinvite=no dtmfmode=inband disallow=all allow=alaw allow=ulaw == DAHDI == From asterisk version 1.4 zaptel is renamed in DAHDI witch stands for Digium Asterisk Hardware Device Interface. If you installed the dahdi-tools (highly recommended) then you can configure you're hardware Conversion from zaptel /etc/zaptel.conf Becomes /etc/dahdi/system.conf /etc/asterisk/zapata.conf Becomes /etc/asterisk/chan_dahdi.conf Lets look at what we have #dahdi_tool This will give a overview of the hardware and if it is configured or not. It will all so show alarms on the hardware. Now lets configure the card. First edit /etc/dadi/genconf_parameters. This file is used with dahdi_genconf and will produce /etc/dahdi-system.conf *lc_country nl You can also set the echo cancelation here MG2 is default #dahdi_genconf #dahdi_cfg -vv DAHDI Tools Version - 2.2.0 DAHDI Version: 2.2.0.1 Echo Canceller(s): MG2 Configuration ====================== Channel map: Channel 01: FXO Kewlstart (Default) (Echo Canceler: mg2) (Slaves: 01) Channel 02: FXO Kewlstart (Default) (Echo Canceler: mg2) (Slaves: 02) 2 channels to configure. Setting echocan for channel 1 to mg2 Setting echocan for channel 2 to mg2 Check if the right module is loaded. #cat /etc/dahdi/modules You can configure the options of dahdi in /etc/asterisk/chan_dahdi.conf for example turn off the echo cancelation = Asterisk dialplans - contexts = A dial plan consists of a number of extensions. Each extensions consists of a number of priorities. Extensions are grouped in contexts. For each priority, an application is called. [context] exten => id, priority, command When Asterisk receives an incoming connection on a channel, Asterisk looks at the context defined for that channel for commands telling Asterisk what it should do. The context defines different sets of commands depending on what extension the user has dialed. For example, a context might provide one set of commands for what to do if the user dials "123", and another set of commands for what to do if the user dials "9", and another set of commands for what to do if the user dials any number beginning with "555". For some kinds of connections — such incoming calls from an outside telephone line — the user has not dialed an extension. In that case, Asterisk behaves as if the user had dialed a special extension named "s" (for Start). Asterisk will look for an extension "number" s in the definition of the context for that channel for instructions about what it should do to handle the call. Let's say, for example, that you have a channel "Zap/1" which is a connection to a telephone handset in your building. And let's say that in the configuration file for Zap channels (zapata.conf), you have defined context=john for Zap channel 1. So when you use that handset to dial a number, Asterisk looks for a context with the name "john" in extensions.conf to find out what it should do. You begin the definition of a context in extensions.conf by putting the name of the context in square brackets on a line by itself, like this: [john] == extensions.conf == [globals] [general] autofallthrough=yes [default] include => fromxs4all [fromxs4all] exten => 08787XXXXX,1,Dial(DAHDI/2) exten => 08787XXXXX,n,Hangup() [outgoing] exten => _X.,1,Dial(sip/xs4all/${EXTEN},60,r) [internal] exten => 6004,1,Dial(sip/6004) exten => 6003,1,Dial(sip/6003) exten => 6005,1,Dial(DAHDI/2) exten => 6006,1,Answer() exten => 6006,n,Playback(hello-world) exten => 6006,n,Hangup() [phones] include => internal include => fromxs4all include => outgoing a90ffc123dd8d2fd4495600d212e8a7d853209f3 2420 2419 2009-07-13T09:46:31Z Insomnia 3 /* DAHDI */ wikitext text/x-wiki = Asterisk basic configuration principles = In this section we'll have a look at the basic configuration of an Asterisk PBX. Contrary to the TFOT-book, we'll be looking at it from the theory side, and from there go to an example configuration. For this example configuration, we'll start from a server with on the "outside" a POTS line and a SIP account with an Internet provider, and on the "inside" two analogue telephones and a SIP softphone. Our goal is to let the PBX behave as if we don't even have a PBX, but a standard home situation: for an incoming call, all phones ring; and every internal phone can make calls to the outside. = Asterisk channel configuration basics = The first thing to realise is that Asterisk sees each connected telephony device as a "channel". But what is a Channel? To Asterisk, a channel is a connection which brings in a call to the Asterisk PBX. A channel could be a connection to an ordinary telephone handset or an ordinary telephone line, or to a logical call (like an Internet phone call). Asterisk makes no distinction between "FXO" and "FXS" style channels (that is, it doesn't distinguish between telephone lines and telephones). Every call is placed or received on a distinct channel. The second thing to realise, is that every type of device attached to the Asterisk PBX have their own specific configuration files. Correctly setting up each (set of) telephony devices makes them available in our Asterisk PBX as channels. Thus, the device configuration files serve as a kind of abstraction layer, and simplify our final Asterisk configuration by putting "channel-specific" information in separate files. If you've followed the previous Asterisk sections in this Wiki, or followed the first four chapters of the TFOT-book, then you've encountered the following configuration files: * ''zaptel.conf'' - in this file, you can set up the most basic parameters for your Zap-type hardware channels, most notably Digium telephony cards. You're configuring the hardware itself, via its driver. You could think of this file as belonging to the hardware, not Asterisk. If you'd have other software on your machine besides Asterisk that could make use of your telephony hardware, then that'd be influenced as well when you change ''zaptel.conf''. * ''zapata.conf'' (and possibly ''zapata-channels.conf'' if you're on Debian) - this file handles the Asterisk-specific configuration of the hardware telephony channels. It thus "sets up the Zap channels" that Asterisk sees - for incoming and outgoing calls. All parameters that set up the channel are specified here. * ''vpb.conf'' - this file is used to configure [http://www.voicetronix.com/ Voicetronix] cards with Asterisk. If you've a Voicetronix card in use, then you've also installed the Voicetronix drivers. This makes the card(s) useable under Linux. But to have Asterisk use the card(s), you need this ''vpb.conf'' file. It thus serves the same purpose as ''zapata.conf''. * ''sip.conf'' - this file contains all information on all SIP devices that we want to connect to our Asterisk server; be it one or more SIP accounts with Internet providers, or SIP capable telephones (hardware or software). When ''sip.conf'' has been set up correctly, we can refer to a SIP device by a friendly name like [1000] or [Jane]. * ''iax.conf'' - this file is just the same as the ''sip.conf'' file, only it handles devices that talk IAX2 protocol instead of the SIP protocol. These five files define all channels that our basic Asterisk PBX might handle (well, it won't even handle the last one, since we're not connecting any other Asterisk boxes or IAX-(soft)phones to our PBX, and it won't handle the third one if you don't have a Voicetronix card). As a reference, we're going to list the contents of four example files, and explain what they do in the way of preparing channels for our simple Asterisk server.: ==zaptel.conf== # Autogenerated by ./genzaptelconf -- do not hand edit # Zaptel Configuration File # # This file is parsed by the Zaptel Configurator, ztcfg # # It must be in the module loading order # Span 1: WCTDM/0 "Wildcard TDM410P Board 1" (MASTER) fxoks=1 fxoks=2 fxsks=3 # channel 4, WCTDM, no module. # Global data loadzone = nl defaultzone = nl This is a relatively simple file, configuring three Digium modules. As you can see, the ''genzaptelconf'' command has generated it for us. It belongs with a Digium TDM410P card, which has two FXS modules in positions 1 and 2, and one FXO module in position 3. The first two non-commented lines define the protocol that the FXS modules must "talk" with the attached devices, which "naturally" is the FXO protocol (yes, FXS talks FXO, and FXO talks FXS... a bit like electric current flowing from negative to positive. It's just a matter of definitions).<br> The third line defines that the FXO module talks FXS protocol.<br> The fourth line configures a set of indications to use for the defined channels. Since we're loading "nl", we're configuring Dutch dialtones etcetera for the channels.<br> Finally, the last line tell the server that any channel that does not have a zone assigned to it, should have the specified default zone configured - Dutch as well in this example.<br> With this simple file, the driver for our example card (''wctdm24xxp'', by the way) can set up the hardware just as we want it. Now to tell Asterisk how to use it... ==zapata-channels.conf== ; Autogenerated by ./genzaptelconf -- do not hand edit ; Zaptel Channels Configurations (zapata.conf) ; ; This is not intended to be a complete zapata.conf. Rather, it is intended ; to be #include-d by /etc/zapata.conf that will include the global settings ; ; Span 1: WCTDM/0 "Wildcard TDM410P Board 1" (MASTER) ;;; line="1 WCTDM/0/0" signalling=fxo_ks callerid="Channel 1" <6001> mailbox=6001 group=5 context=from-internal channel => 1 callerid= mailbox= group= context=default ;;; line="2 WCTDM/0/1" signalling=fxo_ks callerid="Channel 2" <6002> mailbox=6002 group=5 context=from-internal channel => 2 callerid= mailbox= group= context=default ;;; line="3 WCTDM/0/2" signalling=fxs_ks callerid=asreceived group=0 context=from-pstn channel => 3 context=default This second file is also auto-generated. It sets up three channels, associated with the three Digium hardware modules that we've configured with ''zaptel.conf''. Here, we also see how the channel numbers get assigned to the physical ports. The first module gets to be Zap channel 1 ('''Zap/1'''), the second '''Zap/2''' and so on. So if we would like our FXO module to be channel 1, and our FXS modules 2 and three, we could rotate the three channel numbers in this file. Probably we'd then also want to rotate the ''callerid''`s though... Furthermore, we don't think it's a good idea to assign channels to Zap devices in a different order than the devices are found in the system - meaning "stick with the default numbering as much as possible". Note that the way ''zapata-channels.conf'' is interpreted, means that any statement like ''signalling=fxs_ks'' actually ''sets'' the ''signalling'' parameter; when the ''channel => 1'' line is reached, then all preceding parameter assignments are applied to that particular channel. This also means that if you somewhere have set a channel to belong to context "foo", and then never set a context again, then every next channel also gets assigned to "foo". So remember: if you don't see a parameter being set with a specific channel, you CANNOT assume that it then has it's default value; if a preceding channel has set that parameter to value "bar", then for your specific channel, it is "bar" also. An interesting thing to see here is how ''genzaptelconf'' deals with the above concept. After defining each channel, it resets the most important parameters (a.o. the ones that should be unique with a channel) to empty or "default". This means that if you yourself are very meticulous, you could do without that safety net, and rewrite the above configuration file as: signalling=fxo_ks callerid="Channel 1" <6001> mailbox=6001 group=5 context=from-internal channel => 1 signalling=fxo_ks callerid="Channel 2" <6002> mailbox=6002 group=5 context=from-internal channel => 2 signalling=fxs_ks callerid=asreceived group=0 context=from-pstn channel => 3 Note: we like the thoroughnes of the ''genzaptelconf'' configuration, but we like the readability of the second file more. ==zapata.conf== [trunkgroups] [channels] switchtype=national rxwink=300 ; Atlas seems to use long (250ms) winks usecallerid=yes hidecallerid=no callwaiting=yes usecallingpres=yes callwaitingcallerid=yes threewaycalling=yes transfer=yes canpark=yes cancallforward=yes callreturn=yes echocancel=yes echocancelwhenbridged=yes rxgain=0.0 txgain=0.0 callgroup=1 pickupgroup=1 immediate=no #include zapata-channels.conf Under Debian, ==sip.conf== This is a sample configuration for VOIP with XS4ALL ;;/etc/asterisk/sip.conf;; [general] context=default externip=setyoureiphere dtfmmode=inband localnet=192.168.70.0/24 port=5060 bindaddr=0.0.0.0 disallow=all allow=alaw allow=ulaw registerattempts=0 defaultexpiry=7200 register => 08787XXXXX:PASSWORD@sip.xs4all.nl/08787XXXXX [xs4all] type=friend username=08787XXXXX fromuser=08787XXXXX fromdomain=sip.xs4all.nl secret=PASSWORD host=sip.xs4all.nl insecure=invite context=fromxs4all canreinvite=no dtmfmode=inband disallow=all allow=alaw allow=ulaw == DAHDI == From asterisk version 1.4 zaptel is renamed in DAHDI witch stands for Digium Asterisk Hardware Device Interface. If you installed the dahdi-tools (highly recommended) then you can configure you're hardware Conversion from zaptel /etc/zaptel.conf Becomes /etc/dahdi/system.conf /etc/asterisk/zapata.conf Becomes /etc/asterisk/chan_dahdi.conf Lets look at what we have #dahdi_tool This will give a overview of the hardware and if it is configured or not. It will all so show alarms on the hardware. Now lets configure the card. First edit /etc/dadi/genconf_parameters. This file is used with dahdi_genconf and will produce /etc/dahdi-system.conf *lc_country nl You can also set the echo cancelation here MG2 is default #dahdi_genconf #dahdi_cfg -vv DAHDI Tools Version - 2.2.0 DAHDI Version: 2.2.0.1 Echo Canceller(s): MG2 Configuration ====================== Channel map: Channel 01: FXO Kewlstart (Default) (Echo Canceler: mg2) (Slaves: 01) Channel 02: FXO Kewlstart (Default) (Echo Canceler: mg2) (Slaves: 02) 2 channels to configure. Setting echocan for channel 1 to mg2 Setting echocan for channel 2 to mg2 Check if the right module is loaded. #cat /etc/dahdi/modules You can configure the options of dahdi in /etc/asterisk/chan_dahdi.conf for example turn off the echo cancelation You can also check teh channels in asterisk #asterisk -r #server*CLI> dahdi show channels Or set the verbose level on asterisk to see more output #server*CLI> core set verbose 10 = Asterisk dialplans - contexts = A dial plan consists of a number of extensions. Each extensions consists of a number of priorities. Extensions are grouped in contexts. For each priority, an application is called. [context] exten => id, priority, command When Asterisk receives an incoming connection on a channel, Asterisk looks at the context defined for that channel for commands telling Asterisk what it should do. The context defines different sets of commands depending on what extension the user has dialed. For example, a context might provide one set of commands for what to do if the user dials "123", and another set of commands for what to do if the user dials "9", and another set of commands for what to do if the user dials any number beginning with "555". For some kinds of connections — such incoming calls from an outside telephone line — the user has not dialed an extension. In that case, Asterisk behaves as if the user had dialed a special extension named "s" (for Start). Asterisk will look for an extension "number" s in the definition of the context for that channel for instructions about what it should do to handle the call. Let's say, for example, that you have a channel "Zap/1" which is a connection to a telephone handset in your building. And let's say that in the configuration file for Zap channels (zapata.conf), you have defined context=john for Zap channel 1. So when you use that handset to dial a number, Asterisk looks for a context with the name "john" in extensions.conf to find out what it should do. You begin the definition of a context in extensions.conf by putting the name of the context in square brackets on a line by itself, like this: [john] == extensions.conf == [globals] [general] autofallthrough=yes [default] include => fromxs4all [fromxs4all] exten => 08787XXXXX,1,Dial(DAHDI/2) exten => 08787XXXXX,n,Hangup() [outgoing] exten => _X.,1,Dial(sip/xs4all/${EXTEN},60,r) [internal] exten => 6004,1,Dial(sip/6004) exten => 6003,1,Dial(sip/6003) exten => 6005,1,Dial(DAHDI/2) exten => 6006,1,Answer() exten => 6006,n,Playback(hello-world) exten => 6006,n,Hangup() [phones] include => internal include => fromxs4all include => outgoing 0d40ce3af24c160fea07435fd11f60a4e871f8f7 2421 2420 2009-07-13T17:07:40Z 82.161.20.132 0 /* DAHDI */ Problem solving wikitext text/x-wiki = Asterisk basic configuration principles = In this section we'll have a look at the basic configuration of an Asterisk PBX. Contrary to the TFOT-book, we'll be looking at it from the theory side, and from there go to an example configuration. For this example configuration, we'll start from a server with on the "outside" a POTS line and a SIP account with an Internet provider, and on the "inside" two analogue telephones and a SIP softphone. Our goal is to let the PBX behave as if we don't even have a PBX, but a standard home situation: for an incoming call, all phones ring; and every internal phone can make calls to the outside. = Asterisk channel configuration basics = The first thing to realise is that Asterisk sees each connected telephony device as a "channel". But what is a Channel? To Asterisk, a channel is a connection which brings in a call to the Asterisk PBX. A channel could be a connection to an ordinary telephone handset or an ordinary telephone line, or to a logical call (like an Internet phone call). Asterisk makes no distinction between "FXO" and "FXS" style channels (that is, it doesn't distinguish between telephone lines and telephones). Every call is placed or received on a distinct channel. The second thing to realise, is that every type of device attached to the Asterisk PBX have their own specific configuration files. Correctly setting up each (set of) telephony devices makes them available in our Asterisk PBX as channels. Thus, the device configuration files serve as a kind of abstraction layer, and simplify our final Asterisk configuration by putting "channel-specific" information in separate files. If you've followed the previous Asterisk sections in this Wiki, or followed the first four chapters of the TFOT-book, then you've encountered the following configuration files: * ''zaptel.conf'' - in this file, you can set up the most basic parameters for your Zap-type hardware channels, most notably Digium telephony cards. You're configuring the hardware itself, via its driver. You could think of this file as belonging to the hardware, not Asterisk. If you'd have other software on your machine besides Asterisk that could make use of your telephony hardware, then that'd be influenced as well when you change ''zaptel.conf''. * ''zapata.conf'' (and possibly ''zapata-channels.conf'' if you're on Debian) - this file handles the Asterisk-specific configuration of the hardware telephony channels. It thus "sets up the Zap channels" that Asterisk sees - for incoming and outgoing calls. All parameters that set up the channel are specified here. * ''vpb.conf'' - this file is used to configure [http://www.voicetronix.com/ Voicetronix] cards with Asterisk. If you've a Voicetronix card in use, then you've also installed the Voicetronix drivers. This makes the card(s) useable under Linux. But to have Asterisk use the card(s), you need this ''vpb.conf'' file. It thus serves the same purpose as ''zapata.conf''. * ''sip.conf'' - this file contains all information on all SIP devices that we want to connect to our Asterisk server; be it one or more SIP accounts with Internet providers, or SIP capable telephones (hardware or software). When ''sip.conf'' has been set up correctly, we can refer to a SIP device by a friendly name like [1000] or [Jane]. * ''iax.conf'' - this file is just the same as the ''sip.conf'' file, only it handles devices that talk IAX2 protocol instead of the SIP protocol. These five files define all channels that our basic Asterisk PBX might handle (well, it won't even handle the last one, since we're not connecting any other Asterisk boxes or IAX-(soft)phones to our PBX, and it won't handle the third one if you don't have a Voicetronix card). As a reference, we're going to list the contents of four example files, and explain what they do in the way of preparing channels for our simple Asterisk server.: ==zaptel.conf== # Autogenerated by ./genzaptelconf -- do not hand edit # Zaptel Configuration File # # This file is parsed by the Zaptel Configurator, ztcfg # # It must be in the module loading order # Span 1: WCTDM/0 "Wildcard TDM410P Board 1" (MASTER) fxoks=1 fxoks=2 fxsks=3 # channel 4, WCTDM, no module. # Global data loadzone = nl defaultzone = nl This is a relatively simple file, configuring three Digium modules. As you can see, the ''genzaptelconf'' command has generated it for us. It belongs with a Digium TDM410P card, which has two FXS modules in positions 1 and 2, and one FXO module in position 3. The first two non-commented lines define the protocol that the FXS modules must "talk" with the attached devices, which "naturally" is the FXO protocol (yes, FXS talks FXO, and FXO talks FXS... a bit like electric current flowing from negative to positive. It's just a matter of definitions).<br> The third line defines that the FXO module talks FXS protocol.<br> The fourth line configures a set of indications to use for the defined channels. Since we're loading "nl", we're configuring Dutch dialtones etcetera for the channels.<br> Finally, the last line tell the server that any channel that does not have a zone assigned to it, should have the specified default zone configured - Dutch as well in this example.<br> With this simple file, the driver for our example card (''wctdm24xxp'', by the way) can set up the hardware just as we want it. Now to tell Asterisk how to use it... ==zapata-channels.conf== ; Autogenerated by ./genzaptelconf -- do not hand edit ; Zaptel Channels Configurations (zapata.conf) ; ; This is not intended to be a complete zapata.conf. Rather, it is intended ; to be #include-d by /etc/zapata.conf that will include the global settings ; ; Span 1: WCTDM/0 "Wildcard TDM410P Board 1" (MASTER) ;;; line="1 WCTDM/0/0" signalling=fxo_ks callerid="Channel 1" <6001> mailbox=6001 group=5 context=from-internal channel => 1 callerid= mailbox= group= context=default ;;; line="2 WCTDM/0/1" signalling=fxo_ks callerid="Channel 2" <6002> mailbox=6002 group=5 context=from-internal channel => 2 callerid= mailbox= group= context=default ;;; line="3 WCTDM/0/2" signalling=fxs_ks callerid=asreceived group=0 context=from-pstn channel => 3 context=default This second file is also auto-generated. It sets up three channels, associated with the three Digium hardware modules that we've configured with ''zaptel.conf''. Here, we also see how the channel numbers get assigned to the physical ports. The first module gets to be Zap channel 1 ('''Zap/1'''), the second '''Zap/2''' and so on. So if we would like our FXO module to be channel 1, and our FXS modules 2 and three, we could rotate the three channel numbers in this file. Probably we'd then also want to rotate the ''callerid''`s though... Furthermore, we don't think it's a good idea to assign channels to Zap devices in a different order than the devices are found in the system - meaning "stick with the default numbering as much as possible". Note that the way ''zapata-channels.conf'' is interpreted, means that any statement like ''signalling=fxs_ks'' actually ''sets'' the ''signalling'' parameter; when the ''channel => 1'' line is reached, then all preceding parameter assignments are applied to that particular channel. This also means that if you somewhere have set a channel to belong to context "foo", and then never set a context again, then every next channel also gets assigned to "foo". So remember: if you don't see a parameter being set with a specific channel, you CANNOT assume that it then has it's default value; if a preceding channel has set that parameter to value "bar", then for your specific channel, it is "bar" also. An interesting thing to see here is how ''genzaptelconf'' deals with the above concept. After defining each channel, it resets the most important parameters (a.o. the ones that should be unique with a channel) to empty or "default". This means that if you yourself are very meticulous, you could do without that safety net, and rewrite the above configuration file as: signalling=fxo_ks callerid="Channel 1" <6001> mailbox=6001 group=5 context=from-internal channel => 1 signalling=fxo_ks callerid="Channel 2" <6002> mailbox=6002 group=5 context=from-internal channel => 2 signalling=fxs_ks callerid=asreceived group=0 context=from-pstn channel => 3 Note: we like the thoroughnes of the ''genzaptelconf'' configuration, but we like the readability of the second file more. ==zapata.conf== [trunkgroups] [channels] switchtype=national rxwink=300 ; Atlas seems to use long (250ms) winks usecallerid=yes hidecallerid=no callwaiting=yes usecallingpres=yes callwaitingcallerid=yes threewaycalling=yes transfer=yes canpark=yes cancallforward=yes callreturn=yes echocancel=yes echocancelwhenbridged=yes rxgain=0.0 txgain=0.0 callgroup=1 pickupgroup=1 immediate=no #include zapata-channels.conf Under Debian, ==sip.conf== This is a sample configuration for VOIP with XS4ALL ;;/etc/asterisk/sip.conf;; [general] context=default externip=setyoureiphere dtfmmode=inband localnet=192.168.70.0/24 port=5060 bindaddr=0.0.0.0 disallow=all allow=alaw allow=ulaw registerattempts=0 defaultexpiry=7200 register => 08787XXXXX:PASSWORD@sip.xs4all.nl/08787XXXXX [xs4all] type=friend username=08787XXXXX fromuser=08787XXXXX fromdomain=sip.xs4all.nl secret=PASSWORD host=sip.xs4all.nl insecure=invite context=fromxs4all canreinvite=no dtmfmode=inband disallow=all allow=alaw allow=ulaw == DAHDI == From asterisk version 1.4 zaptel is renamed in DAHDI witch stands for Digium Asterisk Hardware Device Interface. If you installed the dahdi-tools (highly recommended) then you can configure you're hardware Conversion from zaptel /etc/zaptel.conf Becomes /etc/dahdi/system.conf /etc/asterisk/zapata.conf Becomes /etc/asterisk/chan_dahdi.conf Lets look at what we have #dahdi_tool This will give a overview of the hardware and if it is configured or not. It will all so show alarms on the hardware. Now lets configure the card. First edit /etc/dadi/genconf_parameters. This file is used with dahdi_genconf and will produce /etc/dahdi-system.conf *lc_country nl You can also set the echo cancelation here MG2 is default #dahdi_genconf #dahdi_cfg -vv DAHDI Tools Version - 2.2.0 DAHDI Version: 2.2.0.1 Echo Canceller(s): MG2 Configuration ====================== Channel map: Channel 01: FXO Kewlstart (Default) (Echo Canceler: mg2) (Slaves: 01) Channel 02: FXO Kewlstart (Default) (Echo Canceler: mg2) (Slaves: 02) 2 channels to configure. Setting echocan for channel 1 to mg2 Setting echocan for channel 2 to mg2 Check if the right module is loaded. #cat /etc/dahdi/modules You can configure the options of dahdi in /etc/asterisk/chan_dahdi.conf for example turn off the echo cancelation You can also check teh channels in asterisk #asterisk -r #server*CLI> dahdi show channels Or set the verbose level on asterisk to see more output #server*CLI> core set verbose 10 I had some trouble with the sounds. When asterisk plays hello-world.gsm it sounded stutterd. I did a #dahdi_test This gives a readout from the timinsettings in asterisk. Mine was -133% and it should give a reading close to 100%.I did a #dahdi destroy channel 1 #dahdi destroy channel 2 #dahdi restart Now i have 2 channels and no Pseudo channel (not shure were it's for) Dahdi_test gives me 99,6% and the spound is good = Asterisk dialplans - contexts = A dial plan consists of a number of extensions. Each extensions consists of a number of priorities. Extensions are grouped in contexts. For each priority, an application is called. [context] exten => id, priority, command When Asterisk receives an incoming connection on a channel, Asterisk looks at the context defined for that channel for commands telling Asterisk what it should do. The context defines different sets of commands depending on what extension the user has dialed. For example, a context might provide one set of commands for what to do if the user dials "123", and another set of commands for what to do if the user dials "9", and another set of commands for what to do if the user dials any number beginning with "555". For some kinds of connections — such incoming calls from an outside telephone line — the user has not dialed an extension. In that case, Asterisk behaves as if the user had dialed a special extension named "s" (for Start). Asterisk will look for an extension "number" s in the definition of the context for that channel for instructions about what it should do to handle the call. Let's say, for example, that you have a channel "Zap/1" which is a connection to a telephone handset in your building. And let's say that in the configuration file for Zap channels (zapata.conf), you have defined context=john for Zap channel 1. So when you use that handset to dial a number, Asterisk looks for a context with the name "john" in extensions.conf to find out what it should do. You begin the definition of a context in extensions.conf by putting the name of the context in square brackets on a line by itself, like this: [john] == extensions.conf == [globals] [general] autofallthrough=yes [default] include => fromxs4all [fromxs4all] exten => 08787XXXXX,1,Dial(DAHDI/2) exten => 08787XXXXX,n,Hangup() [outgoing] exten => _X.,1,Dial(sip/xs4all/${EXTEN},60,r) [internal] exten => 6004,1,Dial(sip/6004) exten => 6003,1,Dial(sip/6003) exten => 6005,1,Dial(DAHDI/2) exten => 6006,1,Answer() exten => 6006,n,Playback(hello-world) exten => 6006,n,Hangup() [phones] include => internal include => fromxs4all include => outgoing 09a2518eac9fde08dd5c7624bdda666122790e07 2441 2421 2009-08-25T21:25:06Z Insomnia 3 /* DAHDI */ wikitext text/x-wiki = Asterisk basic configuration principles = In this section we'll have a look at the basic configuration of an Asterisk PBX. Contrary to the TFOT-book, we'll be looking at it from the theory side, and from there go to an example configuration. For this example configuration, we'll start from a server with on the "outside" a POTS line and a SIP account with an Internet provider, and on the "inside" two analogue telephones and a SIP softphone. Our goal is to let the PBX behave as if we don't even have a PBX, but a standard home situation: for an incoming call, all phones ring; and every internal phone can make calls to the outside. = Asterisk channel configuration basics = The first thing to realise is that Asterisk sees each connected telephony device as a "channel". But what is a Channel? To Asterisk, a channel is a connection which brings in a call to the Asterisk PBX. A channel could be a connection to an ordinary telephone handset or an ordinary telephone line, or to a logical call (like an Internet phone call). Asterisk makes no distinction between "FXO" and "FXS" style channels (that is, it doesn't distinguish between telephone lines and telephones). Every call is placed or received on a distinct channel. The second thing to realise, is that every type of device attached to the Asterisk PBX have their own specific configuration files. Correctly setting up each (set of) telephony devices makes them available in our Asterisk PBX as channels. Thus, the device configuration files serve as a kind of abstraction layer, and simplify our final Asterisk configuration by putting "channel-specific" information in separate files. If you've followed the previous Asterisk sections in this Wiki, or followed the first four chapters of the TFOT-book, then you've encountered the following configuration files: * ''zaptel.conf'' - in this file, you can set up the most basic parameters for your Zap-type hardware channels, most notably Digium telephony cards. You're configuring the hardware itself, via its driver. You could think of this file as belonging to the hardware, not Asterisk. If you'd have other software on your machine besides Asterisk that could make use of your telephony hardware, then that'd be influenced as well when you change ''zaptel.conf''. * ''zapata.conf'' (and possibly ''zapata-channels.conf'' if you're on Debian) - this file handles the Asterisk-specific configuration of the hardware telephony channels. It thus "sets up the Zap channels" that Asterisk sees - for incoming and outgoing calls. All parameters that set up the channel are specified here. * ''vpb.conf'' - this file is used to configure [http://www.voicetronix.com/ Voicetronix] cards with Asterisk. If you've a Voicetronix card in use, then you've also installed the Voicetronix drivers. This makes the card(s) useable under Linux. But to have Asterisk use the card(s), you need this ''vpb.conf'' file. It thus serves the same purpose as ''zapata.conf''. * ''sip.conf'' - this file contains all information on all SIP devices that we want to connect to our Asterisk server; be it one or more SIP accounts with Internet providers, or SIP capable telephones (hardware or software). When ''sip.conf'' has been set up correctly, we can refer to a SIP device by a friendly name like [1000] or [Jane]. * ''iax.conf'' - this file is just the same as the ''sip.conf'' file, only it handles devices that talk IAX2 protocol instead of the SIP protocol. These five files define all channels that our basic Asterisk PBX might handle (well, it won't even handle the last one, since we're not connecting any other Asterisk boxes or IAX-(soft)phones to our PBX, and it won't handle the third one if you don't have a Voicetronix card). As a reference, we're going to list the contents of four example files, and explain what they do in the way of preparing channels for our simple Asterisk server.: ==zaptel.conf== # Autogenerated by ./genzaptelconf -- do not hand edit # Zaptel Configuration File # # This file is parsed by the Zaptel Configurator, ztcfg # # It must be in the module loading order # Span 1: WCTDM/0 "Wildcard TDM410P Board 1" (MASTER) fxoks=1 fxoks=2 fxsks=3 # channel 4, WCTDM, no module. # Global data loadzone = nl defaultzone = nl This is a relatively simple file, configuring three Digium modules. As you can see, the ''genzaptelconf'' command has generated it for us. It belongs with a Digium TDM410P card, which has two FXS modules in positions 1 and 2, and one FXO module in position 3. The first two non-commented lines define the protocol that the FXS modules must "talk" with the attached devices, which "naturally" is the FXO protocol (yes, FXS talks FXO, and FXO talks FXS... a bit like electric current flowing from negative to positive. It's just a matter of definitions).<br> The third line defines that the FXO module talks FXS protocol.<br> The fourth line configures a set of indications to use for the defined channels. Since we're loading "nl", we're configuring Dutch dialtones etcetera for the channels.<br> Finally, the last line tell the server that any channel that does not have a zone assigned to it, should have the specified default zone configured - Dutch as well in this example.<br> With this simple file, the driver for our example card (''wctdm24xxp'', by the way) can set up the hardware just as we want it. Now to tell Asterisk how to use it... ==zapata-channels.conf== ; Autogenerated by ./genzaptelconf -- do not hand edit ; Zaptel Channels Configurations (zapata.conf) ; ; This is not intended to be a complete zapata.conf. Rather, it is intended ; to be #include-d by /etc/zapata.conf that will include the global settings ; ; Span 1: WCTDM/0 "Wildcard TDM410P Board 1" (MASTER) ;;; line="1 WCTDM/0/0" signalling=fxo_ks callerid="Channel 1" <6001> mailbox=6001 group=5 context=from-internal channel => 1 callerid= mailbox= group= context=default ;;; line="2 WCTDM/0/1" signalling=fxo_ks callerid="Channel 2" <6002> mailbox=6002 group=5 context=from-internal channel => 2 callerid= mailbox= group= context=default ;;; line="3 WCTDM/0/2" signalling=fxs_ks callerid=asreceived group=0 context=from-pstn channel => 3 context=default This second file is also auto-generated. It sets up three channels, associated with the three Digium hardware modules that we've configured with ''zaptel.conf''. Here, we also see how the channel numbers get assigned to the physical ports. The first module gets to be Zap channel 1 ('''Zap/1'''), the second '''Zap/2''' and so on. So if we would like our FXO module to be channel 1, and our FXS modules 2 and three, we could rotate the three channel numbers in this file. Probably we'd then also want to rotate the ''callerid''`s though... Furthermore, we don't think it's a good idea to assign channels to Zap devices in a different order than the devices are found in the system - meaning "stick with the default numbering as much as possible". Note that the way ''zapata-channels.conf'' is interpreted, means that any statement like ''signalling=fxs_ks'' actually ''sets'' the ''signalling'' parameter; when the ''channel => 1'' line is reached, then all preceding parameter assignments are applied to that particular channel. This also means that if you somewhere have set a channel to belong to context "foo", and then never set a context again, then every next channel also gets assigned to "foo". So remember: if you don't see a parameter being set with a specific channel, you CANNOT assume that it then has it's default value; if a preceding channel has set that parameter to value "bar", then for your specific channel, it is "bar" also. An interesting thing to see here is how ''genzaptelconf'' deals with the above concept. After defining each channel, it resets the most important parameters (a.o. the ones that should be unique with a channel) to empty or "default". This means that if you yourself are very meticulous, you could do without that safety net, and rewrite the above configuration file as: signalling=fxo_ks callerid="Channel 1" <6001> mailbox=6001 group=5 context=from-internal channel => 1 signalling=fxo_ks callerid="Channel 2" <6002> mailbox=6002 group=5 context=from-internal channel => 2 signalling=fxs_ks callerid=asreceived group=0 context=from-pstn channel => 3 Note: we like the thoroughnes of the ''genzaptelconf'' configuration, but we like the readability of the second file more. ==zapata.conf== [trunkgroups] [channels] switchtype=national rxwink=300 ; Atlas seems to use long (250ms) winks usecallerid=yes hidecallerid=no callwaiting=yes usecallingpres=yes callwaitingcallerid=yes threewaycalling=yes transfer=yes canpark=yes cancallforward=yes callreturn=yes echocancel=yes echocancelwhenbridged=yes rxgain=0.0 txgain=0.0 callgroup=1 pickupgroup=1 immediate=no #include zapata-channels.conf Under Debian, ==sip.conf== This is a sample configuration for VOIP with XS4ALL ;;/etc/asterisk/sip.conf;; [general] context=default externip=setyoureiphere dtfmmode=inband localnet=192.168.70.0/24 port=5060 bindaddr=0.0.0.0 disallow=all allow=alaw allow=ulaw registerattempts=0 defaultexpiry=7200 register => 08787XXXXX:PASSWORD@sip.xs4all.nl/08787XXXXX [xs4all] type=friend username=08787XXXXX fromuser=08787XXXXX fromdomain=sip.xs4all.nl secret=PASSWORD host=sip.xs4all.nl insecure=invite context=fromxs4all canreinvite=no dtmfmode=inband disallow=all allow=alaw allow=ulaw == DAHDI == From asterisk version 1.4 zaptel is renamed in DAHDI witch stands for Digium Asterisk Hardware Device Interface. If you installed the dahdi-tools (highly recommended) then you can configure you're hardware Conversion from zaptel /etc/zaptel.conf Becomes /etc/dahdi/system.conf /etc/asterisk/zapata.conf Becomes /etc/asterisk/chan_dahdi.conf Lets look at what we have #dahdi_tool This will give a overview of the hardware and if it is configured or not. It will all so show alarms on the hardware. Now lets configure the card. First edit /etc/dadi/genconf_parameters. This file is used with dahdi_genconf and will produce /etc/dahdi-system.conf *lc_country nl You can also set the echo cancelation here MG2 is default #dahdi_genconf #dahdi_cfg -vv DAHDI Tools Version - 2.2.0 DAHDI Version: 2.2.0.1 Echo Canceller(s): MG2 Configuration ====================== Channel map: Channel 01: FXO Kewlstart (Default) (Echo Canceler: mg2) (Slaves: 01) Channel 02: FXO Kewlstart (Default) (Echo Canceler: mg2) (Slaves: 02) 2 channels to configure. Setting echocan for channel 1 to mg2 Setting echocan for channel 2 to mg2 Check if the right module is loaded. #cat /etc/dahdi/modules You can configure the options of dahdi in /etc/asterisk/chan_dahdi.conf for example turn off the echo cancelation Also include this line #include dahdi-channels.conf in your chan_dahdi.conf (yes with the #) Otherwise you're asterisk will not see the channels. You can also check the channels in asterisk #asterisk -r #server*CLI> dahdi show channels Or set the verbose level on asterisk to see more output #server*CLI> core set verbose 10 I had some trouble with the sounds. When asterisk plays hello-world.gsm it sounded stutterd. I did a #dahdi_test This gives a readout from the timinsettings in asterisk. Mine was -133% and it should give a reading close to 100%.I did a #dahdi destroy channel 1 #dahdi destroy channel 2 #dahdi restart Now i have 2 channels and no Pseudo channel (not shure were it's for) Dahdi_test gives me 99,6% and the spound is good = Asterisk dialplans - contexts = A dial plan consists of a number of extensions. Each extensions consists of a number of priorities. Extensions are grouped in contexts. For each priority, an application is called. [context] exten => id, priority, command When Asterisk receives an incoming connection on a channel, Asterisk looks at the context defined for that channel for commands telling Asterisk what it should do. The context defines different sets of commands depending on what extension the user has dialed. For example, a context might provide one set of commands for what to do if the user dials "123", and another set of commands for what to do if the user dials "9", and another set of commands for what to do if the user dials any number beginning with "555". For some kinds of connections — such incoming calls from an outside telephone line — the user has not dialed an extension. In that case, Asterisk behaves as if the user had dialed a special extension named "s" (for Start). Asterisk will look for an extension "number" s in the definition of the context for that channel for instructions about what it should do to handle the call. Let's say, for example, that you have a channel "Zap/1" which is a connection to a telephone handset in your building. And let's say that in the configuration file for Zap channels (zapata.conf), you have defined context=john for Zap channel 1. So when you use that handset to dial a number, Asterisk looks for a context with the name "john" in extensions.conf to find out what it should do. You begin the definition of a context in extensions.conf by putting the name of the context in square brackets on a line by itself, like this: [john] == extensions.conf == [globals] [general] autofallthrough=yes [default] include => fromxs4all [fromxs4all] exten => 08787XXXXX,1,Dial(DAHDI/2) exten => 08787XXXXX,n,Hangup() [outgoing] exten => _X.,1,Dial(sip/xs4all/${EXTEN},60,r) [internal] exten => 6004,1,Dial(sip/6004) exten => 6003,1,Dial(sip/6003) exten => 6005,1,Dial(DAHDI/2) exten => 6006,1,Answer() exten => 6006,n,Playback(hello-world) exten => 6006,n,Hangup() [phones] include => internal include => fromxs4all include => outgoing 857ec7a5cfdf1d8210da6014058e75e1160357c8 0 1458 2416 1586 2009-07-13T08:30:07Z Insomnia 3 Compile asterisk wikitext text/x-wiki Asterisk installation on Lenny can be performed with ease using Aptitude. This brings you Asterisk version 1.4.20. Since this has a graphical GUI manager, it might be wise to add X to your server. = Compile Asterisk = You can also compile asterisk and use the latest version. Get the latest version from http://www.asterisk.org/downloads #cd /usr/src Get asterisk version 1.6.1.1 wget http://downloads.asterisk.org/pub/telephony/asterisk/releases/asterisk-1.6.1.1.tar.gz Get the DAHDI linux drivers wget http://downloads.asterisk.org/pub/telephony/dahdi-linux/releases/dahdi-linux-2.2.0.1.tar.gz Get the DAHDI linux tools wget http://downloads.asterisk.org/pub/telephony/dahdi-tools/releases/dahdi-tools-2.2.0.tar.gz Get the ISDN drivers (not sure if its still needed even if you don't have ISDN) wget http://downloads.asterisk.org/pub/telephony/libpri/releases/libpri-1.4.10.1.tar.gz Get the Addon wget http://downloads.asterisk.org/pub/telephony/asterisk/releases/asterisk-addons-1.6.1.0.tar.gz Unpack all the tarballs Go to the asterisk 1.6.1.1 folder and launch the install script #./install.pl Go to the asterisk 1.6.1.1 folder and launch the install script #./install.pl 0051016b7bef0196bab298f7090fc0f179728c36 2422 2416 2009-07-14T20:47:56Z Insomnia 3 /* Compile Asterisk */ wikitext text/x-wiki Asterisk installation on Lenny can be performed with ease using Aptitude. This brings you Asterisk version 1.4.20. Since this has a graphical GUI manager, it might be wise to add X to your server. = Compile Asterisk = If you have a previous version of asterik first Backup config files /ets/asterisk and then uninstall it. From the original source files #make uninstall-all Get the latest version from http://www.asterisk.org/downloads #cd /usr/src Get asterisk version 1.6.1.1 wget http://downloads.asterisk.org/pub/telephony/asterisk/releases/asterisk-1.6.1.1.tar.gz Get the DAHDI linux drivers wget http://downloads.asterisk.org/pub/telephony/dahdi-linux/releases/dahdi-linux-2.2.0.1.tar.gz Get the DAHDI linux tools wget http://downloads.asterisk.org/pub/telephony/dahdi-tools/releases/dahdi-tools-2.2.0.tar.gz Get the ISDN drivers (not sure if its still needed even if you don't have ISDN) wget http://downloads.asterisk.org/pub/telephony/libpri/releases/libpri-1.4.10.1.tar.gz Get the Addon wget http://downloads.asterisk.org/pub/telephony/asterisk/releases/asterisk-addons-1.6.1.0.tar.gz Unpack all the tarballs Go to the asterisk 1.6.1.1 folder and launch the install script #./install.pl # ./configure #make menuselect #make install #make #make install #make samples #make config +---- Asterisk Installation Complete -------+ + + + YOU MUST READ THE SECURITY DOCUMENT + + + + Asterisk has successfully been installed. + + If you would like to install the sample + + configuration files (overwriting any + + existing config files), run: + + + + make samples + + + +----------------- or ---------------------+ + + + You can go ahead and install the asterisk + + program documentation now or later run: + + + + make progdocs + + + + **Note** This requires that you have + + doxygen installed on your local system + Go to the dahdi folder # make install ################################################### ### ### DAHDI installed successfully. ### If you have not done so before, install the package ### dahdi-tools. ### Go to dahdi-tools First run the configure script or you get a error "no rule to make target 'makeopts'" #./configure # make install ################################################### ### ### DAHDI tools installed successfully. ### If you have not done so before, install init scripts with: ### ### make config ### ################################################### Go to the DAHDI tools folder # make config install -D dahdi.init /etc/init.d/dahdi /usr/bin/install -c -D -m 644 init.conf.sample /etc/dahdi/init.conf /usr/bin/install -c -D -m 644 modules.sample /etc/dahdi/modules /usr/bin/install -c -D -m 644 xpp/genconf_parameters /etc/dahdi/genconf_parameters /usr/bin/install -c -D -m 644 modprobe.conf.sample /etc/modprobe.d/dahdi /usr/bin/install -c -D -m 644 blacklist.sample /etc/modprobe.d/dahdi.blacklist /usr/sbin/update-rc.d dahdi defaults 15 30 Adding system startup for /etc/init.d/dahdi ... /etc/rc0.d/K30dahdi -> ../init.d/dahdi /etc/rc1.d/K30dahdi -> ../init.d/dahdi /etc/rc6.d/K30dahdi -> ../init.d/dahdi /etc/rc2.d/S15dahdi -> ../init.d/dahdi /etc/rc3.d/S15dahdi -> ../init.d/dahdi /etc/rc4.d/S15dahdi -> ../init.d/dahdi /etc/rc5.d/S15dahdi -> ../init.d/dahdi DAHDI has been configured. List of detected DAHDI devices: pci:0000:04:05.0 wctdm24xxp+ d161:8005 Wildcard TDM410P run 'dahdi_genconf modules' to load support for only the DAHDI hardware installed in this system. By default support for all DAHDI hardware is loaded at DAHDI start. darktower:/usr/src/dahdi-tools-2.2.0# e66eb23c56adc74c4a7cc2f4b39b6916f5a0d808 2437 2422 2009-08-19T13:46:22Z Insomnia 3 /* Compile Asterisk */ wikitext text/x-wiki Asterisk installation on Lenny can be performed with ease using Aptitude. This brings you Asterisk version 1.4.20. Since this has a graphical GUI manager, it might be wise to add X to your server. = Compile Asterisk = If you have a previous version of asterik first Backup config files /ets/asterisk and then uninstall it. From the original source files #make uninstall-all Get the latest version from http://www.asterisk.org/downloads #cd /usr/src Get asterisk version 1.6.1.1 wget http://downloads.asterisk.org/pub/telephony/asterisk/releases/asterisk-1.6.1.1.tar.gz Get the DAHDI linux drivers wget http://downloads.asterisk.org/pub/telephony/dahdi-linux/releases/dahdi-linux-2.2.0.1.tar.gz Get the DAHDI linux tools wget http://downloads.asterisk.org/pub/telephony/dahdi-tools/releases/dahdi-tools-2.2.0.tar.gz Get the ISDN drivers (not sure if its still needed even if you don't have ISDN) wget http://downloads.asterisk.org/pub/telephony/libpri/releases/libpri-1.4.10.1.tar.gz Get the Addon wget http://downloads.asterisk.org/pub/telephony/asterisk/releases/asterisk-addons-1.6.1.0.tar.gz Unpack all the tarballs Go to the asterisk 1.6.1.1 folder and launch the install script #./install.pl # ./configure #make menuselect #make install #make #make install #make samples #make config +---- Asterisk Installation Complete -------+ + + + YOU MUST READ THE SECURITY DOCUMENT + + + + Asterisk has successfully been installed. + + If you would like to install the sample + + configuration files (overwriting any + + existing config files), run: + + + + make samples + + + +----------------- or ---------------------+ + + + You can go ahead and install the asterisk + + program documentation now or later run: + + + + make progdocs + + + + **Note** This requires that you have + + doxygen installed on your local system + == Compile DAHDI == Go to the dahdi folder # make # make install ################################################### ### ### DAHDI installed successfully. ### If you have not done so before, install the package ### dahdi-tools. ### Go to dahdi-tools First run the configure script or you get a error "no rule to make target 'makeopts'" #./configure # make # make install ################################################### ### ### DAHDI tools installed successfully. ### If you have not done so before, install init scripts with: ### ### make config ### ################################################### Go to the DAHDI tools folder # make config install -D dahdi.init /etc/init.d/dahdi /usr/bin/install -c -D -m 644 init.conf.sample /etc/dahdi/init.conf /usr/bin/install -c -D -m 644 modules.sample /etc/dahdi/modules /usr/bin/install -c -D -m 644 xpp/genconf_parameters /etc/dahdi/genconf_parameters /usr/bin/install -c -D -m 644 modprobe.conf.sample /etc/modprobe.d/dahdi /usr/bin/install -c -D -m 644 blacklist.sample /etc/modprobe.d/dahdi.blacklist /usr/sbin/update-rc.d dahdi defaults 15 30 Adding system startup for /etc/init.d/dahdi ... /etc/rc0.d/K30dahdi -> ../init.d/dahdi /etc/rc1.d/K30dahdi -> ../init.d/dahdi /etc/rc6.d/K30dahdi -> ../init.d/dahdi /etc/rc2.d/S15dahdi -> ../init.d/dahdi /etc/rc3.d/S15dahdi -> ../init.d/dahdi /etc/rc4.d/S15dahdi -> ../init.d/dahdi /etc/rc5.d/S15dahdi -> ../init.d/dahdi DAHDI has been configured. List of detected DAHDI devices: pci:0000:04:05.0 wctdm24xxp+ d161:8005 Wildcard TDM410P run 'dahdi_genconf modules' to load support for only the DAHDI hardware installed in this system. By default support for all DAHDI hardware is loaded at DAHDI start. darktower:/usr/src/dahdi-tools-2.2.0# 885df4424009b6020f1edffd3470f5fc94c14ebc 2438 2437 2009-08-19T14:29:28Z Insomnia 3 /* Compile Asterisk */ wikitext text/x-wiki Asterisk installation on Lenny can be performed with ease using Aptitude. This brings you Asterisk version 1.4.20. Since this has a graphical GUI manager, it might be wise to add X to your server. = Compile Asterisk = If you have a previous version of asterik first Backup config files /ets/asterisk and then uninstall it. From the original source files #make uninstall-all Get the latest version from http://www.asterisk.org/downloads #cd /usr/src Get asterisk version 1.6.1.1 wget http://downloads.asterisk.org/pub/telephony/asterisk/releases/asterisk-1.6.1.1.tar.gz Get the DAHDI linux drivers wget http://downloads.asterisk.org/pub/telephony/dahdi-linux/releases/dahdi-linux-2.2.0.1.tar.gz Get the DAHDI linux tools wget http://downloads.asterisk.org/pub/telephony/dahdi-tools/releases/dahdi-tools-2.2.0.tar.gz Get the ISDN drivers (not sure if its still needed even if you don't have ISDN) wget http://downloads.asterisk.org/pub/telephony/libpri/releases/libpri-1.4.10.1.tar.gz Get the Addon wget http://downloads.asterisk.org/pub/telephony/asterisk/releases/asterisk-addons-1.6.1.0.tar.gz Unpack all the tarballs Go to the asterisk 1.6.1.1 folder and launch the install script # ./configure I had a C++ preprocessor "/lib/cpp" fails sanity check and needed to install g++ #apt-get install g++ #make menuselect (OPTIONAL) #make #make install #make samples #make config +---- Asterisk Installation Complete -------+ + + + YOU MUST READ THE SECURITY DOCUMENT + + + + Asterisk has successfully been installed. + + If you would like to install the sample + + configuration files (overwriting any + + existing config files), run: + + + + make samples + + + +----------------- or ---------------------+ + + + You can go ahead and install the asterisk + + program documentation now or later run: + + + + make progdocs + + + + **Note** This requires that you have + + doxygen installed on your local system + == Compile DAHDI == Go to the dahdi folder # make # make install ################################################### ### ### DAHDI installed successfully. ### If you have not done so before, install the package ### dahdi-tools. ### Go to dahdi-tools First run the configure script or you get a error "no rule to make target 'makeopts'" #./configure # make # make install ################################################### ### ### DAHDI tools installed successfully. ### If you have not done so before, install init scripts with: ### ### make config ### ################################################### Go to the DAHDI tools folder # make config install -D dahdi.init /etc/init.d/dahdi /usr/bin/install -c -D -m 644 init.conf.sample /etc/dahdi/init.conf /usr/bin/install -c -D -m 644 modules.sample /etc/dahdi/modules /usr/bin/install -c -D -m 644 xpp/genconf_parameters /etc/dahdi/genconf_parameters /usr/bin/install -c -D -m 644 modprobe.conf.sample /etc/modprobe.d/dahdi /usr/bin/install -c -D -m 644 blacklist.sample /etc/modprobe.d/dahdi.blacklist /usr/sbin/update-rc.d dahdi defaults 15 30 Adding system startup for /etc/init.d/dahdi ... /etc/rc0.d/K30dahdi -> ../init.d/dahdi /etc/rc1.d/K30dahdi -> ../init.d/dahdi /etc/rc6.d/K30dahdi -> ../init.d/dahdi /etc/rc2.d/S15dahdi -> ../init.d/dahdi /etc/rc3.d/S15dahdi -> ../init.d/dahdi /etc/rc4.d/S15dahdi -> ../init.d/dahdi /etc/rc5.d/S15dahdi -> ../init.d/dahdi DAHDI has been configured. List of detected DAHDI devices: pci:0000:04:05.0 wctdm24xxp+ d161:8005 Wildcard TDM410P run 'dahdi_genconf modules' to load support for only the DAHDI hardware installed in this system. By default support for all DAHDI hardware is loaded at DAHDI start. darktower:/usr/src/dahdi-tools-2.2.0# 5a32d390a6a40ee501f6c43b63595b5d2de5856b 0 1409 2425 2394 2009-07-25T18:54:10Z 212.238.151.172 0 /* Partitioning */ link to Debian dir structure wikitext text/x-wiki <big>'''Debian Lenny Base Server setup'''</big> ==Getting the hardware== {| class="wikitable" border="1" |- |Note: in the following we're assuming you'll be assembling an x86 or x64 type of machine, as it has about the best price/performance ratio you could wish. Hardware costs for other platforms, e.g. IBM's Series p or HP 9000, can be much higher, while platforms like ARM are just not very powerful. Also, the availability of components and of help can be less than with the ubiquietous x86/x64 platforms. |} Naturally, before we can begin to install the operating system, we need to obtain the necessary hardware. Which hardware you require depends on what you want the server for; a testserver on which you will test only a single feature for a short while does not need the same quality of hardware as does a server that's supposed to act as a homeserver for many tasks for a long time. We'll assume your server will be like ours: a home server that must perform many tasks with sufficient performance for a few users, that's reliable and will last for a couple of years. So build or obtain a server with at least the following hardware: * a spacious casing with big, quiet cooling fans, like the [http://www.coolermaster.com/products/product.php?act=detail&id=317 one we have]; * an efficient, heavy-duty power supply that's rated high enough for your devices, and has a decent efficiency. For example, a [http://www.corsair.com/products/power_supplies.aspx Corsair HX520] power supply; * a server class motherboard, e.g. an [http://www.intel.com/products/server/index.htm?iid=home+hdr_nav2_server Intel] or [http://uk.asus.com/products.aspx?l1=9&l2=39&l3=263 AMD] based single-processor motherboard. DO NOT go for the cheapest motherboard you can find: if you pay peanuts, that's what you get. Server class motherboards have the quality, stability and durability you'll need from it, and usually also most of the needed peripherals, like multiple ethernet network cards on-board. Usually a Linux server doesn not require much in the way of video performance (and the screen will be used rarely, if ever), so any old integrated graphics will do. * a matching CPU - or multiple, if you think you need the power and the selected motherboard has the sockets. Furthermore, it pays to think about the energy use of your server CPU. For instance, you could choose an AMD Athlon X2 5600+, running at 2,8 Ghz and 89W maximum, but you can also go for an AMD Athlon X2 4850E, which is dualcore at 2,5GHz, but uses only 45W maximum - almost half of the former! And over a one year period, this choice can save up to 385 kWH. With electricity costing close to €0,20 per kWH (at least for some of us), that could save you €77,- a year. All I'm saying is: think about power use. * a CD-ROM- or DVD-player - although you might not need it any more after installation. * ''multiple'' harddisks - you'll want redundancy, because every harddisk fails at some time. The drive with your data on it will fail fatally when it is most inconvenient to you, and any data on it that you consider valuable will likely be lost forever. To make Murphy's work somewhat harder for him, we're going to store our data redundantly, so that if any drive in the server fails, we'll not lose our data or our server. Thus, get yourself at least two harddisks for your operating system, at least 40GiB in size (don't think you'll be able to buy smaller ones nowadays), and spanking new (NEVER use old harddisks for your production server, new ones are just too cheap to run that risk!). * (multipe) network card(s) (NICs) if your motherboard does not have enough NICs integrated on-board. You'll want a NIC for your network, and another one for your Internet connection; and possible a third one for the wireless segment of your network. Now build a machine out of the above, or have someone build it for you. ==Preparation of the hardware== (Note: in the following we're again assuming you're running an x86/x64 type of machine. Hardware requirements and preparation for other platforms, e.g. IBM's Series p or HP 9000, can differ significantly) Next, check the assembled hardware: * is the configuration complete? If it does not have a CD/DVDplayer from which it can boot, then installing the software gets more difficult - at least get an USB external DVDdrive or something like that. * are all components connected properly (memory DIMMs seated correctly in their sockets, AGP card inserted correctly into the AGP slot, et cetera) and are all cable connections made (multiple power cables to the motherboard, one power cable plus one data cable to each hard disk, etcetera)? Following this, you may hook up the machine. It's going to need power, and you will need at least a keyboard and a monitor attached. And if you want to use a Graphic User Interface to install, a mouse is required also. When you've ensured that everything is safe, you can turn on the machine, and continue to check it: * do all fans start to run when you turn on the machine? (if not, then '''quickly''' turn off your machine and correct the problem!) * does/do the hard disk(s) spin up? * do the power button and reset button operate correctly? * are the power led, HDD led and other display gadgetry functional? * when you let the machine power up, does it emit a single beep? And does it then show a Power-On Self Test screen (POST)? * Does it show the correct amount of memory in the POST screen? The correct number & speed of the CPU(s)? * Does the machine recognise all controller cards (SCSI, S-ATA etc)? And all attached DVD-drives and hard disks? * are all BIOSes/firmwares up to date? * If you have a hardware RAID controller, are your RAID arrays built already? * does the machine attempt to boot from at least the hard disk? ...et cetera. If there is any problem, or you want to update the BIOS or firmwares, it's best to do it before the operating system is installed. This Wiki, however, is not the place (yet) to get the information on how to accomplish these type of tasks. The last steps in the preparation of the hardware, are * to ensure that the machine can boot from CD/DVD, so that you can start installing Debian from it. It is possible to install Debian over the network, but that requires setting up a [http://www.debian-administration.org/articles/478 PXE Boot server] which is (currently) outside the scope of this wiki. * to connect the hardware to the Internet, so that it can get all required updates etcetera; please do ''not'' connect the box ''straight'' to the Internet, but make sure that it's safely behind a firewall, or failing that, a NAT router. By now the system should be almost ready to receive it's Operating System. But first we have an issue to tackle: that of redundancy. ==Software or hardware RAID== Your hard disks will fail. They absolutely will. It is never a question of "if", only of "when". So what will you do when the hard disk containing your complete operating system fails (besides pulling your hair out, that is)? What we propose is this: hard disks are pretty cheap nowadays, so let's use [http://en.wikipedia.org/wiki/Redundant_array_of_independent_disks RAID technology] to make our hard drive space resilient against failure of a whole drive. So first make sure that you have ''two'' disks of equal size instead of only one. Had you already been planning to use multiple disks already, then make sure you have at least ''one'' disk more than your space requirements prescribe; the space on that extra drive will provide the needed redundancy. Next, [[RAID fundamentals under Linux | click here]] to learn a bit more about RAID, to make the decision to use hardware-based and/or software-based RAID, and to plan your RAID arrays. In this example, we'll assume you're using hardware RAID on a RAID controller that's supported by the Debian installation software. This means that the installation software will "see" your RAID array(s) and present them as usable drives. ==Planning your network names== If your machine must become a part of an existing network, then it's almost certain that you already have a DNS domain in place; in that case: obtain the DNS suffix your machine will get (the DNS domain your machine will "belong" to). However, it's also possible that this machine is going to be the first machine in your new network, in which case the whole issue of DNS suffixes is wide open. If you need more information on DNS, go [[http://www.isc.org/sw/bind/arm95/Bv9ARM-all.html#id2564824 here]]. For now we'll assume you have (or will quickly obtain) a working knowledge of the DNS system. Here is our tip on choosing a DNS domain for your home network: * do '''not''' use a publicly registered domain name (e.g. "cocacola.com") for any machine that's not primarily intended to serve the public on the Internet; * for machines serving a private network, we urge you to use Top Level Domain name "lan" (to signify your machine is on a Local Area Network or LAN) * for the Domain Name itself, we suggest you use a level 2 name, like "saruman.lan", and not a level 3 name, like "mister.saruman.lan". This is only a short section on DNS, but remember that once a proper DNS system is in place, it's pretty much work to change it. At any rate, this section has most likely showed you that you need to put some thought into the DNS Domain Name design of your home network. OK, with this out of the way, we can get to installing the OS. ==Operating System installation== To install an Operating System (OS), it's kinda instrumental that you have one. Here, we're going to use [http://www.debian.org/intro/about Debian], the biggest [http://www.debian.org/intro/about#free Free] OS that we know of. Free stands for Freedom, but incidentally that Freedom also means it's gratis, an appealing aspect of Free. To get your own copy of Debian, go to their [http://www.debian.org/distrib/ download site] and obtain the latest [http://www.debian.org/releases/ Stable] image - in this wiki it's Debian 5.0, or "Lenny" as it's also known (although it wasn't stable at the time of writing this). Besides the choice which release of Debian you want to run, you also have to know for which platform you're downloading (in our case: either ''amd64'' or ''i386'' depending on your hardware platform) and what kind of install you wish - if you have a working, fast Internet connection available at the time of install, then we recommend getting the [[http://www.debian.org/CD/netinst/ netinst] CD image; it's a relatively small CD, that'll be able to get you going, but gets most of the software you'll need straight from the 'net at install time. In the example at hand we're installing on an AMD Athlon x2-based server, on which we wish to install 64-bits software. We'll download [http://cdimage.debian.org/cdimage/weekly-builds/amd64/iso-cd/debian-testing-amd64-CD-1.iso debian-testing-amd64-CD-1.iso], which is Lenny, not yet stable at the time of writing. Burn this to a CD-recordable and boot your prepared hardware platform from this CD. After booting from the CD, a friendly prompt invites you to indicate how you want to start installing (image 1). Your choices are listed under &lt;F3&gt;; we're going to use the standard Command Line installation, so we choose "install" and hit &lt;enter&gt;. {| class="wikitable" border="1" |- |We could easily use "Graphic install", in which case we'd have a nice fresh Graphical User Interface for our installation. ''We're'' not going to, because we're real men, and [http://isg.ee.ethz.ch/tools/realmen/ Real Men Don't Click]. Also, we've found that from the GUI it's hard to switch to a second console and then back. We could also go to the Advanced options (image 2), and opt for "Expert install" or "Graphical expert install" as installation method, because it gives a much finer grain of control; however we usually don't need that control, and can do without the barrage of extra questions that the "expert" installation method pose. |} After the Linux kernel finishes initializing the machine, a simple text-based installer appears (image 3) that immediately starts asking questions. Answer them according to your needs. Our example system uses the following choices: * Language: english * country: other &gt; Netherlands * keymap: American English (since we have a keyboard with US layout) Some installation software loads, and we get to the next phase: if you have multiple NICs in your machine (which we believe you ''should'' have!!), and if they're detected properly, then you're required to indicate which of the detected network interface cards (NIC) is going to be the "primary" NIC. {| class="wikitable" border="1" |- |Here, trouble could begin. If your machine has only network cards that are '''not''' supported, then you'll see '''no''' cards here - but then how are you going to do a NetInstall? A solution would be to (temporarily) install a NIC that ''is'' supported, like a cheap Realtek card, or an old 3Com 905 card. Then, when the whole system is installed, up and running, you could compile a new kernel that contains support for your actual NICs, and when these work, remove the temporary NIC. For now, we'll assume that at least one of your NICs is recognised properly by the Debian installation routine. |} Select the card that's connected and has (indirect) access to Internet (again: it should ''not'' be connected straight to the wild wild web, but sit safely behind a firewall, at least until we've installed our own firewall); if at all possible, let it be the NIC that'll be connected to your home network itself, on the ''inside'' of your server. Let's assume that this NIC is designated ''eth0'' by the Debian installation. This card will now be configured using DHCP, so if you're on a network with a DHCP-server, the network will work straight away. If it's not, you can either configure the network manually or fix your DHCP-server and connection between it and ''eth0''. Next is one of the hardest questions that any OS installation is going to ask you: what will be the host name of the system? You could change it at any time in the future, but with lots of hassle, so you better choose wisely. Here are our tips: * do '''not''' name your machine after the user that's going to use it, e.g. "bernie-pc" (at some time in the future, Bernie's machine will be moved to Alice, so then Alice is working on "bernie-pc" which makes the situation quite unclear); * do '''not''' name your machine after the department or workgroup that's using it most, e.g. "accounting-srv" (same reasoning); * do '''not''' name your machine after it's main function, e.g. "printserver" (at some time in the future, the main function is moved to another machine, and/or an alternative function will become the main function of the machine); * do '''not''' name your machine after it's location, e.g. "srv-boston" (at some time in the future, the box will be moved to another location); * do '''not''' name your machine after it's hardware configuration, e.g. "ibmx346" (at some time in the future, either another xSeries x346 will be wheeled in, or the machine will be upgraded to accomodate increased use or overcome hardware problems - your "ibmx346" could suddenly be running on an xSeries x3650). What we feel are safe names for ''any'' machine in your network are true names, perhaps linked to a common theme: names of European cities, names of movie characters, names of countries or holiday destinations et cetera. Immediately following comes the question of the Domain Name. This is about a DNS domain, so effectively the installation program is asking which DNS suffix the host name should have; if the DHCP-server already provided something it'll be suggested, but you can override it if need be. In the preparatory phase, you'll have decided on continuation of your current DNS schema, or starting a new one. Either way, put the chosen DNS suffix in and press &lt;enter&gt;. ==Partitioning== Next comes the question of partitioning, or how to divide the available disk space into chunks for the server to use. This is a tricky subject, because if you put all storage space into one partition, then some day a runaway process will fill up the entire disk with useless logs, and the system will crash. On the other hand, if you divvy up all space into little chunks, then some application is going to need space in one of those partitions where there is none, even though there may be plenty in other partitions. To prevent both problems from occuring, we're going to use [http://tldp.org/HOWTO/LVM-HOWTO/whatisvolman.html Logical Volume Management (LVM)] so that we can provision enough space to start our server, but keep some space in reserve to apply when needed, where it'll be needed. So, we at Saruman.biz have put together a recommended standard partitioning scheme. The basis (in accordance with the standard [[Debian directory structure]]is this: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Partition !style="background:#ffdead;"|MD !style="background:#ffdead;"|LVG !style="background:#ffdead;"|LV-name !style="background:#ffdead;"|Size <br> (physical machine) !style="background:#ffdead;"|Size (VM) !style="background:#ffdead;"|File System !style="background:#ffdead;"|Mount point |- | 1 | /dev/md0 | &nbsp; | &nbsp; | 100MiB | 100MiB | ext3 | /boot |- | 2 | /dev/md1 | &nbsp; | &nbsp; | 3GiB | 1GiB | ext3 | / |- | rowspan="8" valign="top" | 3 | rowspan="8" valign="top" | /dev/md2 | rowspan="8" valign="top" style="background:lightgrey"| system | style="background:lightgrey" | swap | 1GiB<ref name="swap">Rule of thumb: twice the size of the machine's RAM, but no less than 256MiB and no more than 2GiB</ref> | 256MiB<ref name="swap"/> | swap | &nbsp; |- | style="background:lightgrey" | var | 1GiB | 512MiB | ext3 | /var |- | style="background:lightgrey" | varlog | 1GiB | 512MiB | ext3 | /var/log |- | style="background:lightgrey" | appslog | 3GiB | -<ref>Yes, we think a separate ''appslog'' is a very good idea, but when creating a minimal VM, we have to save disk space ''somewhere''...</ref> | ext3 | /var/appslog |- | style="background:lightgrey" | home | 1GiB<ref name="home">Note that this heavily depends on the purpose of the machine; if it is not to house any users, then (almost) no space is needed for /home. But on the other hand if e.g. a virtual user is to be used for keeping mailstores, or other service users need home space, then /home needs to be big enough for that.</ref> | 512MiB<ref name="home"/> | ext3 | /home |- | style="background:lightgrey" | usr | 3GiB | 3GiB | ext3 | /usr |- | style="background:lightgrey" | tmp | 1GiB | 512MiB | ext3 | /tmp |- | style="background:lightgrey" | opt | 1GiB | - | ext3 | /opt |- ! colspan="4" style="text-align:right"| Total ! 18.1GiB ! 6.9GiB ! colspan="2" | |- |} As you can see, the partition table works as follows: we assume that we wind up with 3 partitions, either on three separate software RAID arrays (''md0'' through ''md2'') or on one single hardware RAID array (in which case the 2nd column ''MD'' does not apply). The size of the partitions depends on your machine's make: for standard physical machines the 5th column does sensible suggestions, even though you could choose to have different sizes and of course different divisions altogether. If your machine happens to be a virtual one, running inside a [http://www.vmware.com/products/server/ VMware Server] or [http://www.vmware.com/products/vi/esx/ VMware ESX host], or the like, then you might want to start out with more modest partitions. The same holds for small servers that must run off Flash drives. Anyways, we're now at the Debian installation screen that lets us partition our disks. We're ''not'' going to use any of the "guided" partitionings, we go for "manual". Choosing that brings us to a screen showing all drives that the installation routine has detected, and all partitions on those drives that the installer can "see". We're going to do some assuming here once more: let's assume the drive(s) on which you want to install are visible, and are empty (containing no other partitions). <references/> ===Software RAID partitioning=== If you're to use software RAID, you now have to select the free space on the first drive, press &lt;enter&gt;, and then tell what you want to do with the free space: create a new partition, tell which size you want it to be (see table above), give the type of partition (primary), and give where on the disk it'll sit (the beginning). Next, a screen comes up that details how the partition you're requesting will be created. Here we make some changes: under "use as" we're going to select "physical volume for RAID". This clears all the other options in this screen, except for the "bootable" flag, which must be "on" for the first partition that we'll mount as ''/boot''. Now select "Done setting up the partition". Next, go to the free space on the second disk, and do ''exactly'' the same, to create an identical physical volume for RAID - if it's the first partition, select the "bootable" flag as well (we'll want to be able to boot from this second disk if the first disk fails, right?). Then go back to the rest of the free space on the first disk, make the second physical volume for RAID, duplicate it on the second disk. Then, go back to the rest of the free space on the first disk, make the third physical volume for RAID, and again duplicate it on the second disk. If you now go back to the "partition disks" overview, you'll see all the partitions you've specified listed on their respective disks. But at the top an extra option has appeared, called "configure software RAID". When you now select this option, the installer will ask if it may write the changes you've made to disk. This actually creates the partition tables on the disks. Note that at the end of configuring your partitions, an extra screen may appear (image 4): this asks if you care to identify which MD RAID devices must be started in order to be able to mount the root filesystem. Answering this question with a list of MD's like "md0 md1 md2" or simply "all" will let your server start the listed MD's very early in the boot sequence. ===Hardware RAID partitioning=== Now, if you have hardware RAID, then on your first (boot) disk just make 3 partitions, in the following manner: Select the free space on the intended boot disk, press &lt;enter&gt;, select "create a new partition", and fill out the desired size (100MB). Type is primary, location is beginning of the disk, and in the details of the partition, we only need to change the Mount point to "/boot", and set the Bootable flag to "On". Then we're "Done setting up this partition". The second partition is made the same way, but the desired size is 3GB, the Mount point is "/", and the Bootable flag remains off. Again, we're "Done setting up this partition". The third partition is again a primary partition, it takes up the entire rest of the disk, but the type is not ext3, but "physical volume for LVM". Again, we're "Done setting up this partition". But now from the main partitioner screen, we can access "Configure the Logical Volume Manager". The installer asks if it can write out the choices made to the disk, and then enters the LVM setup screen, which begins with a summary explaining that you have one Free Physical Volume, and nothing more. We now create a Volume Group (VG), which (in accordance to our partitioning standard) we'll call "system". In this VG, we'll add all Physical Volumes (being the one partition we've designated so in the previous step) using the space bar. Now we repeat the following process seven times: * select "Create Logical Volume" * select Volume Group "System" * give the LV Name (from the table, e.g. swap, var etc) * give the LV size (from the table, e.g. 1GB for swap etc) After this, we can select "Finish", the partitioner creates the seven LVs, and we're back at the partitioner screen, where there are now 7 extra "disks", with names such as ''LVM VG system, LV appslog - 3.2GB Linux device mapper''. Each of these "disks" has one block of empty space, which we now assign: seven times we repeat the following process: * select the unassigned chunk of empty space of an LV (e.g. appslog) and press &lt;enter&gt;; * Change "Use as: do not use" into the desired filesystem (ext3 - only the LV "swap" gets as filesystem type "swap area") * Change the mount point from "none" to the one corresponding with the name of the LV (note: the swap LV has no mountpoint; the appslog mountpoint must be entered manually as "/var/appslog") * If so desired, a label can be assigned to the partition (we usually don't) * select "Done setting up the partition" Once all this is done, we can look over the configuration once more, and then select "Finish partitioning and write changes to disk". A summary configuration screen will show, and we'll affirm with "yes" that these partitions can indeed be formatted. After some formatting screens flashing by (unless your partitions are particularly big, your system is particularly slow, or something goes wrong) the installation procedure continues. ==Final installer steps== Next comes one '''VERY''' important question: what to use as root password? We cannot stress this enough: choose a SAFE password! Do NOT go for an easy-to-remember one, go for STRONG and SAFE. There are tools to help you generate strong passwords, like [http://www.pctools.com/guides/password/ this page]: use them! We strongly suggest 10 characters or more, including letters, mixed case, and numbers, so something like ''SuCRe4hecH'' (do NOT use this, generate your own!). Next, give the full name of the principal user of this server (your own, we assume), give the login-name (your given name, we assume), and a corresponding password. Again, use a SAFE password. As long as you don't make your principal user equivalent to root, you might go for a slightly weaker password (8 characters instead of 10), but we rather suggest you make the password just as strong (and different from!) the root password. After entering the details of these two users "root" and "you", the Debian installer will ask you how it can contact the Debian archives, in the dialoge "configure the package manager". For the NetInstall version of Debian, this is as good as mandatory. So here, we say "yes, use a Network Mirror", and in the following list select the country in which we are (in our case: the Netherlands), so the installer can present us with a number of network mirrors "close by". We select ftp.nl.debian.org. Next screen: should you be behind a proxy server, then it's possible to specify that here. And then the test: the system will say "scanning the mirror..." and try to contact the specified mirror. If it does not succeed, then there is either a network problem, a problem with this box's network card, or you've not specified the mirror or proxy correctly - so fix it. You'll know the network mirror has succesfully been contacted when the next dialogue appears - currently "configuring popularity-contest". Answer this question as you please. And then one of the last "big" questions: Software Selection. In this dialogue, you can easily select bundles of software to be installed. The choices are currently: * Desktop environment * Web server * Print server * DNS server * File server * Mail server * SQL database * Laptop * Standard system (selected by default) We have to make a little confession here: we've never before used this option in the installer. In fact, we even deselect the Standard System, so as to minimize the number of software packages that the base installation of our server contains. This makes it more work to manually add packages later, but we feel it gives us more control and understanding of our systems. So if you are like us: deselect the Standard System entry, and select Continue. The next dialogue handles the installation of the [http://www.gnu.org/software/grub/ ''grub'' bootloader]. Unless your disks weren't empty and you're attempting to make this system multiboot, you'll most likely get a question if you'll allow the installer to install ''grub'' into the boot sector of the first hard disk. We'll confirm with "Yes". After the installation of grub is completed, the CD-ROM is ejected, and the system is ready to reboot into Debian Etch. Remove the CD and select "Continue" ==Finishing up the installation== The system should reboot into Debian. This means you should see the following boot sequence: * your machine's standard POST messages * then, a blue grub menu on a black screen, with two entries: ** Debian GNU/Linux, kernel 2.6.&lt;something&gt; ** Debian GNU/Linux, kernel 2.6.&lt;something&gt (single-user mode); * then, after a default time-out, the first grub option will go into effect, and the Linux kernel is started. Lots of cryptic messages in grey-on-black will scroll by, until the last few lines read: "Debian GNU/Linux 4.0 &lt;hostname&gt; tty1" and "&lt;hostname&gt; login:" If your system does not reach this login, and/or some horrible error messages appear anywhere in this boot sequence, then you've got some extra work ahead. For now we'll assume you've reached the login prompt without problem. Log in as the principal user (try to avoid logging in as root! That's BAD practice!). Once logged in, save a copy of the boot messages using ''sudo dmesg > boot.txt'' or whatever you like. Then look through the boot messages, e.g. with ''vi -R boot.txt''. Furthermore, [[APT_and_aptitude | use Aptitude]] to make sure ''all'' your software is updated to the latest version. Done! Your base system is ready. You probably now want to [[essential system software | install essential software]], [[roll your own kernel]] and [[connect your server to the Internet]]. 267d83bc6db9fe4a506e9022093f27fe8f68a70a 2429 2425 2009-07-26T10:40:59Z Saruman! 2 /* Finishing up the installation */ added link to aliases wikitext text/x-wiki <big>'''Debian Lenny Base Server setup'''</big> ==Getting the hardware== {| class="wikitable" border="1" |- |Note: in the following we're assuming you'll be assembling an x86 or x64 type of machine, as it has about the best price/performance ratio you could wish. Hardware costs for other platforms, e.g. IBM's Series p or HP 9000, can be much higher, while platforms like ARM are just not very powerful. Also, the availability of components and of help can be less than with the ubiquietous x86/x64 platforms. |} Naturally, before we can begin to install the operating system, we need to obtain the necessary hardware. Which hardware you require depends on what you want the server for; a testserver on which you will test only a single feature for a short while does not need the same quality of hardware as does a server that's supposed to act as a homeserver for many tasks for a long time. We'll assume your server will be like ours: a home server that must perform many tasks with sufficient performance for a few users, that's reliable and will last for a couple of years. So build or obtain a server with at least the following hardware: * a spacious casing with big, quiet cooling fans, like the [http://www.coolermaster.com/products/product.php?act=detail&id=317 one we have]; * an efficient, heavy-duty power supply that's rated high enough for your devices, and has a decent efficiency. For example, a [http://www.corsair.com/products/power_supplies.aspx Corsair HX520] power supply; * a server class motherboard, e.g. an [http://www.intel.com/products/server/index.htm?iid=home+hdr_nav2_server Intel] or [http://uk.asus.com/products.aspx?l1=9&l2=39&l3=263 AMD] based single-processor motherboard. DO NOT go for the cheapest motherboard you can find: if you pay peanuts, that's what you get. Server class motherboards have the quality, stability and durability you'll need from it, and usually also most of the needed peripherals, like multiple ethernet network cards on-board. Usually a Linux server doesn not require much in the way of video performance (and the screen will be used rarely, if ever), so any old integrated graphics will do. * a matching CPU - or multiple, if you think you need the power and the selected motherboard has the sockets. Furthermore, it pays to think about the energy use of your server CPU. For instance, you could choose an AMD Athlon X2 5600+, running at 2,8 Ghz and 89W maximum, but you can also go for an AMD Athlon X2 4850E, which is dualcore at 2,5GHz, but uses only 45W maximum - almost half of the former! And over a one year period, this choice can save up to 385 kWH. With electricity costing close to €0,20 per kWH (at least for some of us), that could save you €77,- a year. All I'm saying is: think about power use. * a CD-ROM- or DVD-player - although you might not need it any more after installation. * ''multiple'' harddisks - you'll want redundancy, because every harddisk fails at some time. The drive with your data on it will fail fatally when it is most inconvenient to you, and any data on it that you consider valuable will likely be lost forever. To make Murphy's work somewhat harder for him, we're going to store our data redundantly, so that if any drive in the server fails, we'll not lose our data or our server. Thus, get yourself at least two harddisks for your operating system, at least 40GiB in size (don't think you'll be able to buy smaller ones nowadays), and spanking new (NEVER use old harddisks for your production server, new ones are just too cheap to run that risk!). * (multipe) network card(s) (NICs) if your motherboard does not have enough NICs integrated on-board. You'll want a NIC for your network, and another one for your Internet connection; and possible a third one for the wireless segment of your network. Now build a machine out of the above, or have someone build it for you. ==Preparation of the hardware== (Note: in the following we're again assuming you're running an x86/x64 type of machine. Hardware requirements and preparation for other platforms, e.g. IBM's Series p or HP 9000, can differ significantly) Next, check the assembled hardware: * is the configuration complete? If it does not have a CD/DVDplayer from which it can boot, then installing the software gets more difficult - at least get an USB external DVDdrive or something like that. * are all components connected properly (memory DIMMs seated correctly in their sockets, AGP card inserted correctly into the AGP slot, et cetera) and are all cable connections made (multiple power cables to the motherboard, one power cable plus one data cable to each hard disk, etcetera)? Following this, you may hook up the machine. It's going to need power, and you will need at least a keyboard and a monitor attached. And if you want to use a Graphic User Interface to install, a mouse is required also. When you've ensured that everything is safe, you can turn on the machine, and continue to check it: * do all fans start to run when you turn on the machine? (if not, then '''quickly''' turn off your machine and correct the problem!) * does/do the hard disk(s) spin up? * do the power button and reset button operate correctly? * are the power led, HDD led and other display gadgetry functional? * when you let the machine power up, does it emit a single beep? And does it then show a Power-On Self Test screen (POST)? * Does it show the correct amount of memory in the POST screen? The correct number & speed of the CPU(s)? * Does the machine recognise all controller cards (SCSI, S-ATA etc)? And all attached DVD-drives and hard disks? * are all BIOSes/firmwares up to date? * If you have a hardware RAID controller, are your RAID arrays built already? * does the machine attempt to boot from at least the hard disk? ...et cetera. If there is any problem, or you want to update the BIOS or firmwares, it's best to do it before the operating system is installed. This Wiki, however, is not the place (yet) to get the information on how to accomplish these type of tasks. The last steps in the preparation of the hardware, are * to ensure that the machine can boot from CD/DVD, so that you can start installing Debian from it. It is possible to install Debian over the network, but that requires setting up a [http://www.debian-administration.org/articles/478 PXE Boot server] which is (currently) outside the scope of this wiki. * to connect the hardware to the Internet, so that it can get all required updates etcetera; please do ''not'' connect the box ''straight'' to the Internet, but make sure that it's safely behind a firewall, or failing that, a NAT router. By now the system should be almost ready to receive it's Operating System. But first we have an issue to tackle: that of redundancy. ==Software or hardware RAID== Your hard disks will fail. They absolutely will. It is never a question of "if", only of "when". So what will you do when the hard disk containing your complete operating system fails (besides pulling your hair out, that is)? What we propose is this: hard disks are pretty cheap nowadays, so let's use [http://en.wikipedia.org/wiki/Redundant_array_of_independent_disks RAID technology] to make our hard drive space resilient against failure of a whole drive. So first make sure that you have ''two'' disks of equal size instead of only one. Had you already been planning to use multiple disks already, then make sure you have at least ''one'' disk more than your space requirements prescribe; the space on that extra drive will provide the needed redundancy. Next, [[RAID fundamentals under Linux | click here]] to learn a bit more about RAID, to make the decision to use hardware-based and/or software-based RAID, and to plan your RAID arrays. In this example, we'll assume you're using hardware RAID on a RAID controller that's supported by the Debian installation software. This means that the installation software will "see" your RAID array(s) and present them as usable drives. ==Planning your network names== If your machine must become a part of an existing network, then it's almost certain that you already have a DNS domain in place; in that case: obtain the DNS suffix your machine will get (the DNS domain your machine will "belong" to). However, it's also possible that this machine is going to be the first machine in your new network, in which case the whole issue of DNS suffixes is wide open. If you need more information on DNS, go [[http://www.isc.org/sw/bind/arm95/Bv9ARM-all.html#id2564824 here]]. For now we'll assume you have (or will quickly obtain) a working knowledge of the DNS system. Here is our tip on choosing a DNS domain for your home network: * do '''not''' use a publicly registered domain name (e.g. "cocacola.com") for any machine that's not primarily intended to serve the public on the Internet; * for machines serving a private network, we urge you to use Top Level Domain name "lan" (to signify your machine is on a Local Area Network or LAN) * for the Domain Name itself, we suggest you use a level 2 name, like "saruman.lan", and not a level 3 name, like "mister.saruman.lan". This is only a short section on DNS, but remember that once a proper DNS system is in place, it's pretty much work to change it. At any rate, this section has most likely showed you that you need to put some thought into the DNS Domain Name design of your home network. OK, with this out of the way, we can get to installing the OS. ==Operating System installation== To install an Operating System (OS), it's kinda instrumental that you have one. Here, we're going to use [http://www.debian.org/intro/about Debian], the biggest [http://www.debian.org/intro/about#free Free] OS that we know of. Free stands for Freedom, but incidentally that Freedom also means it's gratis, an appealing aspect of Free. To get your own copy of Debian, go to their [http://www.debian.org/distrib/ download site] and obtain the latest [http://www.debian.org/releases/ Stable] image - in this wiki it's Debian 5.0, or "Lenny" as it's also known (although it wasn't stable at the time of writing this). Besides the choice which release of Debian you want to run, you also have to know for which platform you're downloading (in our case: either ''amd64'' or ''i386'' depending on your hardware platform) and what kind of install you wish - if you have a working, fast Internet connection available at the time of install, then we recommend getting the [[http://www.debian.org/CD/netinst/ netinst] CD image; it's a relatively small CD, that'll be able to get you going, but gets most of the software you'll need straight from the 'net at install time. In the example at hand we're installing on an AMD Athlon x2-based server, on which we wish to install 64-bits software. We'll download [http://cdimage.debian.org/cdimage/weekly-builds/amd64/iso-cd/debian-testing-amd64-CD-1.iso debian-testing-amd64-CD-1.iso], which is Lenny, not yet stable at the time of writing. Burn this to a CD-recordable and boot your prepared hardware platform from this CD. After booting from the CD, a friendly prompt invites you to indicate how you want to start installing (image 1). Your choices are listed under &lt;F3&gt;; we're going to use the standard Command Line installation, so we choose "install" and hit &lt;enter&gt;. {| class="wikitable" border="1" |- |We could easily use "Graphic install", in which case we'd have a nice fresh Graphical User Interface for our installation. ''We're'' not going to, because we're real men, and [http://isg.ee.ethz.ch/tools/realmen/ Real Men Don't Click]. Also, we've found that from the GUI it's hard to switch to a second console and then back. We could also go to the Advanced options (image 2), and opt for "Expert install" or "Graphical expert install" as installation method, because it gives a much finer grain of control; however we usually don't need that control, and can do without the barrage of extra questions that the "expert" installation method pose. |} After the Linux kernel finishes initializing the machine, a simple text-based installer appears (image 3) that immediately starts asking questions. Answer them according to your needs. Our example system uses the following choices: * Language: english * country: other &gt; Netherlands * keymap: American English (since we have a keyboard with US layout) Some installation software loads, and we get to the next phase: if you have multiple NICs in your machine (which we believe you ''should'' have!!), and if they're detected properly, then you're required to indicate which of the detected network interface cards (NIC) is going to be the "primary" NIC. {| class="wikitable" border="1" |- |Here, trouble could begin. If your machine has only network cards that are '''not''' supported, then you'll see '''no''' cards here - but then how are you going to do a NetInstall? A solution would be to (temporarily) install a NIC that ''is'' supported, like a cheap Realtek card, or an old 3Com 905 card. Then, when the whole system is installed, up and running, you could compile a new kernel that contains support for your actual NICs, and when these work, remove the temporary NIC. For now, we'll assume that at least one of your NICs is recognised properly by the Debian installation routine. |} Select the card that's connected and has (indirect) access to Internet (again: it should ''not'' be connected straight to the wild wild web, but sit safely behind a firewall, at least until we've installed our own firewall); if at all possible, let it be the NIC that'll be connected to your home network itself, on the ''inside'' of your server. Let's assume that this NIC is designated ''eth0'' by the Debian installation. This card will now be configured using DHCP, so if you're on a network with a DHCP-server, the network will work straight away. If it's not, you can either configure the network manually or fix your DHCP-server and connection between it and ''eth0''. Next is one of the hardest questions that any OS installation is going to ask you: what will be the host name of the system? You could change it at any time in the future, but with lots of hassle, so you better choose wisely. Here are our tips: * do '''not''' name your machine after the user that's going to use it, e.g. "bernie-pc" (at some time in the future, Bernie's machine will be moved to Alice, so then Alice is working on "bernie-pc" which makes the situation quite unclear); * do '''not''' name your machine after the department or workgroup that's using it most, e.g. "accounting-srv" (same reasoning); * do '''not''' name your machine after it's main function, e.g. "printserver" (at some time in the future, the main function is moved to another machine, and/or an alternative function will become the main function of the machine); * do '''not''' name your machine after it's location, e.g. "srv-boston" (at some time in the future, the box will be moved to another location); * do '''not''' name your machine after it's hardware configuration, e.g. "ibmx346" (at some time in the future, either another xSeries x346 will be wheeled in, or the machine will be upgraded to accomodate increased use or overcome hardware problems - your "ibmx346" could suddenly be running on an xSeries x3650). What we feel are safe names for ''any'' machine in your network are true names, perhaps linked to a common theme: names of European cities, names of movie characters, names of countries or holiday destinations et cetera. Immediately following comes the question of the Domain Name. This is about a DNS domain, so effectively the installation program is asking which DNS suffix the host name should have; if the DHCP-server already provided something it'll be suggested, but you can override it if need be. In the preparatory phase, you'll have decided on continuation of your current DNS schema, or starting a new one. Either way, put the chosen DNS suffix in and press &lt;enter&gt;. ==Partitioning== Next comes the question of partitioning, or how to divide the available disk space into chunks for the server to use. This is a tricky subject, because if you put all storage space into one partition, then some day a runaway process will fill up the entire disk with useless logs, and the system will crash. On the other hand, if you divvy up all space into little chunks, then some application is going to need space in one of those partitions where there is none, even though there may be plenty in other partitions. To prevent both problems from occuring, we're going to use [http://tldp.org/HOWTO/LVM-HOWTO/whatisvolman.html Logical Volume Management (LVM)] so that we can provision enough space to start our server, but keep some space in reserve to apply when needed, where it'll be needed. So, we at Saruman.biz have put together a recommended standard partitioning scheme. The basis (in accordance with the standard [[Debian directory structure]]is this: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Partition !style="background:#ffdead;"|MD !style="background:#ffdead;"|LVG !style="background:#ffdead;"|LV-name !style="background:#ffdead;"|Size <br> (physical machine) !style="background:#ffdead;"|Size (VM) !style="background:#ffdead;"|File System !style="background:#ffdead;"|Mount point |- | 1 | /dev/md0 | &nbsp; | &nbsp; | 100MiB | 100MiB | ext3 | /boot |- | 2 | /dev/md1 | &nbsp; | &nbsp; | 3GiB | 1GiB | ext3 | / |- | rowspan="8" valign="top" | 3 | rowspan="8" valign="top" | /dev/md2 | rowspan="8" valign="top" style="background:lightgrey"| system | style="background:lightgrey" | swap | 1GiB<ref name="swap">Rule of thumb: twice the size of the machine's RAM, but no less than 256MiB and no more than 2GiB</ref> | 256MiB<ref name="swap"/> | swap | &nbsp; |- | style="background:lightgrey" | var | 1GiB | 512MiB | ext3 | /var |- | style="background:lightgrey" | varlog | 1GiB | 512MiB | ext3 | /var/log |- | style="background:lightgrey" | appslog | 3GiB | -<ref>Yes, we think a separate ''appslog'' is a very good idea, but when creating a minimal VM, we have to save disk space ''somewhere''...</ref> | ext3 | /var/appslog |- | style="background:lightgrey" | home | 1GiB<ref name="home">Note that this heavily depends on the purpose of the machine; if it is not to house any users, then (almost) no space is needed for /home. But on the other hand if e.g. a virtual user is to be used for keeping mailstores, or other service users need home space, then /home needs to be big enough for that.</ref> | 512MiB<ref name="home"/> | ext3 | /home |- | style="background:lightgrey" | usr | 3GiB | 3GiB | ext3 | /usr |- | style="background:lightgrey" | tmp | 1GiB | 512MiB | ext3 | /tmp |- | style="background:lightgrey" | opt | 1GiB | - | ext3 | /opt |- ! colspan="4" style="text-align:right"| Total ! 18.1GiB ! 6.9GiB ! colspan="2" | |- |} As you can see, the partition table works as follows: we assume that we wind up with 3 partitions, either on three separate software RAID arrays (''md0'' through ''md2'') or on one single hardware RAID array (in which case the 2nd column ''MD'' does not apply). The size of the partitions depends on your machine's make: for standard physical machines the 5th column does sensible suggestions, even though you could choose to have different sizes and of course different divisions altogether. If your machine happens to be a virtual one, running inside a [http://www.vmware.com/products/server/ VMware Server] or [http://www.vmware.com/products/vi/esx/ VMware ESX host], or the like, then you might want to start out with more modest partitions. The same holds for small servers that must run off Flash drives. Anyways, we're now at the Debian installation screen that lets us partition our disks. We're ''not'' going to use any of the "guided" partitionings, we go for "manual". Choosing that brings us to a screen showing all drives that the installation routine has detected, and all partitions on those drives that the installer can "see". We're going to do some assuming here once more: let's assume the drive(s) on which you want to install are visible, and are empty (containing no other partitions). <references/> ===Software RAID partitioning=== If you're to use software RAID, you now have to select the free space on the first drive, press &lt;enter&gt;, and then tell what you want to do with the free space: create a new partition, tell which size you want it to be (see table above), give the type of partition (primary), and give where on the disk it'll sit (the beginning). Next, a screen comes up that details how the partition you're requesting will be created. Here we make some changes: under "use as" we're going to select "physical volume for RAID". This clears all the other options in this screen, except for the "bootable" flag, which must be "on" for the first partition that we'll mount as ''/boot''. Now select "Done setting up the partition". Next, go to the free space on the second disk, and do ''exactly'' the same, to create an identical physical volume for RAID - if it's the first partition, select the "bootable" flag as well (we'll want to be able to boot from this second disk if the first disk fails, right?). Then go back to the rest of the free space on the first disk, make the second physical volume for RAID, duplicate it on the second disk. Then, go back to the rest of the free space on the first disk, make the third physical volume for RAID, and again duplicate it on the second disk. If you now go back to the "partition disks" overview, you'll see all the partitions you've specified listed on their respective disks. But at the top an extra option has appeared, called "configure software RAID". When you now select this option, the installer will ask if it may write the changes you've made to disk. This actually creates the partition tables on the disks. Note that at the end of configuring your partitions, an extra screen may appear (image 4): this asks if you care to identify which MD RAID devices must be started in order to be able to mount the root filesystem. Answering this question with a list of MD's like "md0 md1 md2" or simply "all" will let your server start the listed MD's very early in the boot sequence. ===Hardware RAID partitioning=== Now, if you have hardware RAID, then on your first (boot) disk just make 3 partitions, in the following manner: Select the free space on the intended boot disk, press &lt;enter&gt;, select "create a new partition", and fill out the desired size (100MB). Type is primary, location is beginning of the disk, and in the details of the partition, we only need to change the Mount point to "/boot", and set the Bootable flag to "On". Then we're "Done setting up this partition". The second partition is made the same way, but the desired size is 3GB, the Mount point is "/", and the Bootable flag remains off. Again, we're "Done setting up this partition". The third partition is again a primary partition, it takes up the entire rest of the disk, but the type is not ext3, but "physical volume for LVM". Again, we're "Done setting up this partition". But now from the main partitioner screen, we can access "Configure the Logical Volume Manager". The installer asks if it can write out the choices made to the disk, and then enters the LVM setup screen, which begins with a summary explaining that you have one Free Physical Volume, and nothing more. We now create a Volume Group (VG), which (in accordance to our partitioning standard) we'll call "system". In this VG, we'll add all Physical Volumes (being the one partition we've designated so in the previous step) using the space bar. Now we repeat the following process seven times: * select "Create Logical Volume" * select Volume Group "System" * give the LV Name (from the table, e.g. swap, var etc) * give the LV size (from the table, e.g. 1GB for swap etc) After this, we can select "Finish", the partitioner creates the seven LVs, and we're back at the partitioner screen, where there are now 7 extra "disks", with names such as ''LVM VG system, LV appslog - 3.2GB Linux device mapper''. Each of these "disks" has one block of empty space, which we now assign: seven times we repeat the following process: * select the unassigned chunk of empty space of an LV (e.g. appslog) and press &lt;enter&gt;; * Change "Use as: do not use" into the desired filesystem (ext3 - only the LV "swap" gets as filesystem type "swap area") * Change the mount point from "none" to the one corresponding with the name of the LV (note: the swap LV has no mountpoint; the appslog mountpoint must be entered manually as "/var/appslog") * If so desired, a label can be assigned to the partition (we usually don't) * select "Done setting up the partition" Once all this is done, we can look over the configuration once more, and then select "Finish partitioning and write changes to disk". A summary configuration screen will show, and we'll affirm with "yes" that these partitions can indeed be formatted. After some formatting screens flashing by (unless your partitions are particularly big, your system is particularly slow, or something goes wrong) the installation procedure continues. ==Final installer steps== Next comes one '''VERY''' important question: what to use as root password? We cannot stress this enough: choose a SAFE password! Do NOT go for an easy-to-remember one, go for STRONG and SAFE. There are tools to help you generate strong passwords, like [http://www.pctools.com/guides/password/ this page]: use them! We strongly suggest 10 characters or more, including letters, mixed case, and numbers, so something like ''SuCRe4hecH'' (do NOT use this, generate your own!). Next, give the full name of the principal user of this server (your own, we assume), give the login-name (your given name, we assume), and a corresponding password. Again, use a SAFE password. As long as you don't make your principal user equivalent to root, you might go for a slightly weaker password (8 characters instead of 10), but we rather suggest you make the password just as strong (and different from!) the root password. After entering the details of these two users "root" and "you", the Debian installer will ask you how it can contact the Debian archives, in the dialoge "configure the package manager". For the NetInstall version of Debian, this is as good as mandatory. So here, we say "yes, use a Network Mirror", and in the following list select the country in which we are (in our case: the Netherlands), so the installer can present us with a number of network mirrors "close by". We select ftp.nl.debian.org. Next screen: should you be behind a proxy server, then it's possible to specify that here. And then the test: the system will say "scanning the mirror..." and try to contact the specified mirror. If it does not succeed, then there is either a network problem, a problem with this box's network card, or you've not specified the mirror or proxy correctly - so fix it. You'll know the network mirror has succesfully been contacted when the next dialogue appears - currently "configuring popularity-contest". Answer this question as you please. And then one of the last "big" questions: Software Selection. In this dialogue, you can easily select bundles of software to be installed. The choices are currently: * Desktop environment * Web server * Print server * DNS server * File server * Mail server * SQL database * Laptop * Standard system (selected by default) We have to make a little confession here: we've never before used this option in the installer. In fact, we even deselect the Standard System, so as to minimize the number of software packages that the base installation of our server contains. This makes it more work to manually add packages later, but we feel it gives us more control and understanding of our systems. So if you are like us: deselect the Standard System entry, and select Continue. The next dialogue handles the installation of the [http://www.gnu.org/software/grub/ ''grub'' bootloader]. Unless your disks weren't empty and you're attempting to make this system multiboot, you'll most likely get a question if you'll allow the installer to install ''grub'' into the boot sector of the first hard disk. We'll confirm with "Yes". After the installation of grub is completed, the CD-ROM is ejected, and the system is ready to reboot into Debian Etch. Remove the CD and select "Continue" ==Finishing up the installation== The system should reboot into Debian. This means you should see the following boot sequence: * your machine's standard POST messages * then, a blue grub menu on a black screen, with two entries: ** Debian GNU/Linux, kernel 2.6.&lt;something&gt; ** Debian GNU/Linux, kernel 2.6.&lt;something&gt (single-user mode); * then, after a default time-out, the first grub option will go into effect, and the Linux kernel is started. Lots of cryptic messages in grey-on-black will scroll by, until the last few lines read: "Debian GNU/Linux 4.0 &lt;hostname&gt; tty1" and "&lt;hostname&gt; login:" If your system does not reach this login, and/or some horrible error messages appear anywhere in this boot sequence, then you've got some extra work ahead. For now we'll assume you've reached the login prompt without problem. Log in as the principal user (try to avoid logging in as root! That's BAD practice!). Once logged in, save a copy of the boot messages using ''sudo dmesg > boot.txt'' or whatever you like. Then look through the boot messages, e.g. with ''vi -R boot.txt''. Furthermore, [[APT_and_aptitude | use Aptitude]] to make sure ''all'' your software is updated to the latest version. Done! Your base system is ready. You probably now want to [[essential system software | install essential software]], [[roll your own kernel]] and [[connect your server to the Internet]]. Furthermore, you might want to create a couple of [[aliases in every profile]] so that your favorite commands are always available. 1a66e52b4d347fef3843cc00936186cbf0e9928f 0 1587 2426 2009-07-25T18:59:04Z Saruman! 2 page started wikitext text/x-wiki The directories under Debian follow the [http://www.linuxfoundation.org/collaborate/workgroups/lsb LSB]. Under this standard, the following directories contain the described sort of data: /boot static files of the boot loader /home user home directories /tmp temporary files /usr static data /usr/local local hierarchy /var variable data /srv data for services provided by this system /opt add-on application software packages ec1be287c7cf8e6f582b52a0bc4914887e65a520 0 1467 2428 2005 2009-07-26T10:14:00Z Saruman! 2 split install and config wikitext text/x-wiki == OpenLDAP installation== Note: we're going to install OpenLDAP on our server as [http://www.openldap.org/doc/admin24/config.html#Local%20Directory%20Service the local directory service], without replication, referrals or other advanced features. Installing OpenLDAP on your Debian server is ridiculously simple. Just make sure your server is up-to-date (''sudo apt-get update'' followed by ''sudo apt-get upgrade''), and then install the two main components for your OpenLDAP server: sudo apt-get install slapd ldap-utils The Debian configuration script will ask you for only one single thing: an administrator password. As always: generate a strong password! When you've provided the password, the LDAP database is created with the administrator name "admin" and as a base directory path, something based on your DNS name. Suppose your internal domain is "amber.lan", then the script will generate ''suffix "dc=amber,dc=lan"''<ref>Should you see a third, empty, domain component (''dc='') then this is caused by a trailing dot in your particular DNS name: the DNS root. You might have specified your domain as "amber.lan.". You ''should'' change your domain name to a name without the DNS root, and you ''must'' regenerate your LDAP directory.</ref>. Since this might not always be the most convenient configuration, we recommend that you run the configuration again using ''dpkg-reconfigure slapd''. Interestingly enough, this reconfiguration asks you many ''more'' questions. The answers could look like this: omit OpenLDAP config: no DNS domain name: saruman.biz Organization name: Saruman Administrator passwd: wEt3udes Database backend: HDB DB remove after purge: no Move old DB: yes Allow LDAPv2: no As you can see, the reconfiguration yields much more configuration options than plain installation - although really you'll probably answer most questions with their default values anyway, with the exception of the database backend, which by default is BDB (see further down for the difference between BDB and HDB).<br> Anyway, the above method of configuring yields you an LDAP database with only two objects in it: * a single Organization (o="Saruman") with Distinguished Name dn="dc=saruman,dc=biz" * a single administrator with Common Name cn="admin", and dn="cn=admin,dc=saruman,dc=biz" The database that your OpenLDAP server uses is a standard Berkeley DB (BDB/HDB) database. Now we most likely will require some other databases as well in our server setup, something modern like PostgreSQL or MySQL - so why don't we configure our OpenLDAP to use this same database as well? For the answer, see [http://www.openldap.org/doc/admin24/intro.html#LDAP%20vs%20RDBMS here] - in short, the LDAP tree structure does not lend itself very well to inclusion in a modern relational database. Thus, we advise to stick with the Berkeley database provided with OpenLDAP. Now, for the database backend, we have the choice between two almost identical flavours: the ''bdb'' backend is the recommended primary backend for a normal slapd database. It uses the Oracle Berkeley DB package, referred to as ''BDB'', to store data. It makes extensive use of indexing and caching to speed data access. ''hdb'' is a variant of the ''bdb'' backend that uses a hierarchical database layout which supports subtree renames. It is otherwise identical to the ''bdb'' behavior, and all the same configuration options apply. <references/> ==OpenLDAP configuration== To finetune the OpenLDAP configuration, we make some changes to the main configuration file for the OpenLDAP server, ''/etc/ldap/slapd.conf''. Note: make SURE that the permissions on this file are rw-r----- (640) and the owner is ''root:openldap'', so that OpenLDAP can read the configuration, but only you can change it. We find the line beginning with "loglevel" and change it from ''none'' to ''256''. This value means connections/operations/results wil be logged to the ''syslogd'' daemon. There, it will be logged to the ''LOG_LOCAL4'' facility. The default hash algorithm for encrypting user passwords is {SSHA}, which is the SHA-1 algorithm (FIPS160-1) wit a seed number. However, OpenLDAP can understand more hashes, even multiple at the same time. To specify which hash or hashes, we can specify something like password-hash {SSHA} {MD5} Valid hashes are {SHA}, {SSHA} (the default), {MD5}, {SMD5}, {CRYPT} and {CLEARTEXT}. We usually don't need to change the default, but if you do, put in the directive and restart your LDAP server. More information: "man 5 slapd.conf". We find the line beginning with ''index'', and add a second line to it. This will make the section look like this: index objectClass eq index uid eq index memberUid eq The purpose of this change is to make the OpenLDAP server create another index, on LDAP attribute ''uid'', and another one on LDAP attribute ''memberUid''. The ''uid'' index is important, because under some circumstances you might not receive any result on a valid query unless the searched entries are indexed. This entry makes sure all objects with a ''uid'' attribute are indexed, and thus can be found when queried. The ''memberUid'' index is not so important, but creating it will prevent a lot of informational messages in our syslog that go like Nov 9 20:24:40 dworkin slapd[13998]: <= bdb_equality_candidates: (memberUid) not indexed Finally, we check to be certain all necessary schema's are included: in the beginning of the file we should see include /etc/ldap/schema/core.schema include /etc/ldap/schema/cosine.schema include /etc/ldap/schema/nis.schema include /etc/ldap/schema/inetorgperson.schema If any line got missing, we need to (re)enter it in order to be able to create the LDAP entries that we want. After these little refinements, we must stop, reindex, and restart the OpenLDAP server. This can be done with the following sequence of commands: sudo invoke-rc.d slapd stop sudo -u openldap slapindex sudo invoke-rc.d slapd start Note: you need to have your ''sudo'' configured to allow you to ''su'' to user ''openldap'' in order to run the second command. ==Installing and configuring an LDAP Account Manager== It's perfectly normal to manipulate your LDAP from the command line using LDAP utilities like ''ldapsearch'', ''ldapadd'', ''ldapdelete'' and ''ldapmodify'', as well as ''slapcat'', ''slappasswd'' etcetera. However, many people find a GUI for LDAP indispensible. If you are amongst those, then for you, my friend, the question becomes: which graphic tool do you want to use? Many people speak highly of ''[http://gq-project.org/ gq]'', ''[http://luma.sourceforge.net/about.html luma]'' and ''[http://phpldapadmin.sourceforge.net/ phpldapadmin]''. We go for ''lam'' ([http://lam.sourceforge.net/index.htm LDAP acount Manager]).<br> To install ''lam'', first ensure that you have installed Apache2 and PHP5. Then we can use ''apt-get install ldap-account-manager''. After installation, we can right away surf to http://<server-IP>/lam, where we can log in. However, note that in the upper right, there's a link ''LAM configuration''. We'll go there first. Under the LAM configuration page, there are two links to areas, where settings can be specified. The first one is "Edit general settings", and clicking it prompts you for a master password - by default this is "lam". Behind that password is a simple settings page, that can be filled with values like this ('''bold''' values deviate from the default): * Security settings ** Session timeout: '''15''' (the amount of minutes of inactivity that's allowed before a user is logged off) ** Allowed hosts: '''192.168.67.*''' (the range of IP numbers from which LAM accepts connections; empty would mean "all" so we recommend limiting the scope to your internal network, or even less if possible. Multiple hosts or network ranges can be inserted below each other) * Password policy (in this section you can specify lower limits on your LDAP passwords - tho currently it's not clear to us what you're limiting. We suspect it's the creation of all LDAP passwords from within LAM). ** Minimum password length: '''6''' ** Minimum lowercase characters: 0 ** Minimum uppercase characters: 0 ** Minimum numeric characters: 0 ** Minimum symbolic characters: 0 ** Minimum character classes: '''3''' (The character classes are: lowercase, uppercase, numeric and symbols) * Logging ** Log level: notice (this is the most detailed level; "warning" logs less information, "error" less still) ** Log destination: syslog (outputs all LAM messages to the syslogger; alternatively specify "no logging" or a file name & location) * Change master password ** New master password: '''*****''' (this is the password that'll replace "lam" to log into the LAM configuration; it is NOT the password of your rootdn, and if anywhere possible, you should avoid using that particular password here - for safety. Generate [http://www.pctools.com/guides/password/ yet another strong password].) ** Reenter new master password: '''*****''' After entering the above settings, we at least know LAM is operational, and coarsely secured (it's not using SSL yet). Click ''OK'' to save, or ''back to login'' if you change your mind and just want to go back. The second link from the LAM configuration page, "Edit server profiles" will again prompt you. However, this password prompt page contains an extra pulldown option, currently filled with the word "lam". This is because there is only one server profile, named "lam", and filled with some default values for your LDAP server. And under those two boxes, there's a link "manage server profiles".<br> Now first we'll rename that profile to something more descriptive. Click the "manage server profiles" link, in the "profile management page" check the radio button next to ''&#091;lam&#093; Rename profile'', put in the new name (e.g. "sarumanbiz"), fill in the shiny new master LAM password &#8212; it should no longer be the default "lam" since you've changed it, in line with the paragraph above :-) &#8212; and then click OK. Presto! The server profile is renamed.<br> When you now enter your password to edit the server preferences for profile "sarumanbiz", you get to a page with a lot of settings; the only ones we're currently interested in are: * Server settings ** Server address: ldap://localhost:389 (verify that it's either localhost, if both the LDAP server and your LAM Apache2 are on the same machine, or a correct IP address or DNS name if that's not the case) ** Tree Suffix: '''dc=saruman,dc=biz''' (the same suffix you've installed your LDAP server with) * Account types ** Edit Account types *** Users **** LDAP Suffix: '''ou=people,dc=saruman,dc=biz''' (You'll have to designate an OU in which to store user accounts; it does not have to exist yet (LAM can create it for you any time you log in) but the base has to be accessible; in our example: saruman.biz. Any name will do, but since we're storing identities, and not specifically users, we're calling the OU "people") *** Groups **** LDAP Suffix: '''ou=groups,dc=saruman,dc=biz''' (This is the OU where groups will be stored) *** Hosts **** LDAP Suffix: '''ou=hosts,dc=saruman,dc=biz''' (This is where machines, i.e. hosts, will be stored) *** Samba domains **** LDAP Suffix: '''ou=domains,dc=saruman,dc=biz''' (This is where all Windows workgroups/domains will wind up) * Security settings ** List of valid users: '''cn=admin,dc=saruman,dc=biz''' (or whatever you've designated your root DN) ** New password: '''''leave empty''''' (because this is to change the master password to edit ''this'' server profile; when this remains empty, the "master master password" for LAM remains in effect) ** Reenter password: (make this the same as the new password, i.e. empty) Now click OK, and your LAM should be ready to go. When you first log into the LAM profile you've just created, LAM will ask you if it should create the four OU's you've designated for people/groups/machines/domains. This is a nice test: if LAM cannot create those OU's, then you've misconfigured it (or the LDAP tree itself). If it can, then you'll be able to click ''tree view'' and browse the LDAP tree. At least the administrator (e.g. cn=admin) and the four OU's (e.g. domains/groups/hosts/people) should be present under the root (e.g. dc=saruman,dc=biz).<br> Incidentally, the configuration you've just entered into LAM as profile "sarumanbiz" can also be found at ''/usr/share/ldap-account-manager/config/sarumanbiz.conf'', so if need be, you can edit the profile by hand. ==Securing LAM communications with SSL== Until just now, all communications with LAM have taken place over unencrypted connections - not a nice way to work in a production environment. We really need to use SSL to secure the LAM environment. Fortunately, that is as easy as enabling SSL on the underlying Apache2 webserver. ==Where to go from here== This completes the setup of the LDAP server. * To fill it with relevant data, go to [[Filling an OpenLDAP database | the next section]]. * To set your system to accept LDAP users logging in to the machine, [[Accessing_a_shell_with_LDAP_authentication | go here]]. be3343c90071ae06e27d22c3524d6cb855eb8c04 2432 2428 2009-07-26T16:16:07Z Saruman! 2 /* OpenLDAP configuration */ divided global and backend directives wikitext text/x-wiki == OpenLDAP installation== Note: we're going to install OpenLDAP on our server as [http://www.openldap.org/doc/admin24/config.html#Local%20Directory%20Service the local directory service], without replication, referrals or other advanced features. Installing OpenLDAP on your Debian server is ridiculously simple. Just make sure your server is up-to-date (''sudo apt-get update'' followed by ''sudo apt-get upgrade''), and then install the two main components for your OpenLDAP server: sudo apt-get install slapd ldap-utils The Debian configuration script will ask you for only one single thing: an administrator password. As always: generate a strong password! When you've provided the password, the LDAP database is created with the administrator name "admin" and as a base directory path, something based on your DNS name. Suppose your internal domain is "amber.lan", then the script will generate ''suffix "dc=amber,dc=lan"''<ref>Should you see a third, empty, domain component (''dc='') then this is caused by a trailing dot in your particular DNS name: the DNS root. You might have specified your domain as "amber.lan.". You ''should'' change your domain name to a name without the DNS root, and you ''must'' regenerate your LDAP directory.</ref>. Since this might not always be the most convenient configuration, we recommend that you run the configuration again using ''dpkg-reconfigure slapd''. Interestingly enough, this reconfiguration asks you many ''more'' questions. The answers could look like this: omit OpenLDAP config: no DNS domain name: saruman.biz Organization name: Saruman Administrator passwd: wEt3udes Database backend: HDB DB remove after purge: no Move old DB: yes Allow LDAPv2: no As you can see, the reconfiguration yields much more configuration options than plain installation - although really you'll probably answer most questions with their default values anyway, with the exception of the database backend, which by default is BDB (see further down for the difference between BDB and HDB).<br> Anyway, the above method of configuring yields you an LDAP database with only two objects in it: * a single Organization (o="Saruman") with Distinguished Name dn="dc=saruman,dc=biz" * a single administrator with Common Name cn="admin", and dn="cn=admin,dc=saruman,dc=biz" The database that your OpenLDAP server uses is a standard Berkeley DB (BDB/HDB) database. Now we most likely will require some other databases as well in our server setup, something modern like PostgreSQL or MySQL - so why don't we configure our OpenLDAP to use this same database as well? For the answer, see [http://www.openldap.org/doc/admin24/intro.html#LDAP%20vs%20RDBMS here] - in short, the LDAP tree structure does not lend itself very well to inclusion in a modern relational database. Thus, we advise to stick with the Berkeley database provided with OpenLDAP. Now, for the database backend, we have the choice between two almost identical flavours: the ''bdb'' backend is the recommended primary backend for a normal slapd database. It uses the Oracle Berkeley DB package, referred to as ''BDB'', to store data. It makes extensive use of indexing and caching to speed data access. ''hdb'' is a variant of the ''bdb'' backend that uses a hierarchical database layout which supports subtree renames. It is otherwise identical to the ''bdb'' behavior, and all the same configuration options apply. <references/> ==OpenLDAP configuration== To finetune the OpenLDAP configuration, we make some changes to the main configuration file for the OpenLDAP server, ''/etc/ldap/slapd.conf''. Note: make SURE that the permissions on this file are rw-r----- (640) and the owner is ''root:openldap'', so that OpenLDAP can read the configuration, but only you can change it. When changing the configuration of your LDAP server, keep in mind that everything ''above'' the first ''backend hdb'' (or ''backend <something>'') should contain only global directives, and everything under it only backend directives that will apply to all databases that you're going to run under that backend type. In our examples, we're only going to run a single database of a single backend type, so all backend directives will apply to our single database. Nevertheless, you should put your global directives above the backend declaration, and the rest below. ===global directives=== We check to be certain all necessary '''schemas''' are included: in the beginning of the file we should see include /etc/ldap/schema/core.schema include /etc/ldap/schema/cosine.schema include /etc/ldap/schema/nis.schema include /etc/ldap/schema/inetorgperson.schema If any line got missing, we need to (re)enter it in order to be able to create the LDAP entries that we want. We find the line beginning with '''loglevel''' and change it from ''none'' to ''256''. This value means connections/operations/results wil be logged to the ''syslogd'' daemon. There, it will be logged to the ''LOG_LOCAL4'' facility. The default hash algorithm for '''encrypting user passwords''' is {SSHA}, which is the SHA-1 algorithm (FIPS160-1) wit a seed number. However, OpenLDAP can understand more hashes, even multiple at the same time. To specify which hash or hashes, we can specify something like password-hash {SSHA} password-hash {MD5} Valid hashes are {SHA}, {SSHA} (the default), {MD5}, {SMD5}, {CRYPT} and {CLEARTEXT}. We usually don't need to change the default, but if you do, put in the directive and restart your LDAP server. More information: "man 5 slapd.conf". ===backend directives=== We find the line beginning with ''index'', and add one or more lines under it, containing the attributes that we would like to be indexed. For starters, we would advise you to index not only ''objectClass'', but also ''uid'' and ''memberUid''. This will make the section look like this: index objectClass eq index uid eq index memberUid eq The purpose of this change is to make the OpenLDAP server create another index, on LDAP attribute ''uid'', and another one on LDAP attribute ''memberUid''. The ''uid'' index is important, because under some circumstances you might not receive any result on a valid query unless the searched entries are indexed. This entry makes sure all objects with a ''uid'' attribute are indexed, and thus can be found when queried. The ''memberUid'' index is not so important, but creating it will prevent a lot of informational messages in our syslog that go like Nov 9 10:24:40 dworkin slapd[13998]: <= bdb_equality_candidates: (memberUid) not indexed After these little refinements, we must stop, reindex, and restart the OpenLDAP server. This can be done with the following sequence of commands: sudo invoke-rc.d slapd stop sudo -u openldap slapindex sudo invoke-rc.d slapd start Note: you need to have your ''sudo'' configured to allow you to ''su'' to user ''openldap'' in order to run the second command. ==Installing and configuring an LDAP Account Manager== It's perfectly normal to manipulate your LDAP from the command line using LDAP utilities like ''ldapsearch'', ''ldapadd'', ''ldapdelete'' and ''ldapmodify'', as well as ''slapcat'', ''slappasswd'' etcetera. However, many people find a GUI for LDAP indispensible. If you are amongst those, then for you, my friend, the question becomes: which graphic tool do you want to use? Many people speak highly of ''[http://gq-project.org/ gq]'', ''[http://luma.sourceforge.net/about.html luma]'' and ''[http://phpldapadmin.sourceforge.net/ phpldapadmin]''. We go for ''lam'' ([http://lam.sourceforge.net/index.htm LDAP acount Manager]).<br> To install ''lam'', first ensure that you have installed Apache2 and PHP5. Then we can use ''apt-get install ldap-account-manager''. After installation, we can right away surf to http://<server-IP>/lam, where we can log in. However, note that in the upper right, there's a link ''LAM configuration''. We'll go there first. Under the LAM configuration page, there are two links to areas, where settings can be specified. The first one is "Edit general settings", and clicking it prompts you for a master password - by default this is "lam". Behind that password is a simple settings page, that can be filled with values like this ('''bold''' values deviate from the default): * Security settings ** Session timeout: '''15''' (the amount of minutes of inactivity that's allowed before a user is logged off) ** Allowed hosts: '''192.168.67.*''' (the range of IP numbers from which LAM accepts connections; empty would mean "all" so we recommend limiting the scope to your internal network, or even less if possible. Multiple hosts or network ranges can be inserted below each other) * Password policy (in this section you can specify lower limits on your LDAP passwords - tho currently it's not clear to us what you're limiting. We suspect it's the creation of all LDAP passwords from within LAM). ** Minimum password length: '''6''' ** Minimum lowercase characters: 0 ** Minimum uppercase characters: 0 ** Minimum numeric characters: 0 ** Minimum symbolic characters: 0 ** Minimum character classes: '''3''' (The character classes are: lowercase, uppercase, numeric and symbols) * Logging ** Log level: notice (this is the most detailed level; "warning" logs less information, "error" less still) ** Log destination: syslog (outputs all LAM messages to the syslogger; alternatively specify "no logging" or a file name & location) * Change master password ** New master password: '''*****''' (this is the password that'll replace "lam" to log into the LAM configuration; it is NOT the password of your rootdn, and if anywhere possible, you should avoid using that particular password here - for safety. Generate [http://www.pctools.com/guides/password/ yet another strong password].) ** Reenter new master password: '''*****''' After entering the above settings, we at least know LAM is operational, and coarsely secured (it's not using SSL yet). Click ''OK'' to save, or ''back to login'' if you change your mind and just want to go back. The second link from the LAM configuration page, "Edit server profiles" will again prompt you. However, this password prompt page contains an extra pulldown option, currently filled with the word "lam". This is because there is only one server profile, named "lam", and filled with some default values for your LDAP server. And under those two boxes, there's a link "manage server profiles".<br> Now first we'll rename that profile to something more descriptive. Click the "manage server profiles" link, in the "profile management page" check the radio button next to ''&#091;lam&#093; Rename profile'', put in the new name (e.g. "sarumanbiz"), fill in the shiny new master LAM password &#8212; it should no longer be the default "lam" since you've changed it, in line with the paragraph above :-) &#8212; and then click OK. Presto! The server profile is renamed.<br> When you now enter your password to edit the server preferences for profile "sarumanbiz", you get to a page with a lot of settings; the only ones we're currently interested in are: * Server settings ** Server address: ldap://localhost:389 (verify that it's either localhost, if both the LDAP server and your LAM Apache2 are on the same machine, or a correct IP address or DNS name if that's not the case) ** Tree Suffix: '''dc=saruman,dc=biz''' (the same suffix you've installed your LDAP server with) * Account types ** Edit Account types *** Users **** LDAP Suffix: '''ou=people,dc=saruman,dc=biz''' (You'll have to designate an OU in which to store user accounts; it does not have to exist yet (LAM can create it for you any time you log in) but the base has to be accessible; in our example: saruman.biz. Any name will do, but since we're storing identities, and not specifically users, we're calling the OU "people") *** Groups **** LDAP Suffix: '''ou=groups,dc=saruman,dc=biz''' (This is the OU where groups will be stored) *** Hosts **** LDAP Suffix: '''ou=hosts,dc=saruman,dc=biz''' (This is where machines, i.e. hosts, will be stored) *** Samba domains **** LDAP Suffix: '''ou=domains,dc=saruman,dc=biz''' (This is where all Windows workgroups/domains will wind up) * Security settings ** List of valid users: '''cn=admin,dc=saruman,dc=biz''' (or whatever you've designated your root DN) ** New password: '''''leave empty''''' (because this is to change the master password to edit ''this'' server profile; when this remains empty, the "master master password" for LAM remains in effect) ** Reenter password: (make this the same as the new password, i.e. empty) Now click OK, and your LAM should be ready to go. When you first log into the LAM profile you've just created, LAM will ask you if it should create the four OU's you've designated for people/groups/machines/domains. This is a nice test: if LAM cannot create those OU's, then you've misconfigured it (or the LDAP tree itself). If it can, then you'll be able to click ''tree view'' and browse the LDAP tree. At least the administrator (e.g. cn=admin) and the four OU's (e.g. domains/groups/hosts/people) should be present under the root (e.g. dc=saruman,dc=biz).<br> Incidentally, the configuration you've just entered into LAM as profile "sarumanbiz" can also be found at ''/usr/share/ldap-account-manager/config/sarumanbiz.conf'', so if need be, you can edit the profile by hand. ==Securing LAM communications with SSL== Until just now, all communications with LAM have taken place over unencrypted connections - not a nice way to work in a production environment. We really need to use SSL to secure the LAM environment. Fortunately, that is as easy as enabling SSL on the underlying Apache2 webserver. ==Where to go from here== This completes the setup of the LDAP server. * To fill it with relevant data, go to [[Filling an OpenLDAP database | the next section]]. * To set your system to accept LDAP users logging in to the machine, [[Accessing_a_shell_with_LDAP_authentication | go here]]. 8a9cf06fef9dfa8fdba749d933799fc03ea4b425 0 1588 2430 2009-07-26T11:00:43Z Saruman! 2 page started wikitext text/x-wiki ==Aliases in general== One of the fun little things of Linux is the ability to create your own aliases for commands that you often need. You can set an alias like this: alias more='less' This has the effect of intercepting any command entries for ''more'', substituting ''less''. Thus the alias makes sure that when you type ''more'', you get the ''less'' command executed instead. This works because the shell keeps the list of aliases at hand, and substitutes your specified aliases at execution time.<br> Note: if you also have the ''more'' command installed, then you cannot get to the ''more'' command any more. And note that - in a completely opposite fashion - your aliases are local to your shell, and are not passed down to programs or to other shells. Thus, a script that needs to run ''more'' will not get confused by your alias - it will not use ''less'' instead. Should you want to know which aliases are in effect, simply run alias Should you want to know what commands you have stored under a particular alias, just run that: alias more The above use of aliases is very trivial; it gets better if you add parameters to the alias. And to top it off, you can also use (environment) variables. For example: alias ls='ls $LS_OPTIONS -lAF' will make command ''ls'' use bot the value of $LS_OPTIONS (usually something like ''--color=auto'') and the ''-lAF'' parameters. Finally, you can have a single alias run multiple commands, separated with semicolons, pipes et cetera. Suppose you often want to know what processes are running with the credentials of web-user ''www-data'': alias psw='ps -ef | grep www-data' Try it :-) ==Aliases in profiles== Every time you set an alias, it is known only in that particular shell. Once you exit that shell, the aliases you've so carefully set are gone forever and ever! Of course, there is a way to preserve your work: set the aliases in one of your profile files. ==Our favorite aliases== This is a list of the aliases that we like so much that we put them on every one of our boxes, at the end of ''/etc/profile'' eval "`dircolors`" alias l='ls $LS_OPTIONS -lAF' alias ts='multitail /var/log/syslog' alias tf='tail -fn40 /var/log/ulog/syslogemu.log | ccze' alias tm='tail -fn40 /var/appslog/mail/mail.log | ccze' You can probably guess the meaning of the aliases from their commands, but in case not: * '''l''' - list in our favorite output form * '''ts''' - tail syslog * '''tf''' - tail firewall log * '''tm''' = tail mail log 304af31e89f0928f96b3e7b0441eb2f96ee0ddd0 2431 2430 2009-07-26T11:59:00Z 212.238.151.172 0 finished up profiles wikitext text/x-wiki ==Aliases in general== One of the fun little things of Linux is the ability to create your own aliases for commands that you often need. You can set an alias like this: alias more='less' This has the effect of intercepting any command entries for ''more'', substituting ''less''. Thus the alias makes sure that when you type ''more'', you get the ''less'' command executed instead. This works because the shell keeps the list of aliases at hand, and substitutes your specified aliases at execution time.<br> Note: if you also have the ''more'' command installed, then you cannot get to the ''more'' command any more. And note that - in a completely opposite fashion - your aliases are local to your shell, and are not passed down to programs or to other shells. Thus, a script that needs to run ''more'' will not get confused by your alias - it will not use ''less'' instead. Should you want to know which aliases are in effect, simply run alias Should you want to know what commands you have stored under a particular alias, just run that: alias more The above use of aliases is very trivial; it gets better if you add parameters to the alias. And to top it off, you can also use (environment) variables. For example: alias ls='ls $LS_OPTIONS -lAF' will make command ''ls'' use bot the value of $LS_OPTIONS (usually something like ''--color=auto'') and the ''-lAF'' parameters. Finally, you can have a single alias run multiple commands, separated with semicolons, pipes et cetera. Suppose you often want to know what processes are running with the credentials of web-user ''www-data'': alias psw='ps -ef | grep www-data' Try it :-) ==Aliases in profiles== Every time you set an alias, it is known only in that particular shell. Once you exit that shell, the aliases you've so carefully set are gone forever and ever! Of course, there is a way to preserve your work: set the aliases in one of your profile files (''~/.bash_profile'', ''~/.profile'' et cetera). However, you can also put aliases in one of the system-wide profile files: ''/etc/profile'' or ''/etc/bash.bashrc''. Especially the latter is suitable, as it is meant to hold functions and aliases. However, if you also want to have the aliases available when you log in remotely, you should either put the aliases in ''/etc/profile'', or have ''/etc/bash.bashrc'' sourced from ''/etc/profile''. ==Our favorite aliases== This is a list of the aliases that we like so much that we put them on every one of our boxes, at the end of ''/etc/bash.bashrc'' (which we have sourced from ''/etc/profile''): eval "`dircolors`" alias l='ls $LS_OPTIONS -lAF' alias ts='multitail /var/log/syslog' alias tf='tail -fn40 /var/log/ulog/syslogemu.log | ccze' alias tm='tail -fn40 /var/appslog/mail/mail.log | ccze' You can probably guess the meaning of the aliases from their commands, but in case not: * '''l''' - list in our favorite output form * '''ts''' - tail syslog * '''tf''' - tail firewall log * '''tm''' = tail mail log 019180a11bd882ddb20505bf0a00e5caabc97ec2 0 1434 2433 2397 2009-08-03T20:50:03Z Saruman! 2 /* Extra configuration */ added performance tricks wikitext text/x-wiki ==Installation of MediaWiki== Here we have the [[Basic MediaWiki Installation|basic installation]] of [http://www.mediawiki.org/ MediaWiki] outlined for you. The default installation will create your wiki in subdirectory ''/mediawiki''. Should you wish to have another name, e.g. ''<nowiki>http://www.yourserver.com/wiki</nowiki>'', then you must make [[Change MediaWiki subpath|two changes]]. ==Extra configuration== After installation of MediaWiki, your Wiki is available on ''every'' Virtual Host you run - unless you follow the instructions to [[place MediaWiki inside a Virtual Host]]. An extra feature we added was support for iFrames by means of a little PHP script that we googled; the extension is called [[The websiteFrame PHP extension| websiteFrame.php]]. Furthermore, we [[wiki footer change |changed the Creative Commons picture]] in the footer from a remote one to a local one. For performance, the following tricks can be used (which we found on [http://mituzas.lt/2007/01/26/mediawiki-performance-tuning this site]): * <pre>apt-get install php-apc</pre> to install a PHP accelerator; * add ''$wgMainCacheType = CACHE_ACCEL;'' (instead of ''CACHE_NONE'') into ''LocalSettings.php'' to enable that installed APC PHP accelerator; * add ''$wgDisableCounters = true;'' into ''LocalSettings.php'' to disable the page counters. On the example site referenced, the cache reduced rendering of an (almost empty) main page from 217ms to 50ms; disabling the page view counter took off another 10ms. ==Extensions== One of the nice things about using something as popular as MediaWiki is the availability of a great number of [http://www.mediawiki.org/wiki/Manual:Extensions extensions]. One of the first things to do, therefor, is to [[mediawiki-extensions under Debian| install the default Debian Mediawiki Extensions package]]. For user management, we added the extensions [[MediaWikiExtension_Password_Reset | Password Reset]] and [[MediaWiki_Extension_-_GroupPermissionsManager | Group Permissions Manager]]. A feature we needed to gain experience for another project was the [http://semantic-mediawiki.org/wiki/Semantic_MediaWiki Semantic MediaWiki (SMW)] extension; it also has a pretty [[Semantic MediaWiki under Debian | simple installation]]. ==Multiple Wiki's on a single server== Some people want to run multiple Wiki instances on one single server - especially so if that server runs multiple websites (the forementioned [[place MediaWiki inside a Virtual Host|Virtual Hosts]]). The answer to that is to [[Create a Wikifarm | create a Wikifarm]].<br> Note that we've set up a [http://www.mediawikifarm.nl/wiki/index.php/Main_Page separate site] for this problem - you're welcome there with any questions you might have on wikifarms on Debian. 9aa3690ae57cd811cacd8c9f0f9fbf20f503d9f9 2442 2433 2009-08-27T19:59:14Z Saruman! 2 added user rights wikitext text/x-wiki ==Installation of MediaWiki== Here we have the [[Basic MediaWiki Installation|basic installation]] of [http://www.mediawiki.org/ MediaWiki] outlined for you. The default installation will create your wiki in subdirectory ''/mediawiki''. Should you wish to have another name, e.g. ''<nowiki>http://www.yourserver.com/wiki</nowiki>'', then you must make [[Change MediaWiki subpath|two changes]]. ==Extra configuration== After installation of MediaWiki, your Wiki is available on ''every'' Virtual Host you run - unless you follow the instructions to [[place MediaWiki inside a Virtual Host]]. An extra feature we added was support for iFrames by means of a little PHP script that we googled; the extension is called [[The websiteFrame PHP extension| websiteFrame.php]]. Furthermore, we [[wiki footer change |changed the Creative Commons picture]] in the footer from a remote one to a local one. For performance, the following tricks can be used (which we found on [http://mituzas.lt/2007/01/26/mediawiki-performance-tuning this site]): * <pre>apt-get install php-apc</pre> to install a PHP accelerator; * add ''$wgMainCacheType = CACHE_ACCEL;'' (instead of ''CACHE_NONE'') into ''LocalSettings.php'' to enable that installed APC PHP accelerator; * add ''$wgDisableCounters = true;'' into ''LocalSettings.php'' to disable the page counters. On the example site referenced, the cache reduced rendering of an (almost empty) main page from 217ms to 50ms; disabling the page view counter took off another 10ms. ==Extensions== One of the nice things about using something as popular as MediaWiki is the availability of a great number of [http://www.mediawiki.org/wiki/Manual:Extensions extensions]. One of the first things to do, therefor, is to [[mediawiki-extensions under Debian| install the default Debian Mediawiki Extensions package]]. For user management, we added the extensions [[MediaWikiExtension_Password_Reset | Password Reset]] and [[MediaWiki_Extension_-_GroupPermissionsManager | Group Permissions Manager]]. A feature we needed to gain experience for another project was the [http://semantic-mediawiki.org/wiki/Semantic_MediaWiki Semantic MediaWiki (SMW)] extension; it also has a pretty [[Semantic MediaWiki under Debian | simple installation]]. ==Multiple Wiki's on a single server== Some people want to run multiple Wiki instances on one single server - especially so if that server runs multiple websites (the forementioned [[place MediaWiki inside a Virtual Host|Virtual Hosts]]). The answer to that is to [[Create a Wikifarm | create a Wikifarm]].<br> Note that we've set up a [http://www.mediawikifarm.nl/wiki/index.php/Main_Page separate site] for this problem - you're welcome there with any questions you might have on wikifarms on Debian. ==User Rights management== The MediaWiki documentation quite clearly documents [http://www.mediawiki.org/wiki/Manual:$wgGroupPermissions how to manage user rights], but here is a very quick recap: The following user rights are granted implicitly to non-logged-in users: // Implicit group for all visitors $wgGroupPermissions['*' ]['createaccount'] = true; // 1.5.0 $wgGroupPermissions['*' ]['read'] = true; // 1.5.0 $wgGroupPermissions['*' ]['edit'] = true; // 1.5.0 $wgGroupPermissions['*' ]['createpage'] = true; // 1.6.0 $wgGroupPermissions['*' ]['createtalk'] = true; // 1.6.0 So if you want to limit the rights of anonymous users, paste these lines into ''LocalSettings.php'' and change to false those rights that you want to take away. e.g. if you do not want anonymous users to edit pages, set the 'edit' permission to false. Setting 'read' to false requires users to log in before they can read your wiki (but they can still see the sidebar!) The following rights are implicitly granted to all logged-in users. // Implicit group for all logged-in accounts $wgGroupPermissions['user' ]['move'] = true; // 1.5.0 $wgGroupPermissions['user' ]['read'] = true; // 1.5.0 $wgGroupPermissions['user' ]['edit'] = true; // 1.5.0 $wgGroupPermissions['user' ]['createpage'] = true; // 1.6.0 $wgGroupPermissions['user' ]['createtalk'] = true; // 1.6.0 $wgGroupPermissions['user' ]['upload'] = true; // 1.5.0 $wgGroupPermissions['user' ]['reupload'] = true; // 1.6.0 $wgGroupPermissions['user' ]['reupload-shared'] = true; // 1.6.0 $wgGroupPermissions['user' ]['minoredit'] = true; // 1.6.0 $wgGroupPermissions['user' ]['purge'] = true; // 1.10.0 '''NOTE:''' you '''cannot''' let normal users keep a right like 'edit' and take it away for a special group that you create, like 'students'. You MUST grant the group 'user' the ''fewest'' rights that anyone should have, grant extra rights to other groups, and place the right users in these other groups. Examples: $wgGroupPermissions['student' ]['edit'] = false; // WILL NOT WORK The above will NOT "give everyone edit rights except for students". $wgGroupPermissions['*' ]['edit'] = false; // $wgGroupPermissions['user' ]['edit'] = false; // explicitly take away edit from all logged-in users $wgGroupPermissions['staff' ]['edit'] = true; // then give back edit to everyone except standard $wgGroupPermissions['visitingstaff' ]['edit'] = true; // users This WILL work: the edit right is taken away from everyone, including students, untill that right is explicitly restored. Just restore it to the necessary groups, taking care not to restore it to 'students'. So if you want to grant everyone 'edit' except for a particular account - sorry, don't know how that'd work. cee085c60d6b8884e853a2d91edce88c29641fd9 2445 2442 2009-08-29T07:28:43Z Saruman! 2 /* Extra configuration */ link to skinning wikitext text/x-wiki ==Installation of MediaWiki== Here we have the [[Basic MediaWiki Installation|basic installation]] of [http://www.mediawiki.org/ MediaWiki] outlined for you. The default installation will create your wiki in subdirectory ''/mediawiki''. Should you wish to have another name, e.g. ''<nowiki>http://www.yourserver.com/wiki</nowiki>'', then you must make [[Change MediaWiki subpath|two changes]]. ==Extra configuration== After installation of MediaWiki, your Wiki is available on ''every'' Virtual Host you run - unless you follow the instructions to [[place MediaWiki inside a Virtual Host]]. An extra feature we added was support for iFrames by means of a little PHP script that we googled; the extension is called [[The websiteFrame PHP extension| websiteFrame.php]]. Furthermore, we [[wiki footer change |changed the Creative Commons picture]] in the footer from a remote one to a local one. For performance, the following tricks can be used (which we found on [http://mituzas.lt/2007/01/26/mediawiki-performance-tuning this site]): * <pre>apt-get install php-apc</pre> to install a PHP accelerator; * add ''$wgMainCacheType = CACHE_ACCEL;'' (instead of ''CACHE_NONE'') into ''LocalSettings.php'' to enable that installed APC PHP accelerator; * add ''$wgDisableCounters = true;'' into ''LocalSettings.php'' to disable the page counters. On the example site referenced, the cache reduced rendering of an (almost empty) main page from 217ms to 50ms; disabling the page view counter took off another 10ms. Should you wish to customize the look of your MediaWiki wiki, then you must [[MediaWiki skinning|edit the MediaWiki skins]]. ==Extensions== One of the nice things about using something as popular as MediaWiki is the availability of a great number of [http://www.mediawiki.org/wiki/Manual:Extensions extensions]. One of the first things to do, therefor, is to [[mediawiki-extensions under Debian| install the default Debian Mediawiki Extensions package]]. For user management, we added the extensions [[MediaWikiExtension_Password_Reset | Password Reset]] and [[MediaWiki_Extension_-_GroupPermissionsManager | Group Permissions Manager]]. A feature we needed to gain experience for another project was the [http://semantic-mediawiki.org/wiki/Semantic_MediaWiki Semantic MediaWiki (SMW)] extension; it also has a pretty [[Semantic MediaWiki under Debian | simple installation]]. ==Multiple Wiki's on a single server== Some people want to run multiple Wiki instances on one single server - especially so if that server runs multiple websites (the forementioned [[place MediaWiki inside a Virtual Host|Virtual Hosts]]). The answer to that is to [[Create a Wikifarm | create a Wikifarm]].<br> Note that we've set up a [http://www.mediawikifarm.nl/wiki/index.php/Main_Page separate site] for this problem - you're welcome there with any questions you might have on wikifarms on Debian. ==User Rights management== The MediaWiki documentation quite clearly documents [http://www.mediawiki.org/wiki/Manual:$wgGroupPermissions how to manage user rights], but here is a very quick recap: The following user rights are granted implicitly to non-logged-in users: // Implicit group for all visitors $wgGroupPermissions['*' ]['createaccount'] = true; // 1.5.0 $wgGroupPermissions['*' ]['read'] = true; // 1.5.0 $wgGroupPermissions['*' ]['edit'] = true; // 1.5.0 $wgGroupPermissions['*' ]['createpage'] = true; // 1.6.0 $wgGroupPermissions['*' ]['createtalk'] = true; // 1.6.0 So if you want to limit the rights of anonymous users, paste these lines into ''LocalSettings.php'' and change to false those rights that you want to take away. e.g. if you do not want anonymous users to edit pages, set the 'edit' permission to false. Setting 'read' to false requires users to log in before they can read your wiki (but they can still see the sidebar!) The following rights are implicitly granted to all logged-in users. // Implicit group for all logged-in accounts $wgGroupPermissions['user' ]['move'] = true; // 1.5.0 $wgGroupPermissions['user' ]['read'] = true; // 1.5.0 $wgGroupPermissions['user' ]['edit'] = true; // 1.5.0 $wgGroupPermissions['user' ]['createpage'] = true; // 1.6.0 $wgGroupPermissions['user' ]['createtalk'] = true; // 1.6.0 $wgGroupPermissions['user' ]['upload'] = true; // 1.5.0 $wgGroupPermissions['user' ]['reupload'] = true; // 1.6.0 $wgGroupPermissions['user' ]['reupload-shared'] = true; // 1.6.0 $wgGroupPermissions['user' ]['minoredit'] = true; // 1.6.0 $wgGroupPermissions['user' ]['purge'] = true; // 1.10.0 '''NOTE:''' you '''cannot''' let normal users keep a right like 'edit' and take it away for a special group that you create, like 'students'. You MUST grant the group 'user' the ''fewest'' rights that anyone should have, grant extra rights to other groups, and place the right users in these other groups. Examples: $wgGroupPermissions['student' ]['edit'] = false; // WILL NOT WORK The above will NOT "give everyone edit rights except for students". $wgGroupPermissions['*' ]['edit'] = false; // $wgGroupPermissions['user' ]['edit'] = false; // explicitly take away edit from all logged-in users $wgGroupPermissions['staff' ]['edit'] = true; // then give back edit to everyone except standard $wgGroupPermissions['visitingstaff' ]['edit'] = true; // users This WILL work: the edit right is taken away from everyone, including students, untill that right is explicitly restored. Just restore it to the necessary groups, taking care not to restore it to 'students'. So if you want to grant everyone 'edit' except for a particular account - sorry, don't know how that'd work. 5b6ddaf9051b01a8976d3f0f5451cb7768c1e66e 0 1507 2436 2400 2009-08-19T06:00:42Z Saruman! 2 /* Configuration of Apache2 */ mail address fix wikitext text/x-wiki ==Apache2== ===Installation of Apache2=== Installation of Apache2 is quite simple: apt-get install apache2 This brings a slew of packages, a.o. ''apache2-mpm-worker'', ''apache2-utils'', ''libapr1'' et cetera. When you want a different worker (e.g. , you should use ''aptitude'' to select that different worker (prefork etc.). ===Configuration of Apache2=== Once Apache2 is in place, you might want to [[Enabling SSL for Apache2 | enable SSL]] for it. Furthermore, you have to realise that mail sent by your webserver, or any PHP program running under it (e.g. MediaWiki) will have the envelope sender address of www-data@<your.maildomain>. To make sure that your maildomain is actually a real mail domain (necessary for reverse lookup, which is something that real mail servers do), you have to take care to put the right mail domain in ''/etc/mailname'' (e.g. "saruman.biz"). Furthermore, at the top of your Postfix ''main.cf'' you might like to add myorigin = /etc/mailname If you now restart Postfix, outgoing mail from user ''www-data'' will have an envelope sender address of ''www-data@saruman.biz'' ==Installation of PHP5== Installing PHP5 is as easy as sudo apt-get install php5 php5-cli Note that if you had installed Apache2 module ''apache2-mpm-worker'', it will get replaced with ''apache2-mpm-prefork''. Furthermore, note that ''php5-cli'' is only needed if you want to run PHP commands at the prompt - but our guess is that you want it (e.g. to perform maintenance tasks for your [[Mediawiki_Installation|MediaWiki wikiserver]]. ==Adding WebDAV to your Apache2== ===Thoughts about WebDAV and your configuration=== Out of the box, your Debian Apache2 is prepared to start using WebDAV. All you need is to enable two modules: one for WebDAV itself, one for the authentication that you want to use. Since our server mainly uses LDAP, we'll describe WebDAV+LDAP here. Furthermore, because WebDAV allows editing files on your server, security is paramount (well, it always is, of course. What we mean is that it's even '''more''' important now). The Apache project recommends:<br> ''The use of HTTP Basic Authentication is not recommended. You should use at least HTTP Digest Authentication, which is provided by the mod_auth_digest module. Nearly all WebDAV clients support this authentication method. An alternative is Basic Authentication over an SSL enabled connection.''<br> Thus you should not using Basic Authentication (which is pretty simple to set up) unless you run it over SSL - so we do that as well. We choose the Virtual Host that defines our SSL-site, and extend it with WebDAV functionality. If this is not what you want, consider stepping your authentication up to Digest Authentication. ===Configuring WebDAV and LDAP for your SSL-enabled Virtual Host=== First, enable the WebDAV and authnz_ldap modules: a2enmod dav a2enmod dav_fs a2enmod authnz_ldap Do not restart Apache2 just yet, because we haven't configured either the WebDAV site or its authentication! Furthermore, a location for the DAV lock database must be specified in the global section of your Apache2 configuration file using the [http://httpd.apache.org/docs/2.2/mod/mod_dav_fs.html#davlockdb DavLockDB directive]. To this end, create a file under ''/etc/apache2/conf.d'' named ''webdav'' containing this single line: DavLockDB /var/run/apache2/DavLock This will act as the (global) lock database for WebDAV; we don't need to specify it in any other configuration file (like the Virtual Host configuration files). Of course, your server should have a directory ''/var/run/apache2'', and it must be writable for the user ''www-data'' under which Apache2 runs. Next, adapt the virtual host that may employ WebDAV and LDAP authentication. The virtual host file needs a section that enables WebDAV (using the directive ''Dav On''), and some directives on how to authorize users within this section. Suppose we want to enable WebDAV only for subdirectory ''webdav'' within virtual host ''<nowiki>http://www.saruman.biz/</nowiki>''. Then in the correspondig Virtual Host file (something like ''/etc/apache2/sites-available/000-saruman.biz'') we need to include the following section: <Location /webdav> Order Allow,Deny Allow from all Dav On These lines turn on WebDAV for the location ''/webdav''. This of course means that there should ''be'' a directory in your server's filesystem named ''webdav'' and located under the root of this virtual host, e.g. ''/var/www/saruman.biz/webdav'' AuthType Basic AuthBasicProvider ldap AuthzLDAPAuthoritative On This section sets up the authentication as HTTP Basic, with LDAP as the provider, and NOT allowing the authorization phase to fall back to other providers if LDAP cannot provide the required answer. If you want to use "require" statements from some other authorization provider, then you must set ''AuthzLDAPAuthoritative'' to "off". AuthName "Enter your Saruman.biz login" AuthLDAPURL "ldap://myserver.saruman.biz/ou=people,dc=saruman,dc=biz?mail" NONE AuthLDAPBindDN "cn=admin,dc=saruman,dc=biz" AuthLDAPBindPassword "mypassword" The ''AuthName'' directive "sets the name of the authorization realm". The string provided for the AuthName is what will appear in the password dialog provided by most browsers.<br> The ''AuthLDAPURL'' should point to your server, and the word behind the question mark should be the LDAP field that you want to use as login. We use ''mail'' so that we can log in with our mail address.<br> The ''AuthLDAPBindDN'' should be of a user with the right to view the passwords of the users that will be using the WebDAV server, and the ''AuthLDAPBindPassword'' should be that user's password.<br> require valid-user </Location> This last directive means that any user who has authenticated is granted access. Since only LDAP users can authenticate, this is just fine. Next up, you need to create folder ''webdav'' under the root of your Virtual Host. Do not forget to make that folder owned by ''www-data:www-data'' and readable/writable only by that user: cd /data/wwwroot/yoursite mkdir webdav chown www-data:www-data webdav chmod 660 webdav Now you can restart Apache2, see if it restarts ok, and then test your new WebDAV folder. 1cea3f7a598f0c7fbc6d06e6d98875f63dc65d0b 0 1494 2439 2025 2009-08-23T15:09:39Z Insomnia 3 /* WINS configuration */ wikitext text/x-wiki == The Samba Section== == Preparations == First off, get yourself [http://oreilly.com/catalog/9780596007690/index.html this wonderful book] - and READ IT. Next, make sure our user backend of choice, OpenLDAP, is properly installed and can be used to authenticate users. If you haven't yet installed OpenLDAP, go to [[OpenLDAP | the relevant section]] of this wiki, and get going. Make sure your OpenLDAP is running well. === Software installation === This is easy: using ''aptitude'', install the following packages: * ''samba'', the actual server. * ''samba-tools'', a set of utilities. * ''samba-doc'' - note that we NEED ''samba-doc'', as this package contains a configuration file that we need (the LDAP schema file). * ''smbclient'', that can make your Linux server work with a Windows or SaMBa server; we need this to test our own server. As usual, Debian is asking us for the configuration details. For SaMBa 3.2, there are only two simple questions: * What do you want to be your Windows workgroup name? (we provide the name "AMBER") * Do you want to modify ''smb.conf'' to use WINS setting from DHCP? (we provide "no") Now we have our SaMBa configuration file as ''/etc/samba/smb.conf'', but we're going to follow two time-honoured tradions: we're going to save the original configuration file for future reference, and we're going to rename our configuration file to ''smb.conf.master'', while providing SaMBa with a comment-stripped version of it: cd /etc/samba cp smb.conf smb.conf.sample mv smb.conf smb.conf.master testparm smb.conf.master testparm -s smb.conf.master > smb.conf Now remember: when we want to change our SaMBa configuration, we edit ''smb.conf.master''. Once we're ready with that, we ALWAYS need to run those last two lines; the first of those will check our updated configuration, to see if we haven't made some silly typo that renders the configuration wholly or partially crippled, and the second one creates a comment-stripped version of it that SaMBa will actually be using. === WINS configuration === To enable WINS, we add the following lines to ''smb.conf.master'': ## Browsing/Identification ### workgroup = AMBER netbios name = DWORKIN # Windows Internet Name Serving Support Section: # WINS Support - Tells the NMBD component of Samba to enable its WINS Server wins support = yes os level = 33 domain master = yes local master = yes preferred master = yes name resolve order = wins lmhosts hosts bcast dns proxy = yes Now this does a whole lot of things with the SaMBa ''nmbd'' daemon - at least when you remember to save the master config file, test it with ''testparm'' and write the actual ''smb.conf'' as desribed previously, AND then restart your ''nmbd'' daemon: /etc/init.d/samba restart OK so what do the configuration lines mean? * ''workgroup = AMBER'' - this line makes the SaMBa server a member of workgroup AMBER. * ''netbios name = DWORKIN'' - here we define the server NetBIOS name to be "dworkin". * ''wins support = yes'' - this line actually turns on the WINS support, so it instructs the ''nmbd'' daemon to start acting as a WINS server. * ''os level = 33'' - this gives our WINS server a "rank" of 33, meaning that it will be sure to become the WINS master browser, even if there are Windows servers on the network tat act as domain controllers. * ''domain master = yes'' - this will tell our server that it will not be just any master browser, but a '''domain''' master browser, so that our server will be the master browser on each and every subnet that it is connected to. * ''local master = yes'' - this setting is vital to being a domain master browser, as it ensures that our WINS server is also the local master browser. * ''preferred master = yes'' - adding this line makes the ''nmbd'' daemon initiate a browser election as soon as it starts up, so that it essentially gets the master browser role as fast as possible. * ''name resolve order = wins lmhosts hosts bcast'' - this ensures that for a WINS request, the ''nmbd'' daemon not only checks its WINS database, but also the local ''lmhosts'' file (if it exists), the Linux ''/etc/hosts'' file, and finally, to revert to a broadcast to see if it can locate the requested name by shouting out for it. * ''dns proxy = yes'' - this makes ''nmbd'' to check a requested name with the DNS server, if it cannot be found in the WINS database itself. After restarting, we can see if our Linux server is now a WINS master browser by inspecting the SaMBa log file, by default ''/var/log/samba/nmbd.log''. It should show something like [2008/11/21 16:18:03, 0] nmbd/nmbd.c:main(849) nmbd version 3.2.4 started. Copyright Andrew Tridgell and the Samba Team 1992-2008 [2008/11/21 16:18:03, 0] nmbd/asyncdns.c:start_async_dns(155) started asyncdns process 25707 [2008/11/21 16:18:03, 0] nmbd/nmbd_become_dmb.c:become_domain_master_browser_wins(336) become_domain_master_browser_wins: Attempting to become domain master browser on workgroup AMBER, subnet UNICAST_SUBNET. [2008/11/21 16:18:03, 0] nmbd/nmbd_become_dmb.c:become_domain_master_browser_wins(350) become_domain_master_browser_wins: querying WINS server from IP 192.168.67.10 for domain master browser name AMBER<1b> on workgroup AMBER [2008/11/21 16:18:03, 0] nmbd/nmbd_become_dmb.c:become_domain_master_stage2(110) ***** Samba server DWORKIN is now a domain master browser for workgroup AMBER on subnet UNICAST_SUBNET ***** [2008/11/21 16:18:03, 0] nmbd/nmbd_become_dmb.c:become_domain_master_browser_bcast(291) become_domain_master_browser_bcast: Attempting to become domain master browser on workgroup AMBER on subnet 192.168.67.10 [2008/11/21 16:18:03, 0] nmbd/nmbd_become_dmb.c:become_domain_master_browser_bcast(304) become_domain_master_browser_bcast: querying subnet 192.168.67.9 for domain master browser on workgroup AMBER [2008/11/21 16:18:11, 0] nmbd/nmbd_become_dmb.c:become_domain_master_stage2(110) ***** Samba server DWORKIN is now a domain master browser for workgroup AMBER on subnet 192.168.67.10 ***** [2008/11/21 16:18:26, 0] nmbd/nmbd_become_lmb.c:become_local_master_stage2(395) ***** Samba name server DWORKIN is now a local master browser for workgroup AMBER on subnet 192.168.67.10 ***** Furthermore, we can test on the server itself if a WINS lookup succeeds: dworkin:# nmblookup -M amber querying amber on 127.255.255.255 192.168.67.10 amber<1d> Finally, we tell our DHCP server to provide clients with the IP address of our WINS server. We do this by adding the following line to ''/etc/dhcp3-server/dhcpd.conf'': option netbios-name-servers 192.168.67.10; This line can either be added to the global section, or within the ''subnet'' declaration for each individual subnet that you want to inform of this WINS server. === OpenLDAP adaptation === In order for our OpenLDAP server to recognise the SaMBa-specific attributes that we're going to use, we need to add the "samba" schema to the OpenLDAP server. After installation of ''samba-doc'', we can find this schema in ''/usr/share/doc/samba-doc/examples/LDAP'', where it sits gzipped between some other schema files; as the README explains, what we need is ''samba.schema.gz'', so we unzip it and copy it to our OpenLDAP schema directory cd /usr/share/doc/samba-doc/examples/LDAP gunzip samba.schema.gz cp samba.schema /etc/ldap/schema Next up, we include this schema into our LDAP configuration, by adding the following line to ''/etc/ldap/slapd.conf'': include /etc/ldap/schema/samba.schema Not only do we need schema updates, we could also do with some more indices. Thus, we change the relevant section of ''/etc/ldap/slapd.conf'' to read: # Indexing options for database #1 index objectClass,uidNumber,gidNumber eq index cn,sn,uid,displayName pres,sub,eq index memberUid,mail,givenname eq,subinitial index sambaSID,sambaPrimaryGroupSID,sambaDomainName eq Ofcourse, it's not just enough to add these parameters, we also need to generate the indices, and restart our LDAP server: sudo invoke-rc.d slapd stop sudo -u openldap slapindex sudo invoke-rc.d slapd start Check to see if the Samba objects are now usable in your LDAP server, e.g. by opening your LDAP Account Manager, and go to tools > schema browser; you should have objects like "sambaConfig" and "sambaDomain". === Feed OpenLDAP with Samba information=== Now we can add the Samba3 account information to our LDAP server. There are two ways of doing that: create an LDAP ldif file with the necessary information, or use the graphic LDAP manager to add it. For small amounts of users, the last way is quickest. What you need is to take two steps: '''Add the SaMBa domain to the LDAP tree'''<br> For this step, as root you perform the following command net getlocalsid This will a string like "SID for domain DWORKIN is: S-1-5-21-2406862431-3150385097-213705319". With this SID, we can create the LDAP object that represents the SaMBa domain. To that end we log into our LDAP account manager, go to "Samba domains", and create our domain. There are only three pieces of information that are mandatory: * the domain name, in our example "amber" * the forementioned SID, in our example "S-1-5-21-2406862431-3150385097-213705319". * the RID base; this has a default of 1000, which you should not change unless you know exactly what you're doing. However, there are other options that you might find it worth setting, like the minimal password length, password history length, if users should be disconnected "outside logon hours" etcetera. We would advise you to not set too many options until you've finished testing all basic functionality of your SaMBa server. In case you're curious, the LDAP ldif file for such an account could look like this: dn: sambaDomainName=amber,ou=domains,dc=saruman,dc=biz objectClass: sambaDomain sambaDomainName: amber sambaSID: S-1-5-21-2476862421-3150885297-210706319 sambaAlgorithmicRidBase: 1000 sambaMinPwdLength: 7 sambaPwdHistoryLength: 5 sambaLogonToChgPwd: 0 sambaForceLogoff: -1 sambaRefuseMachinePwdChange: 1 dn: sambaDomainName=DWORKIN,dc=saruman,dc=biz objectClass: sambaDomain sambaDomainName: DWORKIN sambaSID: S-1-5-21-2476862421-3150885297-210706319 sambaAlgorithmicRidBase: 1000 sambaNextUserRid: 1000 sambaMinPwdLength: 5 sambaPwdHistoryLength: 0 sambaLogonToChgPwd: 0 sambaMaxPwdAge: -1 sambaMinPwdAge: 0 sambaLockoutDuration: 30 sambaLockoutObservationWindow: 30 sambaLockoutThreshold: 0 sambaForceLogoff: -1 sambaRefuseMachinePwdChange: 0 '''Add the SaMBa account information to LDAP user accounts'''<br> Again we use our LDAP account manager, and we now go to a user that we want to provide access to SaMBa. When you choose to edit the user, there should be a tab "Samba 3". In this tab, you can click the button "Add Samba 3 account"; until you've done that, this user has no access at all to the Samba server.<br> When adding (or changing) a users Samba account information, there is actually only one mandatory field: * "Domain": from this pulldown list you can choose the SaMBa/Windows domain that the user will belong to. When you have only your one SaMBa domain entered in your LDAP, this field will show the name of that domain. Furthermore, there are a few more fields that you might want to fill. They are: * "Display name": the name that Windows shows for a user * "Samba password": this may be a different password from a Unix account that the user may have * Windows group: this is the primary group that the user belongs to, from a SaMBa perspective instead of a Unix perspective. Having added the necessary information, the user should be able from a Windows machine to browse the SaMBa server, and see all non-hidden shares that are available to him. Furthermore, from a Linux prompt, you could use ''smbclient'' to verify that SaMBa honours the users name and password: smbclient //192.168.67.10/Data -U jan If the Data share has been made (for that: see further down), and if user "jan" has a Samba account in LDAP, and if you type the correct password, then you're greeted with an SMB client prompt: smb: \> Here you can type commands like "dir", "del" and "mkdir"; type "help" to see all available commands. == Samba configuration for LDAP authentication== To get SaMBA to use OpenLDAP as a backend is actually quite straightforward. The main work is done in ''smb.conf.master'', where we add the following section: passdb backend = ldapsam:ldap://127.0.0.1 ldap suffix = dc=saruman,dc=biz ldap machine suffix = ou=hosts ldap user suffix = ou=people ldap group suffix = ou=groups ldap admin dn = cn=admin,dc=saruman,dc=biz ldap delete dn = no # allow user privileges enable privileges = yes One note: if you use ''testparm -s'' to test and convert ''smb.conf.master'', then it's possible that your ''ldap suffix'' statement gets lower than one or more than the other ''ldap'' statements; you should rectify that before starting SaMBa, because otherwise SaMBa gets mighty confused, and cannot find the right LDAP OU's. Now the above declares the LDAP account ''admin,saruman,biz'' to be the LDAP admin account - but SaMBa hasn't got the admin password yet, so it can't do much. To this end, we let SaMBa store the password for this admin account in its own little secret file ''/etc/samba/secrets.tdb''. We do this by running smbpasswd -W Setting stored password for "cn=admin,dc=saruman,dc=biz" in secrets.tdb New SMB password: Retype new SMB password: If we used a lowercase ''-w'', then we could have specified the password on the command line (''smbpasswd -w SuperSecret''). = Samba share configuration = With the above configuration, we should now be able to create a share, and make it available to our LDAP accounts. To this end, we create a directory that we're going to share, and give it a workable set of permissions. Suppose we have an LDAP user "jan" and an LDAP group "networkusers". We could then, as root, do this: cd /data/samba mkdir Data chown jan:networkusers Data chmod g+rwxs,o-rwx Data This ensures that user "jan", as well as every user that's a member of "networkusers", is allowed to read and write in this share. However, thanks to the "sticky bit" set for the group with the ''chmod'' command, files that are written to this directory are automatically owned by the group "networkusers", who have read & write rights. Next step would be to share this directory, by adding the following section to ''smb.conf.master'': [Data] comment = Data directory for us all browseable = yes path = /data/samba/Data guest ok = no read only = no create mask = 0770 create directory mask = 0770 This makes the directory usable via the share "Data". Notice that we do not allow unauthenticated users ("guest ok = no"), that we allow writing in this share ("read only = no", although we could also have used "writeable = yes", which is the same), and that we mask every create operation (for both files and directories) so that they can set any right under "user" and "group", but cannot set any rights under "other". This prevents anyone other than the "networkusers" to read (let alone write) the files in this share. 98046e41ebbbfc665bdcbac0017ffcc680bf57da 2440 2439 2009-08-23T16:55:15Z 82.161.20.132 0 /* OpenLDAP adaptation */ wikitext text/x-wiki == The Samba Section== == Preparations == First off, get yourself [http://oreilly.com/catalog/9780596007690/index.html this wonderful book] - and READ IT. Next, make sure our user backend of choice, OpenLDAP, is properly installed and can be used to authenticate users. If you haven't yet installed OpenLDAP, go to [[OpenLDAP | the relevant section]] of this wiki, and get going. Make sure your OpenLDAP is running well. === Software installation === This is easy: using ''aptitude'', install the following packages: * ''samba'', the actual server. * ''samba-tools'', a set of utilities. * ''samba-doc'' - note that we NEED ''samba-doc'', as this package contains a configuration file that we need (the LDAP schema file). * ''smbclient'', that can make your Linux server work with a Windows or SaMBa server; we need this to test our own server. As usual, Debian is asking us for the configuration details. For SaMBa 3.2, there are only two simple questions: * What do you want to be your Windows workgroup name? (we provide the name "AMBER") * Do you want to modify ''smb.conf'' to use WINS setting from DHCP? (we provide "no") Now we have our SaMBa configuration file as ''/etc/samba/smb.conf'', but we're going to follow two time-honoured tradions: we're going to save the original configuration file for future reference, and we're going to rename our configuration file to ''smb.conf.master'', while providing SaMBa with a comment-stripped version of it: cd /etc/samba cp smb.conf smb.conf.sample mv smb.conf smb.conf.master testparm smb.conf.master testparm -s smb.conf.master > smb.conf Now remember: when we want to change our SaMBa configuration, we edit ''smb.conf.master''. Once we're ready with that, we ALWAYS need to run those last two lines; the first of those will check our updated configuration, to see if we haven't made some silly typo that renders the configuration wholly or partially crippled, and the second one creates a comment-stripped version of it that SaMBa will actually be using. === WINS configuration === To enable WINS, we add the following lines to ''smb.conf.master'': ## Browsing/Identification ### workgroup = AMBER netbios name = DWORKIN # Windows Internet Name Serving Support Section: # WINS Support - Tells the NMBD component of Samba to enable its WINS Server wins support = yes os level = 33 domain master = yes local master = yes preferred master = yes name resolve order = wins lmhosts hosts bcast dns proxy = yes Now this does a whole lot of things with the SaMBa ''nmbd'' daemon - at least when you remember to save the master config file, test it with ''testparm'' and write the actual ''smb.conf'' as desribed previously, AND then restart your ''nmbd'' daemon: /etc/init.d/samba restart OK so what do the configuration lines mean? * ''workgroup = AMBER'' - this line makes the SaMBa server a member of workgroup AMBER. * ''netbios name = DWORKIN'' - here we define the server NetBIOS name to be "dworkin". * ''wins support = yes'' - this line actually turns on the WINS support, so it instructs the ''nmbd'' daemon to start acting as a WINS server. * ''os level = 33'' - this gives our WINS server a "rank" of 33, meaning that it will be sure to become the WINS master browser, even if there are Windows servers on the network tat act as domain controllers. * ''domain master = yes'' - this will tell our server that it will not be just any master browser, but a '''domain''' master browser, so that our server will be the master browser on each and every subnet that it is connected to. * ''local master = yes'' - this setting is vital to being a domain master browser, as it ensures that our WINS server is also the local master browser. * ''preferred master = yes'' - adding this line makes the ''nmbd'' daemon initiate a browser election as soon as it starts up, so that it essentially gets the master browser role as fast as possible. * ''name resolve order = wins lmhosts hosts bcast'' - this ensures that for a WINS request, the ''nmbd'' daemon not only checks its WINS database, but also the local ''lmhosts'' file (if it exists), the Linux ''/etc/hosts'' file, and finally, to revert to a broadcast to see if it can locate the requested name by shouting out for it. * ''dns proxy = yes'' - this makes ''nmbd'' to check a requested name with the DNS server, if it cannot be found in the WINS database itself. After restarting, we can see if our Linux server is now a WINS master browser by inspecting the SaMBa log file, by default ''/var/log/samba/nmbd.log''. It should show something like [2008/11/21 16:18:03, 0] nmbd/nmbd.c:main(849) nmbd version 3.2.4 started. Copyright Andrew Tridgell and the Samba Team 1992-2008 [2008/11/21 16:18:03, 0] nmbd/asyncdns.c:start_async_dns(155) started asyncdns process 25707 [2008/11/21 16:18:03, 0] nmbd/nmbd_become_dmb.c:become_domain_master_browser_wins(336) become_domain_master_browser_wins: Attempting to become domain master browser on workgroup AMBER, subnet UNICAST_SUBNET. [2008/11/21 16:18:03, 0] nmbd/nmbd_become_dmb.c:become_domain_master_browser_wins(350) become_domain_master_browser_wins: querying WINS server from IP 192.168.67.10 for domain master browser name AMBER<1b> on workgroup AMBER [2008/11/21 16:18:03, 0] nmbd/nmbd_become_dmb.c:become_domain_master_stage2(110) ***** Samba server DWORKIN is now a domain master browser for workgroup AMBER on subnet UNICAST_SUBNET ***** [2008/11/21 16:18:03, 0] nmbd/nmbd_become_dmb.c:become_domain_master_browser_bcast(291) become_domain_master_browser_bcast: Attempting to become domain master browser on workgroup AMBER on subnet 192.168.67.10 [2008/11/21 16:18:03, 0] nmbd/nmbd_become_dmb.c:become_domain_master_browser_bcast(304) become_domain_master_browser_bcast: querying subnet 192.168.67.9 for domain master browser on workgroup AMBER [2008/11/21 16:18:11, 0] nmbd/nmbd_become_dmb.c:become_domain_master_stage2(110) ***** Samba server DWORKIN is now a domain master browser for workgroup AMBER on subnet 192.168.67.10 ***** [2008/11/21 16:18:26, 0] nmbd/nmbd_become_lmb.c:become_local_master_stage2(395) ***** Samba name server DWORKIN is now a local master browser for workgroup AMBER on subnet 192.168.67.10 ***** Furthermore, we can test on the server itself if a WINS lookup succeeds: dworkin:# nmblookup -M amber querying amber on 127.255.255.255 192.168.67.10 amber<1d> Finally, we tell our DHCP server to provide clients with the IP address of our WINS server. We do this by adding the following line to ''/etc/dhcp3-server/dhcpd.conf'': option netbios-name-servers 192.168.67.10; This line can either be added to the global section, or within the ''subnet'' declaration for each individual subnet that you want to inform of this WINS server. === OpenLDAP adaptation === In order for our OpenLDAP server to recognise the SaMBa-specific attributes that we're going to use, we need to add the "samba" schema to the OpenLDAP server. After installation of ''samba-doc'', we can find this schema in ''/usr/share/doc/samba-doc/examples/LDAP'', where it sits gzipped between some other schema files; as the README explains, what we need is ''samba.schema.gz'', so we unzip it and copy it to our OpenLDAP schema directory cd /usr/share/doc/samba-doc/examples/LDAP gunzip samba.schema.gz cp samba.schema /etc/ldap/schema Next up, we include this schema into our LDAP configuration, by adding the following line to ''/etc/ldap/slapd.conf'' under # Schema and objectClass definitions: include /etc/ldap/schema/samba.schema Not only do we need schema updates, we could also do with some more indices. Thus, we change the relevant section of ''/etc/ldap/slapd.conf'' to read: # Indexing options for database #1 index objectClass,uidNumber,gidNumber eq index cn,sn,uid,displayName pres,sub,eq index memberUid,mail,givenname eq,subinitial index sambaSID,sambaPrimaryGroupSID,sambaDomainName eq Ofcourse, it's not just enough to add these parameters, we also need to generate the indices, and restart our LDAP server: sudo invoke-rc.d slapd stop sudo -u openldap slapindex sudo invoke-rc.d slapd start Check to see if the Samba objects are now usable in your LDAP server, e.g. by opening your LDAP Account Manager, and go to tools > schema browser; you should have objects like "sambaConfig" and "sambaDomain". === Feed OpenLDAP with Samba information=== Now we can add the Samba3 account information to our LDAP server. There are two ways of doing that: create an LDAP ldif file with the necessary information, or use the graphic LDAP manager to add it. For small amounts of users, the last way is quickest. What you need is to take two steps: '''Add the SaMBa domain to the LDAP tree'''<br> For this step, as root you perform the following command net getlocalsid This will a string like "SID for domain DWORKIN is: S-1-5-21-2406862431-3150385097-213705319". With this SID, we can create the LDAP object that represents the SaMBa domain. To that end we log into our LDAP account manager, go to "Samba domains", and create our domain. There are only three pieces of information that are mandatory: * the domain name, in our example "amber" * the forementioned SID, in our example "S-1-5-21-2406862431-3150385097-213705319". * the RID base; this has a default of 1000, which you should not change unless you know exactly what you're doing. However, there are other options that you might find it worth setting, like the minimal password length, password history length, if users should be disconnected "outside logon hours" etcetera. We would advise you to not set too many options until you've finished testing all basic functionality of your SaMBa server. In case you're curious, the LDAP ldif file for such an account could look like this: dn: sambaDomainName=amber,ou=domains,dc=saruman,dc=biz objectClass: sambaDomain sambaDomainName: amber sambaSID: S-1-5-21-2476862421-3150885297-210706319 sambaAlgorithmicRidBase: 1000 sambaMinPwdLength: 7 sambaPwdHistoryLength: 5 sambaLogonToChgPwd: 0 sambaForceLogoff: -1 sambaRefuseMachinePwdChange: 1 dn: sambaDomainName=DWORKIN,dc=saruman,dc=biz objectClass: sambaDomain sambaDomainName: DWORKIN sambaSID: S-1-5-21-2476862421-3150885297-210706319 sambaAlgorithmicRidBase: 1000 sambaNextUserRid: 1000 sambaMinPwdLength: 5 sambaPwdHistoryLength: 0 sambaLogonToChgPwd: 0 sambaMaxPwdAge: -1 sambaMinPwdAge: 0 sambaLockoutDuration: 30 sambaLockoutObservationWindow: 30 sambaLockoutThreshold: 0 sambaForceLogoff: -1 sambaRefuseMachinePwdChange: 0 '''Add the SaMBa account information to LDAP user accounts'''<br> Again we use our LDAP account manager, and we now go to a user that we want to provide access to SaMBa. When you choose to edit the user, there should be a tab "Samba 3". In this tab, you can click the button "Add Samba 3 account"; until you've done that, this user has no access at all to the Samba server.<br> When adding (or changing) a users Samba account information, there is actually only one mandatory field: * "Domain": from this pulldown list you can choose the SaMBa/Windows domain that the user will belong to. When you have only your one SaMBa domain entered in your LDAP, this field will show the name of that domain. Furthermore, there are a few more fields that you might want to fill. They are: * "Display name": the name that Windows shows for a user * "Samba password": this may be a different password from a Unix account that the user may have * Windows group: this is the primary group that the user belongs to, from a SaMBa perspective instead of a Unix perspective. Having added the necessary information, the user should be able from a Windows machine to browse the SaMBa server, and see all non-hidden shares that are available to him. Furthermore, from a Linux prompt, you could use ''smbclient'' to verify that SaMBa honours the users name and password: smbclient //192.168.67.10/Data -U jan If the Data share has been made (for that: see further down), and if user "jan" has a Samba account in LDAP, and if you type the correct password, then you're greeted with an SMB client prompt: smb: \> Here you can type commands like "dir", "del" and "mkdir"; type "help" to see all available commands. == Samba configuration for LDAP authentication== To get SaMBA to use OpenLDAP as a backend is actually quite straightforward. The main work is done in ''smb.conf.master'', where we add the following section: passdb backend = ldapsam:ldap://127.0.0.1 ldap suffix = dc=saruman,dc=biz ldap machine suffix = ou=hosts ldap user suffix = ou=people ldap group suffix = ou=groups ldap admin dn = cn=admin,dc=saruman,dc=biz ldap delete dn = no # allow user privileges enable privileges = yes One note: if you use ''testparm -s'' to test and convert ''smb.conf.master'', then it's possible that your ''ldap suffix'' statement gets lower than one or more than the other ''ldap'' statements; you should rectify that before starting SaMBa, because otherwise SaMBa gets mighty confused, and cannot find the right LDAP OU's. Now the above declares the LDAP account ''admin,saruman,biz'' to be the LDAP admin account - but SaMBa hasn't got the admin password yet, so it can't do much. To this end, we let SaMBa store the password for this admin account in its own little secret file ''/etc/samba/secrets.tdb''. We do this by running smbpasswd -W Setting stored password for "cn=admin,dc=saruman,dc=biz" in secrets.tdb New SMB password: Retype new SMB password: If we used a lowercase ''-w'', then we could have specified the password on the command line (''smbpasswd -w SuperSecret''). = Samba share configuration = With the above configuration, we should now be able to create a share, and make it available to our LDAP accounts. To this end, we create a directory that we're going to share, and give it a workable set of permissions. Suppose we have an LDAP user "jan" and an LDAP group "networkusers". We could then, as root, do this: cd /data/samba mkdir Data chown jan:networkusers Data chmod g+rwxs,o-rwx Data This ensures that user "jan", as well as every user that's a member of "networkusers", is allowed to read and write in this share. However, thanks to the "sticky bit" set for the group with the ''chmod'' command, files that are written to this directory are automatically owned by the group "networkusers", who have read & write rights. Next step would be to share this directory, by adding the following section to ''smb.conf.master'': [Data] comment = Data directory for us all browseable = yes path = /data/samba/Data guest ok = no read only = no create mask = 0770 create directory mask = 0770 This makes the directory usable via the share "Data". Notice that we do not allow unauthenticated users ("guest ok = no"), that we allow writing in this share ("read only = no", although we could also have used "writeable = yes", which is the same), and that we mask every create operation (for both files and directories) so that they can set any right under "user" and "group", but cannot set any rights under "other". This prevents anyone other than the "networkusers" to read (let alone write) the files in this share. 4229e3d107e7ab087ee272526853c9a8b1d27bdb 0 1489 2443 2095 2009-08-28T07:13:22Z Insomnia 3 /* Dovecot default configuration */ wikitext text/x-wiki ==E-mail server setup== What we want to accomplish here is the setup of a mail server with the following properties: * can serve multiple mail domains * can relay mail for other domains to other mail servers * can have one or more mailboxes per domain * users of these mailboxes can be virtual (do not need to have a Linux user account) * can have multiple aliases per mailbox * can forward mail for certain aliases to multiple mailboxes For this type of mail server setup, we owe a great thankyou to [http://workaround.org/articles/ispmail-etch/ Christoph Haas], whose advise has helped us create flexible and reliable mail servers since 2003. ==Preparation== We'll assume that the server currently has no mailserver installed, at least no other than the default ''exim'' mailserver. Furthermore, the server is already fitted with MySQL, and this database is running without problems. The hostname of the server must be set correctly, so that ''hostname -f'' returns a valid DNS name, like ''lighthouse.saruman.biz.''. It might also be an internal name like ''lighthouse.saruman.lan.'' but that will require us to give extra attention to the name under which Postfix will contact its collegues on the Internet. Also, the server can correctly [Networking_section#DNS_resolution_under_Debian | resolve DNS names] like [http://www.debian.org www.debian.org], preferably by running it's own caching DNS server. The server is kept on the correct date and time using NTP, TCP port 25 is open on the server, the ISP will allow connections from Internet to this port, and if there's a firewall running on this server, then it has port 25 open so as to not block incoming e-mail. ==Software installation== As a first step, we use [[APT and aptitude|apt or aptitude]] to make sure that our server is up-to-date. Then we can install the necessary software packages. Under Debian 5.0 "Lenny", the (single) packages is: * ''postfix'', the mail server itself - this includes the "virtual package" postfix-tls, that we want to use to secure connections to Postfix with the TLS protocol At the same time we can - and must - purge the following packages: * exim4 * exim4-base * exim4-daemon-light * exim4-config In ''aptitude'', only press "go" when you've marked all four of these packages "purge", or you cannot install postfix. When installing the postfix package, the Debian installer script will ask you several questions, which you can answer like this: * General type of mail configuration: Internet site * System mail name: the FQDN of the mail server that you've verified in the previous section. Note that the script will try to guess the DNS name, but that might yield a DNS name with a trailing dot. That is technically correct, but the installation script will barf. Remove the trailing dot before hitting &lt;enter>! * Postmaster mail address: the address that all mail should go to that is addressed to "root" and "postmaster". * Domain list: give the list of all domains that the machine can consider itself the FINAL destination for. This should at a minimum include an empty value, "localhost" and the FQDN of the machine itself (no trailing dots!); however, if you're running your own mail domain, you can also add that (e.g. "saruman.biz"). Thus, the list could look like this: saruman.biz, lighthouse.saruman.lan, localhost.saruman.lan, , localhost * Force synchronous updates? We think that's not necessary, but please read the question and decide for yourself * Local networks: something like ''127.0.0.0/8 [::ffff:127.0.0.0]/104 [::1]/128 192.168.67.0/24'' (the default, augmented with your local IP range) * Mailbox size limits: you can give postfix a limit in bytes, but we're going to use one single big mailbox for all users, so we cannot let Postfix guard it. Leave it at 0 (zero) so we don't have a size limit. * Character for local address extension: we leave it at ''+'' * Internet protocols to use: currently we don't have IPv6 support, so there's no sense in letting Postfix try to serve IPv6. We choose ''ipv4'' only. With the above data, the Debian install script for Postfix can do its job and configure Postfix with some basic settings. Now that Postfix is installed, we can install some dependent packages (we could install them in the same run, but if anything goes amiss with the postfix installation, then these packages are going to remain unconfigured as well): * ''postfix-doc'', the accompanying documentation; * ''postfix-mysql'', necessary to have Postfix talk to our MySQL server; * ''postfix-pcre'' to be able to parse regular expressions, which which we can combat spam; * ''dovecot-imapd'' is a daemon that will provide your users with IMAP access to their mail; * ''dovecot-pop3d'' is another daemon, but for the POP3 protocol. ==Virtual Mailman creation== When we're done, we'll need a "system user", a sort of virtual mailman that is the owner of all mailboxes that we're serving. We suggest the name "vmail" for this user. Note: this user does not get his own mailbox (i.e. there's no mailbox at vmail@saruman.biz). To create this user, and his home directory, we can run the following commands: groupadd -g 120 vmail useradd -g vmail -u 120 vmail -d /data/vmail -m -s /bin/false As you see, we've chosen a group ID and user ID of 120 (after confirming that this ID was not taken by another group or user, by checking ''/etc/passwd'' and ''/etc/group''. Furthermore, we've decided to keep the ''vmail'' user's home directory not under ''/home/vmail'', but in a special place where we're going to expect server data to reside - in our server, the ''/data'' directory (which is a RAID-5 array mounted under root). By adding ''-m'', we've actually created the home directory, and adding ''-s /bin/false'' makes totally sure that the user ''vmail'' can never ever log in - even if we've not created a password for this user, so ''vmail'' shouldn't be able to log in anyway. Better safe than sorry. To tell Postfix that this ''vmail'' user is someone special, we run postconf -e virtual_uid_maps=static:120 postconf -e virtual_gid_maps=static:120 That makes postfix understand that all mail for the virtual mail domains must be written to disk with these specified user and group ID's. ==MySQL configuration== ===Database preparation=== We will use the MySQL database to record data on our mail system, and then give our Postfix access to this database so that it can read its configuration from there. For starters, we'll create a MySQL database named "vmail", and a MySQL user named "vmail_admin" that can read all necessary data from that "vmail" database. Then, we create the necessary tables, and a view that links these tables. We do this with the MySQL client ''mysql''. However, we're quite lazy, so we don't create this database by hand (that's error-prone), but by use of a script [[create.vmail.sql]]. To this end, feed the [[create.vmail.sql]] script into the ''mysql'' client like this: mysql -u root -p < create.vmail.sql (This of course assumes you have ''create.vmail.sql'' in your current working directory; if not you can include the path to the file.) Simply give the MySQL root user password, and the script creates the database, the user, the necessary tables, and the view.<br> A note of caution: it is never a good idea to just run scripts without a proper understanding of what it does. Especially with MySQL, it will be advantageous if you understand the SQL commands. Open the script in a text editor, open the [http://dev.mysql.com/doc/refman/5.0/en/ MySQL command reference], and trace back what the script does exactly. ===Inserting data=== Next up, we fill the database with the first sets of values (either test data or the first of our production data). We'll start off with the virtual domains that we're hosting, by running the mysql client and feeding it information like this: mysql -u root -p vmail mysql> INSERT INTO virtual_domains (id, vdomain) VALUES (1, 'saruman.biz'); mysql> INSERT INTO virtual_domains (vdomain) VALUES ('wiki.saruman.biz'); mysql> INSERT INTO virtual_domains (vdomain) VALUES ('shop.saruman.biz'); This has the effect of creating three entries. You can check that everything worked as planned by executing mysql> select * from virtual_domains; Note: only the first entry needs an ''id'' value, because in MySQL we've defined that field as AUTO_INCREMENT. After creating your first virtual domain in the table, you never have to use a statement like the first INSERT again, only statements like the other two. Now the MySQL database has the information needed by Postfix to recognise that you have three virtual mail domains (namely the three domains in the VALUES section) for which it hosts virtual mailboxes. Postfix cannot read this information yet, but that'll be taken care of in the next section. Whle still within the mysql client, we can now create users: mysql> INSERT INTO virtual_users (id, domain_id, user, passwd) VALUES (1, 1, 'jan', MD5('JanSecret')); mysql> INSERT INTO virtual_users (domain_id, user, passwd) VALUES (1, 'mike', MD5('MikeSecret')); mysql> INSERT INTO virtual_users (domain_id, user, passwd) VALUES (3, 'shopkeeper', MD5('ShopSecret')); This has the effect of creating three users "jan" (in domain saruman.biz), "mike" (in domain saruman.biz) and "shopkeeper" (in domain shop.saruman.biz). Again, the ''id'' value is only ever needed in the first statement, because from now on every user addition will auto-increment ''id''. The passwords shown are encrypted with MD5, and put in the ''passwd'' field. Later on, the users will be able to access their mailboxes using this password; we won't tell Postfix anything about them, because it doesn't need the passwords. You can check the content of the ''virtual_users'' table with the right "select" statement, and you can now also see that the view ''view-users'' works: mysql> select * from virtual_users; mysql> select * from view_users; Next up, we're going to add some aliases, which are alternative e-mail addresses for the users; their primary e-mail address can already be seen in the ''view_users'' view, but perhaps you also want mail to "webmaster@shop.saruman.biz" to arrive at one or more mailboxes, e.g. in the mailbox for user "shopkeeper" (within domain "shop.saruman.biz") and this guy's home address ("j.doe@example.com"). Furthermore, we'll define catchall-addresses for all domains, that'll send all mail for which no mailbox can be found to the mailbox of user Mike (for the first two domains) and Webmaster (for shop.saruman.biz; Webmaster himself is an alias yet again, that points to shopkeeper@shop.saruman.biz). To create the catchall, leave out a value for the source address. This creates the empty value for source that will be expanded (using source@domain) to "@domain". mysql> INSERT INTO virtual_aliases (id, domain_id, source, destination) VALUES (1, 2, 'webmaster', 'shopkeeper@shop.saruman.biz'); mysql> INSERT INTO virtual_aliases (domain_id, source, destination) VALUES (2, 'webmaster', 'j.doe@example.com'); mysql> INSERT INTO virtual_aliases (domain_id, destination) VALUES (1, 'mike@saruman.biz'); mysql> INSERT INTO virtual_aliases (domain_id, destination) VALUES (2, 'mike@saruman.biz'); mysql> INSERT INTO virtual_aliases (domain_id, destination) VALUES (3, 'webmaster@saruman.biz'); Again, we don't need to add the ''id'' value any more after the first ever insertion into this table. We can check the result by running a select statement against the ''virtual_aliases'' table and ''view_aliases'' view: mysql> select * from virtual_aliases; mysql> select * from view_aliases; == Postfix configuration for MySQL lookups== Next, we're going to tell Postfix to use the ''vmail'' database, and also how to read the database (Postfix never writes the MySQL database). To this end, we're going to create three configuration files in directory ''/etc/postfix''. We'll start off with one configuration file, with which Postfix can determine if a domain name is among the domain(s) that it's actually hosting mailboxes for. Then we'll create the config file that checks the table that contains all the users that have a virtual mailbox, and finally we create the lookup for the table with all the aliases. ===Virtual mail domains lookup=== Create file ''/etc/postfix/mysql-virtual-domains.cf'' with the following content: user = vmail_admin password = SuperSecret hosts = 127.0.0.1 dbname = vmail query = SELECT 1 FROM virtual_domains WHERE vdomain='%s' Next, we tell postfix to check this configuration file when it needs to check "virtual_mailbox_domains": postconf -e virtual_mailbox_domains=mysql:/etc/postfix/mysql-virtual-domains.cf Use of this configuration file in postfix has the effect of returning "yes" when checking our database for the domain part of an email address. Naturally, this configuration file has to be fitted with the actual ''vmail_admin'' password rather than our example "SuperSecret". === Virtual mail user lookup=== Create the file ''/etc/postfix/mysql-virtual-mailbox-maps.cf'' with the following content: user = vmail_admin password = SuperSecret hosts = 127.0.0.1 dbname = vmail query = SELECT 1 FROM view_users WHERE email='%s' Next, we tell Postfix that this mapping file is supposed to be used for the ''virtual_mailbox_maps'' mapping: postconf -e virtual_mailbox_maps=mysql:/etc/postfix/mysql-virtual-mailbox-maps.cf The lookup of virtual mailboxes should work with the data we've put into the database previously. i.e. postmap -q jan@saruman.biz mysql:/etc/postfix/mysql-virtual-mailbox-maps.cf should return a '''1''' to acknowledge that "jan@saruman.biz" is indeed a virtual mailbox in our Postfix configuration. === Virtual alias lookup=== Create another cf file at ''/etc/postfix/mysql-virtual-alias-maps.cf'': user = vmail_admin password = SuperSecret hosts = 127.0.0.1 dbname = vmail query = SELECT destination FROM view_aliases WHERE email='%s' And create yet another cf file at ''/etc/postfix/mysql-email2email.cf'': user = vmail_admin password = SuperSecret hosts = 127.0.0.1 dbname = vmail query = SELECT email FROM view_users WHERE email='%s' Again, we tell Postfix that this mapping file is supposed to be used for the ''virtual_alias_maps'' mapping: postconf -e virtual_alias_maps=mysql:/etc/postfix/mysql-virtual-alias-maps.cf,mysql:/etc/postfix/mysql-email2email.cf The lookup of virtual aliases should now work as designed: postmap -q shopkeeper@shop.saruman.biz mysql:/etc/postfix/mysql-virtual-alias-maps.cf postmap -q webmaster@shop.saruman.biz mysql:/etc/postfix/mysql-virtual-alias-maps.cf If you've put in the data from the previous section, then both commands should return the same result: ''shopkeeper@saruman.biz''. This shows that Postfix will deliver mail to shopkeeper or to webmaster to the mailbox of shopkeeper. ===Finishing up configuration files=== When everything works as planned, then we secure the configuration files against prying eyes. Remember, the configuration files contain the user/password combination which which to access the ''vmail'' SQL database. The ''vmail_admin'' user has only read rights, and passwords in there are encrypted, but nevertheless, this is information we need to protect. Thus: chown root:postfix /etc/postfix/mysql-*.cf chmod u=rw,g=r,o= /etc/postfix/mysql-*.cf This protects all four configuration files since only root can write them, members of group ''postfix'' can read them, and the rest of the world cannot access them at all. ==Configuring mail delivery through Dovecot LDA== E-mails get delivered to the virtual mailboxes by means of a Mail Delivery Agent (MDA). With Postfix, the standard MDA for delivery to virtual mailboxes is called ''virtual'', but we're not going to use that; we're going to use ''[http://wiki.dovecot.org/LDA Dovecot LDA]'', which is a program called ''deliver''. By the way, the abbreviation LDA stands for Local Delivery Agent, which of course means more or less the same as MDA. ===Enabling the Dovecot daemon=== To make Postfix use Dovecot LDA, we add the following line to ''/etc/postfix/master.cf'': dovecot unix - n n - - pipe flags=DRhu user=vmail:vmail argv=/usr/lib/dovecot/deliver -d ${recipient} This declares the service "dovecot" to mean using the program ''/usr/lib/dovecot/deliver'' with the right parameters. If we now let Postfix reload its files, it'll learn about this new service. Subsequently we can instruct Postfix to start using it, by declaring service "dovecot" to be the virtual transport of choice, and specifying one Dovecot-specific variable: postfix reload postconf -e virtual_transport=dovecot postconf -e dovecot_destination_recipient_limit=1 ===Dovecot default configuration=== Now to configure Dovecot itself: open ''/etc/dovecot/dovecot.conf'' with your favourite editor [[vim]]; first make sure the ''protocols ='' line reads protocols = imap imaps pop3 pop3s (which it should by default). The second setting is quite crucial. By default, the location of the mail directories is found automatically by Dovecot, but here that won't work. Find the line that reads ''#mail_location ='', and change it to mail_location = maildir:/data/vmail/%d/%n/Maildir This will look for mail in directory ''/data/vmail/'''DOMAIN'''/'''USER'''/Maildir'', and expect this directory to be in "maildir" format. Next look for a section called "auth default". First define the allowed authentication mechanisms: mechanisms = plain login Then inside that same section you need to uncomment: passdb sql { args = /etc/dovecot/dovecot-sql.conf } which tells Dovecot that the passwords are stored in an SQL database (it's obvious that we'll now have to create this conf-file) and: userdb static { args = uid=120 gid=120 home=/data/vmail/%d/%n allow_all_users=yes } to tell Dovecot where the mailboxes are located. This is similar to the ''mail_location'' setting. Next task: comment out the section ''passdb pam'', so that Dovecot doesn't accidentally try to service local users as well. Next up: tell Dovecot to handle IMAP the same as previous versions of this virtual mailserver have - this can prove to be quite tricky if you already have mailboxes full of mail, put there by e.g. Courier-IMAP. What works for us, is namespace private { separator = . prefix = inbox = yes } However, your mileage may vary. You'll also want to comment out the ''passdb pam'' sections, since we're not hosting mail for local users. Next up, we'll edit the section ''socket listen'' so that Dovecot can access the user database (master section), and our Postfix mailserver can access Dovecot (client section): socket listen { master { path = /var/run/dovecot/auth-master mode = 0600 user = vmail } client { path = /var/spool/postfix/private/auth mode = 0660 user = postfix group = postfix } } Finally, the protocol section, where we specify log files, an address to put in mails when we send out nondelivery reports, and a place to store scripts: protocol lda { log_path = /var/log/appslog/mail/dovecot-deliver.log auth_socket_path = /var/run/dovecot/auth-master postmaster_address = postmaster@saruman.biz mail_plugins = cmusieve global_script_path = /data/vmail/globalsieverc } Now that we've finished the Dovecot configuration file, we need to create a fitting MySQL configuration file for Dovecot. The file is ''/etc/dovecot/dovecot-sql.conf'', and its contents are driver = mysql connect = host=127.0.0.1 dbname=vmail user=vmail_admin password=SuperSecret default_pass_scheme = PLAIN-MD5 password_query = SELECT email as user, passwd as password FROM view_users WHERE email='%u'; When you've created this file (as root), change the attributes of ''dovecot-sql.conf'' and ''dovecot.conf'', and then restart Dovecot to start using the new configuration. Note: ''dovecot.conf'' needs to be read by Postfix, hence the group ownership for the file. chmod u=rw,g=,o= /etc/dovecot/dovecot-sql.conf chgrp vmail /etc/dovecot/dovecot.conf chmod u=rw,g=r,o= /etc/dovecot/dovecot.conf /etc/init.d/dovecot restart ===Dovecot SSL configuration=== Out of the (Debian) box, Dovecot is SSL-enabled. We'll now replace the generic SSL-certificate, generated for the host by the Dovecot installation script, by our own certificate. To ths end, we first [[Creating_digital_certificates_with_our_root_certificate | generate an appropriate certificate]], e.g. an SSL wildcard certificate: "*.saruman.biz". This results in a public and a private certificate, both of which must be placed somewhere where Dovecot expects them and can read them. By default, Dovecot expects the following locations/filenames/owner/attributes: /etc/ssl/certs/dovecot.pem -rw-r--r-- root:dovecot 4624 bytes /etc/ssl/private/dovecot.pem -rw------- root:dovecot 1743 bytes If we may make a suggestion: rename the generated certificates in both locations to dovecot.pem.bak, place your generated certificates in their place, and set the owner/permissions like displayed here. However, if you've generated your own keys, you might have used a passphrase on the private key. You'll have to tell dovecot about it in its configuration file /etc/dovecot/dovecot.conf. To this end, edit the corresponding section by uncommenting the "ssl_" lines, and using your private key password (e.g. "zM7Ertq12") in the appropriate line: ssl_cert_file = /etc/ssl/certs/dovecot.pem ssl_key_file = /etc/ssl/private/dovecot.pem # If key file is password protected, give the password here. Alternatively # give it when starting dovecot with -p parameter. ssl_key_password = zM7Ertq12 Naturally you are free to place the keys in a different location, and/or use a different name... ==Finishing up== This is a good moment to test your configuration, if you haven't been able to test your work inbetween. If everything works as expected, you can add bells and whistles to your configuration. ===''smtpd'' TLS encryption=== The first addition we'd like to present covers the way Postfix handles incoming connections. Since authentication works, we can have Postfix distrust every (unauthenticated) connection: postconf -e mynetworks= Furthermore, since a default SSL certificate is installed by the Debian Postfix installation routine, we can encrypt all our connections using TLS; we enforce this using postconf -e smtpd_use_tls=yes postconf -e smtpd_tls_auth_only=yes Of course, you need to adjust the settings of your IMAP client so that it properly uses TLS and properly authenticates itself. If TLS works, you'll probably want to change the certificate as you have for Dovecot in the previous section. This is again pretty easy. If you haven't yet, now is the time to [[Creating_digital_certificates_with_our_root_certificate | creating that custom SSL certificate]] for our mail server - but you have to make sure that you DON'T use a password on the private key. Unlike Dovecot, Postfix cannot be told the password to the private key somewhere. For starters, look at the TLS-section of your ''main.cf'' that you currently have. Chances are a big chunk of it looks like this: # TLS parameters smtpd_tls_cert_file=/etc/ssl/certs/ssl-cert-snakeoil.pem smtpd_tls_key_file=/etc/ssl/private/ssl-cert-snakeoil.key smtpd_use_tls=yes Now all you need to do is replace the name of the snakeoil-keys with those of appropriate ssl-certificates, the private key of which needs to be NOT passphrase-protected. For this you could copy the Dovecot certificates, if you strip that passphrase in the manner described in the [[Creating_digital_certificates_with_our_root_certificate#Creating_an_SSL_certificate | SSL certificate section]]. The ''main.cf'' then would become: # TLS parameters smtpd_tls_cert_file=/etc/ssl/certs/postfix.pem smtpd_tls_key_file=/etc/ssl/private/postfix.key smtpd_use_tls=yes Restart Postfix, and presto. === Other additions === If everything ''still'' works after these changes, then congratulations, you now have a powerful, flexible and pretty secure mail setup. Of course, there are always points for improvements. We'll cover these in separate pages. One page that we want to direct you to now, is * [[Antispam measures]] for our Postfix mailserver 64906ba319f4bac5b0c0febfce928ec2e13c69d1 2447 2443 2009-08-29T08:02:46Z Insomnia 3 /* Dovecot default configuration */ wikitext text/x-wiki ==E-mail server setup== What we want to accomplish here is the setup of a mail server with the following properties: * can serve multiple mail domains * can relay mail for other domains to other mail servers * can have one or more mailboxes per domain * users of these mailboxes can be virtual (do not need to have a Linux user account) * can have multiple aliases per mailbox * can forward mail for certain aliases to multiple mailboxes For this type of mail server setup, we owe a great thankyou to [http://workaround.org/articles/ispmail-etch/ Christoph Haas], whose advise has helped us create flexible and reliable mail servers since 2003. ==Preparation== We'll assume that the server currently has no mailserver installed, at least no other than the default ''exim'' mailserver. Furthermore, the server is already fitted with MySQL, and this database is running without problems. The hostname of the server must be set correctly, so that ''hostname -f'' returns a valid DNS name, like ''lighthouse.saruman.biz.''. It might also be an internal name like ''lighthouse.saruman.lan.'' but that will require us to give extra attention to the name under which Postfix will contact its collegues on the Internet. Also, the server can correctly [Networking_section#DNS_resolution_under_Debian | resolve DNS names] like [http://www.debian.org www.debian.org], preferably by running it's own caching DNS server. The server is kept on the correct date and time using NTP, TCP port 25 is open on the server, the ISP will allow connections from Internet to this port, and if there's a firewall running on this server, then it has port 25 open so as to not block incoming e-mail. ==Software installation== As a first step, we use [[APT and aptitude|apt or aptitude]] to make sure that our server is up-to-date. Then we can install the necessary software packages. Under Debian 5.0 "Lenny", the (single) packages is: * ''postfix'', the mail server itself - this includes the "virtual package" postfix-tls, that we want to use to secure connections to Postfix with the TLS protocol At the same time we can - and must - purge the following packages: * exim4 * exim4-base * exim4-daemon-light * exim4-config In ''aptitude'', only press "go" when you've marked all four of these packages "purge", or you cannot install postfix. When installing the postfix package, the Debian installer script will ask you several questions, which you can answer like this: * General type of mail configuration: Internet site * System mail name: the FQDN of the mail server that you've verified in the previous section. Note that the script will try to guess the DNS name, but that might yield a DNS name with a trailing dot. That is technically correct, but the installation script will barf. Remove the trailing dot before hitting &lt;enter>! * Postmaster mail address: the address that all mail should go to that is addressed to "root" and "postmaster". * Domain list: give the list of all domains that the machine can consider itself the FINAL destination for. This should at a minimum include an empty value, "localhost" and the FQDN of the machine itself (no trailing dots!); however, if you're running your own mail domain, you can also add that (e.g. "saruman.biz"). Thus, the list could look like this: saruman.biz, lighthouse.saruman.lan, localhost.saruman.lan, , localhost * Force synchronous updates? We think that's not necessary, but please read the question and decide for yourself * Local networks: something like ''127.0.0.0/8 [::ffff:127.0.0.0]/104 [::1]/128 192.168.67.0/24'' (the default, augmented with your local IP range) * Mailbox size limits: you can give postfix a limit in bytes, but we're going to use one single big mailbox for all users, so we cannot let Postfix guard it. Leave it at 0 (zero) so we don't have a size limit. * Character for local address extension: we leave it at ''+'' * Internet protocols to use: currently we don't have IPv6 support, so there's no sense in letting Postfix try to serve IPv6. We choose ''ipv4'' only. With the above data, the Debian install script for Postfix can do its job and configure Postfix with some basic settings. Now that Postfix is installed, we can install some dependent packages (we could install them in the same run, but if anything goes amiss with the postfix installation, then these packages are going to remain unconfigured as well): * ''postfix-doc'', the accompanying documentation; * ''postfix-mysql'', necessary to have Postfix talk to our MySQL server; * ''postfix-pcre'' to be able to parse regular expressions, which which we can combat spam; * ''dovecot-imapd'' is a daemon that will provide your users with IMAP access to their mail; * ''dovecot-pop3d'' is another daemon, but for the POP3 protocol. ==Virtual Mailman creation== When we're done, we'll need a "system user", a sort of virtual mailman that is the owner of all mailboxes that we're serving. We suggest the name "vmail" for this user. Note: this user does not get his own mailbox (i.e. there's no mailbox at vmail@saruman.biz). To create this user, and his home directory, we can run the following commands: groupadd -g 120 vmail useradd -g vmail -u 120 vmail -d /data/vmail -m -s /bin/false As you see, we've chosen a group ID and user ID of 120 (after confirming that this ID was not taken by another group or user, by checking ''/etc/passwd'' and ''/etc/group''. Furthermore, we've decided to keep the ''vmail'' user's home directory not under ''/home/vmail'', but in a special place where we're going to expect server data to reside - in our server, the ''/data'' directory (which is a RAID-5 array mounted under root). By adding ''-m'', we've actually created the home directory, and adding ''-s /bin/false'' makes totally sure that the user ''vmail'' can never ever log in - even if we've not created a password for this user, so ''vmail'' shouldn't be able to log in anyway. Better safe than sorry. To tell Postfix that this ''vmail'' user is someone special, we run postconf -e virtual_uid_maps=static:120 postconf -e virtual_gid_maps=static:120 That makes postfix understand that all mail for the virtual mail domains must be written to disk with these specified user and group ID's. ==MySQL configuration== ===Database preparation=== We will use the MySQL database to record data on our mail system, and then give our Postfix access to this database so that it can read its configuration from there. For starters, we'll create a MySQL database named "vmail", and a MySQL user named "vmail_admin" that can read all necessary data from that "vmail" database. Then, we create the necessary tables, and a view that links these tables. We do this with the MySQL client ''mysql''. However, we're quite lazy, so we don't create this database by hand (that's error-prone), but by use of a script [[create.vmail.sql]]. To this end, feed the [[create.vmail.sql]] script into the ''mysql'' client like this: mysql -u root -p < create.vmail.sql (This of course assumes you have ''create.vmail.sql'' in your current working directory; if not you can include the path to the file.) Simply give the MySQL root user password, and the script creates the database, the user, the necessary tables, and the view.<br> A note of caution: it is never a good idea to just run scripts without a proper understanding of what it does. Especially with MySQL, it will be advantageous if you understand the SQL commands. Open the script in a text editor, open the [http://dev.mysql.com/doc/refman/5.0/en/ MySQL command reference], and trace back what the script does exactly. ===Inserting data=== Next up, we fill the database with the first sets of values (either test data or the first of our production data). We'll start off with the virtual domains that we're hosting, by running the mysql client and feeding it information like this: mysql -u root -p vmail mysql> INSERT INTO virtual_domains (id, vdomain) VALUES (1, 'saruman.biz'); mysql> INSERT INTO virtual_domains (vdomain) VALUES ('wiki.saruman.biz'); mysql> INSERT INTO virtual_domains (vdomain) VALUES ('shop.saruman.biz'); This has the effect of creating three entries. You can check that everything worked as planned by executing mysql> select * from virtual_domains; Note: only the first entry needs an ''id'' value, because in MySQL we've defined that field as AUTO_INCREMENT. After creating your first virtual domain in the table, you never have to use a statement like the first INSERT again, only statements like the other two. Now the MySQL database has the information needed by Postfix to recognise that you have three virtual mail domains (namely the three domains in the VALUES section) for which it hosts virtual mailboxes. Postfix cannot read this information yet, but that'll be taken care of in the next section. Whle still within the mysql client, we can now create users: mysql> INSERT INTO virtual_users (id, domain_id, user, passwd) VALUES (1, 1, 'jan', MD5('JanSecret')); mysql> INSERT INTO virtual_users (domain_id, user, passwd) VALUES (1, 'mike', MD5('MikeSecret')); mysql> INSERT INTO virtual_users (domain_id, user, passwd) VALUES (3, 'shopkeeper', MD5('ShopSecret')); This has the effect of creating three users "jan" (in domain saruman.biz), "mike" (in domain saruman.biz) and "shopkeeper" (in domain shop.saruman.biz). Again, the ''id'' value is only ever needed in the first statement, because from now on every user addition will auto-increment ''id''. The passwords shown are encrypted with MD5, and put in the ''passwd'' field. Later on, the users will be able to access their mailboxes using this password; we won't tell Postfix anything about them, because it doesn't need the passwords. You can check the content of the ''virtual_users'' table with the right "select" statement, and you can now also see that the view ''view-users'' works: mysql> select * from virtual_users; mysql> select * from view_users; Next up, we're going to add some aliases, which are alternative e-mail addresses for the users; their primary e-mail address can already be seen in the ''view_users'' view, but perhaps you also want mail to "webmaster@shop.saruman.biz" to arrive at one or more mailboxes, e.g. in the mailbox for user "shopkeeper" (within domain "shop.saruman.biz") and this guy's home address ("j.doe@example.com"). Furthermore, we'll define catchall-addresses for all domains, that'll send all mail for which no mailbox can be found to the mailbox of user Mike (for the first two domains) and Webmaster (for shop.saruman.biz; Webmaster himself is an alias yet again, that points to shopkeeper@shop.saruman.biz). To create the catchall, leave out a value for the source address. This creates the empty value for source that will be expanded (using source@domain) to "@domain". mysql> INSERT INTO virtual_aliases (id, domain_id, source, destination) VALUES (1, 2, 'webmaster', 'shopkeeper@shop.saruman.biz'); mysql> INSERT INTO virtual_aliases (domain_id, source, destination) VALUES (2, 'webmaster', 'j.doe@example.com'); mysql> INSERT INTO virtual_aliases (domain_id, destination) VALUES (1, 'mike@saruman.biz'); mysql> INSERT INTO virtual_aliases (domain_id, destination) VALUES (2, 'mike@saruman.biz'); mysql> INSERT INTO virtual_aliases (domain_id, destination) VALUES (3, 'webmaster@saruman.biz'); Again, we don't need to add the ''id'' value any more after the first ever insertion into this table. We can check the result by running a select statement against the ''virtual_aliases'' table and ''view_aliases'' view: mysql> select * from virtual_aliases; mysql> select * from view_aliases; == Postfix configuration for MySQL lookups== Next, we're going to tell Postfix to use the ''vmail'' database, and also how to read the database (Postfix never writes the MySQL database). To this end, we're going to create three configuration files in directory ''/etc/postfix''. We'll start off with one configuration file, with which Postfix can determine if a domain name is among the domain(s) that it's actually hosting mailboxes for. Then we'll create the config file that checks the table that contains all the users that have a virtual mailbox, and finally we create the lookup for the table with all the aliases. ===Virtual mail domains lookup=== Create file ''/etc/postfix/mysql-virtual-domains.cf'' with the following content: user = vmail_admin password = SuperSecret hosts = 127.0.0.1 dbname = vmail query = SELECT 1 FROM virtual_domains WHERE vdomain='%s' Next, we tell postfix to check this configuration file when it needs to check "virtual_mailbox_domains": postconf -e virtual_mailbox_domains=mysql:/etc/postfix/mysql-virtual-domains.cf Use of this configuration file in postfix has the effect of returning "yes" when checking our database for the domain part of an email address. Naturally, this configuration file has to be fitted with the actual ''vmail_admin'' password rather than our example "SuperSecret". === Virtual mail user lookup=== Create the file ''/etc/postfix/mysql-virtual-mailbox-maps.cf'' with the following content: user = vmail_admin password = SuperSecret hosts = 127.0.0.1 dbname = vmail query = SELECT 1 FROM view_users WHERE email='%s' Next, we tell Postfix that this mapping file is supposed to be used for the ''virtual_mailbox_maps'' mapping: postconf -e virtual_mailbox_maps=mysql:/etc/postfix/mysql-virtual-mailbox-maps.cf The lookup of virtual mailboxes should work with the data we've put into the database previously. i.e. postmap -q jan@saruman.biz mysql:/etc/postfix/mysql-virtual-mailbox-maps.cf should return a '''1''' to acknowledge that "jan@saruman.biz" is indeed a virtual mailbox in our Postfix configuration. === Virtual alias lookup=== Create another cf file at ''/etc/postfix/mysql-virtual-alias-maps.cf'': user = vmail_admin password = SuperSecret hosts = 127.0.0.1 dbname = vmail query = SELECT destination FROM view_aliases WHERE email='%s' And create yet another cf file at ''/etc/postfix/mysql-email2email.cf'': user = vmail_admin password = SuperSecret hosts = 127.0.0.1 dbname = vmail query = SELECT email FROM view_users WHERE email='%s' Again, we tell Postfix that this mapping file is supposed to be used for the ''virtual_alias_maps'' mapping: postconf -e virtual_alias_maps=mysql:/etc/postfix/mysql-virtual-alias-maps.cf,mysql:/etc/postfix/mysql-email2email.cf The lookup of virtual aliases should now work as designed: postmap -q shopkeeper@shop.saruman.biz mysql:/etc/postfix/mysql-virtual-alias-maps.cf postmap -q webmaster@shop.saruman.biz mysql:/etc/postfix/mysql-virtual-alias-maps.cf If you've put in the data from the previous section, then both commands should return the same result: ''shopkeeper@saruman.biz''. This shows that Postfix will deliver mail to shopkeeper or to webmaster to the mailbox of shopkeeper. ===Finishing up configuration files=== When everything works as planned, then we secure the configuration files against prying eyes. Remember, the configuration files contain the user/password combination which which to access the ''vmail'' SQL database. The ''vmail_admin'' user has only read rights, and passwords in there are encrypted, but nevertheless, this is information we need to protect. Thus: chown root:postfix /etc/postfix/mysql-*.cf chmod u=rw,g=r,o= /etc/postfix/mysql-*.cf This protects all four configuration files since only root can write them, members of group ''postfix'' can read them, and the rest of the world cannot access them at all. ==Configuring mail delivery through Dovecot LDA== E-mails get delivered to the virtual mailboxes by means of a Mail Delivery Agent (MDA). With Postfix, the standard MDA for delivery to virtual mailboxes is called ''virtual'', but we're not going to use that; we're going to use ''[http://wiki.dovecot.org/LDA Dovecot LDA]'', which is a program called ''deliver''. By the way, the abbreviation LDA stands for Local Delivery Agent, which of course means more or less the same as MDA. ===Enabling the Dovecot daemon=== To make Postfix use Dovecot LDA, we add the following line to ''/etc/postfix/master.cf'': dovecot unix - n n - - pipe flags=DRhu user=vmail:vmail argv=/usr/lib/dovecot/deliver -d ${recipient} This declares the service "dovecot" to mean using the program ''/usr/lib/dovecot/deliver'' with the right parameters. If we now let Postfix reload its files, it'll learn about this new service. Subsequently we can instruct Postfix to start using it, by declaring service "dovecot" to be the virtual transport of choice, and specifying one Dovecot-specific variable: postfix reload postconf -e virtual_transport=dovecot postconf -e dovecot_destination_recipient_limit=1 ===Dovecot default configuration=== Now to configure Dovecot itself: open ''/etc/dovecot/dovecot.conf'' with your favourite editor [[vim]]; first make sure the ''protocols ='' line reads protocols = imap imaps pop3 pop3s (which it should by default). The second setting is quite crucial. By default, the location of the mail directories is found automatically by Dovecot, but here that won't work. Find the line that reads ''#mail_location ='', and change it to mail_location = maildir:/data/vmail/%d/%n/Maildir This will look for mail in directory ''/data/vmail/'''DOMAIN'''/'''USER'''/Maildir'', and expect this directory to be in "maildir" format. Next look for a section called "auth default". First define the allowed authentication mechanisms: mechanisms = plain login Then inside that same section you need to uncomment: passdb sql { args = /etc/dovecot/dovecot-sql.conf } which tells Dovecot that the passwords are stored in an SQL database (it's obvious that we'll now have to create this conf-file) and: userdb static { args = uid=120 gid=120 home=/data/vmail/%d/%n allow_all_users=yes } to tell Dovecot where the mailboxes are located. This is similar to the ''mail_location'' setting. Next task: comment out the section ''passdb pam'', so that Dovecot doesn't accidentally try to service local users as well. Next up: tell Dovecot to handle IMAP the same as previous versions of this virtual mailserver have - this can prove to be quite tricky if you already have mailboxes full of mail, put there by e.g. Courier-IMAP. What works for us, is namespace private { separator = . prefix = inbox = yes } However, your mileage may vary. You'll also want to comment out the ''passdb pam'' sections, since we're not hosting mail for local users. Next up, we'll edit the section ''socket listen'' so that Dovecot can access the user database (master section), and our Postfix mailserver can access Dovecot (client section): socket listen { master { path = /var/run/dovecot/auth-master mode = 0600 user = vmail } client { path = /var/spool/postfix/private/auth mode = 0660 user = postfix group = postfix } } Finally, the protocol section, where we specify log files, an address to put in mails when we send out nondelivery reports, and a place to store scripts: protocol lda { log_path = /var/log/appslog/mail/dovecot-deliver.log auth_socket_path = /var/run/dovecot/auth-master postmaster_address = postmaster@saruman.biz mail_plugins = cmusieve global_script_path = /data/vmail/globalsieverc } You could change the log path to "log_path =" With a empty logpath syslog will log the events. Now that we've finished the Dovecot configuration file, we need to create a fitting MySQL configuration file for Dovecot. The file is ''/etc/dovecot/dovecot-sql.conf'', and its contents are driver = mysql connect = host=127.0.0.1 dbname=vmail user=vmail_admin password=SuperSecret default_pass_scheme = PLAIN-MD5 password_query = SELECT email as user, passwd as password FROM view_users WHERE email='%u'; When you've created this file (as root), change the attributes of ''dovecot-sql.conf'' and ''dovecot.conf'', and then restart Dovecot to start using the new configuration. Note: ''dovecot.conf'' needs to be read by Postfix, hence the group ownership for the file. chmod u=rw,g=,o= /etc/dovecot/dovecot-sql.conf chgrp vmail /etc/dovecot/dovecot.conf chmod u=rw,g=r,o= /etc/dovecot/dovecot.conf /etc/init.d/dovecot restart To get some more logging in the case something goes wrong. Uncomment the folling and change to yes. auth_verbose = yes auth_debug = yes auth_debug_passwords = yes ===Dovecot SSL configuration=== Out of the (Debian) box, Dovecot is SSL-enabled. We'll now replace the generic SSL-certificate, generated for the host by the Dovecot installation script, by our own certificate. To ths end, we first [[Creating_digital_certificates_with_our_root_certificate | generate an appropriate certificate]], e.g. an SSL wildcard certificate: "*.saruman.biz". This results in a public and a private certificate, both of which must be placed somewhere where Dovecot expects them and can read them. By default, Dovecot expects the following locations/filenames/owner/attributes: /etc/ssl/certs/dovecot.pem -rw-r--r-- root:dovecot 4624 bytes /etc/ssl/private/dovecot.pem -rw------- root:dovecot 1743 bytes If we may make a suggestion: rename the generated certificates in both locations to dovecot.pem.bak, place your generated certificates in their place, and set the owner/permissions like displayed here. However, if you've generated your own keys, you might have used a passphrase on the private key. You'll have to tell dovecot about it in its configuration file /etc/dovecot/dovecot.conf. To this end, edit the corresponding section by uncommenting the "ssl_" lines, and using your private key password (e.g. "zM7Ertq12") in the appropriate line: ssl_cert_file = /etc/ssl/certs/dovecot.pem ssl_key_file = /etc/ssl/private/dovecot.pem # If key file is password protected, give the password here. Alternatively # give it when starting dovecot with -p parameter. ssl_key_password = zM7Ertq12 Naturally you are free to place the keys in a different location, and/or use a different name... ==Finishing up== This is a good moment to test your configuration, if you haven't been able to test your work inbetween. If everything works as expected, you can add bells and whistles to your configuration. ===''smtpd'' TLS encryption=== The first addition we'd like to present covers the way Postfix handles incoming connections. Since authentication works, we can have Postfix distrust every (unauthenticated) connection: postconf -e mynetworks= Furthermore, since a default SSL certificate is installed by the Debian Postfix installation routine, we can encrypt all our connections using TLS; we enforce this using postconf -e smtpd_use_tls=yes postconf -e smtpd_tls_auth_only=yes Of course, you need to adjust the settings of your IMAP client so that it properly uses TLS and properly authenticates itself. If TLS works, you'll probably want to change the certificate as you have for Dovecot in the previous section. This is again pretty easy. If you haven't yet, now is the time to [[Creating_digital_certificates_with_our_root_certificate | creating that custom SSL certificate]] for our mail server - but you have to make sure that you DON'T use a password on the private key. Unlike Dovecot, Postfix cannot be told the password to the private key somewhere. For starters, look at the TLS-section of your ''main.cf'' that you currently have. Chances are a big chunk of it looks like this: # TLS parameters smtpd_tls_cert_file=/etc/ssl/certs/ssl-cert-snakeoil.pem smtpd_tls_key_file=/etc/ssl/private/ssl-cert-snakeoil.key smtpd_use_tls=yes Now all you need to do is replace the name of the snakeoil-keys with those of appropriate ssl-certificates, the private key of which needs to be NOT passphrase-protected. For this you could copy the Dovecot certificates, if you strip that passphrase in the manner described in the [[Creating_digital_certificates_with_our_root_certificate#Creating_an_SSL_certificate | SSL certificate section]]. The ''main.cf'' then would become: # TLS parameters smtpd_tls_cert_file=/etc/ssl/certs/postfix.pem smtpd_tls_key_file=/etc/ssl/private/postfix.key smtpd_use_tls=yes Restart Postfix, and presto. === Other additions === If everything ''still'' works after these changes, then congratulations, you now have a powerful, flexible and pretty secure mail setup. Of course, there are always points for improvements. We'll cover these in separate pages. One page that we want to direct you to now, is * [[Antispam measures]] for our Postfix mailserver f7a9c78e5c0812c357418109a0ef60d0c22f0398 0 1488 2444 2395 2009-08-28T07:48:18Z Insomnia 3 /* Preparing for certificate creation */ wikitext text/x-wiki ==Preparing for certificate creation== When we're going to create certificates, we're going to use the ''openssl'' command twice: * once to create a "certificate signing request", in which we define all information to be included in the certificate, and actually generate the public and private key parts of the key pair, and * once to instruct the OpenSSL package to sign the certificate with our CA root certificate. The first step thus '''creates''' the actual keypair, and the second step '''signs''' the public key. However, we're going to need to input a lot of parameters on the ''openssl'' command line. We can make things a bit easier for us by specifying these in the ''openssl.cnf'' file, just as we have added some values when creating the CA itself. To be precise, we're going to add '''X.509 V3 extensions''' By default OpenSSL generates V1 certificates, but if we're not extremely worried about offending certain ancient web browsers, we can add V3 extensions, and even make ''openssl'' do that by default. To do this, we find in ''/etc/ssl/openssl.cnf'' the following line in the section ''[ req ]'', which is likely present but commented out: req_extensions = v3_req # The extensions to add to a certificate request Simply remove the # sign in front of it, so that it appears as given above. This by default enables V3 extensions. Furthermore, check the section ''[ v3_req ]''. It should look like this: [ v3_req ] # Extensions to add to a certificate request basicConstraints = CA:FALSE keyUsage = nonRepudiation, digitalSignature, keyEncipherment subjectKeyIdentifier = hash What is added is the last line, with ''subjectKeyIdentifier''; this line specifies how to identify the public key being certified, so that distinct keys used by the same subject can be differentiated (e.g. as key updating occurs, for example). Four values are possible, but the IETF Public Key Infrastructure (PKIX) working group recommends the setting ''subjectKeyIdentifier=hash'' ==Creating an SSL certificate== Now we can create an SSL certificate for a web server. For the Common Name of the certificate, we need the '''exact''' name of the web server that'll offer the SSL connections. However, some servers run different websites as Virtual Hosts, so they could be running, for example, www.saruman.biz, as well as shop.saruman.biz. That might present a problem, because if the certificate is issued for www.saruman.biz, then each visitor of shop.saruman.biz will get a warning along the lines of "Warning: The website you're trying to visit is shop.saruman.biz, but the certificate offered is for www.saruman.biz". To prevent that, we could use the wildcard character in the name of the certificate, so as to generate a certificate for *.saruman.biz. === CA.sh - certificate creation made easy=== Since we have the ''openssl.cnf'' set up just right, and the ''CA.sh'' script primed, generating an SSL certificate is not very hard. From any old directory, run as root /usr/lib/ssl/misc/CA.sh -newreq This will create the signing request. The questions it'll ask, are * a PEM passphrase, with which to protect the private key of the key pair. Note: you cannot generate a signing request without passphrase, so the private key you'll generate will ''always'' have a passphrase. If this is not what you want, do not despair: you can easily remove the passphrase from the private key after it's been generated (see further down). So just use a passphrase, even if you don't need one. * Country/State/Locality/Organization/Organizational Unit; just as with the CA root certificate creation, these have your preprogrammed defaults that you may or may not change. * Common Name; here we MUST give the DNS name of the host that is going to use the certificate, e.g. ''shop.saruman.biz'', or ''*.saruman.biz''. * Challenge password; leave it blank, it's just to protect your signing request while en-route to the CA - but that's you anyway :-) * Optional company name; leave that blank too, it's also extra information for the CA. Now your private key and your certificate signing request (CSR) are ready; they're called ''newkey.pem'' and ''newreq.pem'' by default, and are located in your working directory. Time to do some signing! From that same working directory, run /usr/lib/ssl/misc/CA.sh -sign The script will show that it's using the config file ''/usr/lib/ssl/openssl.cnf'' (as we indeed wish), and then ask for the super-duper-secret passphrase to the CA private key (provided you've left that in directory ''/etc/ssl/ca/private''). Feed the script the passphrase, and it'll get to work. It'll check the request, then show you the details of the certificate you're about to sign. An example would be Certificate Details: Serial Number: 1 (0x1) Validity Not Before: Oct 27 09:34:00 2008 GMT Not After : Nov 1 09:34:00 2009 GMT Subject: countryName = NL stateOrProvinceName = Utrecht organizationName = Saruman.biz organizationalUnitName = Internet Dept. commonName = shop.saruman.biz emailAddress = webmaster@saruman.biz X509v3 extensions: X509v3 Basic Constraints: CA:FALSE Netscape Comment: OpenSSL Generated Certificate X509v3 Subject Key Identifier: 30:F2:61:80:AA:CF:1B:F0:3E:44:41:D6:38:CC:31:F0:94:28:BD:2B X509v3 Authority Key Identifier: keyid:80:41:F8:A5:1F:C2:27:6E:CF:A9:28:8E:8A:EF:83:E7:FD:8A:D5:26 Certificate is to be certified until Nov 1 09:34:00 2009 GMT (370 days) Sign the certificate? [y/n]: After doing your CA duty and diligently checking all the data, just press ''y''. The script certifies the request, and asks if it is to commit the request. This means it'll update it's own database, by saving a copy of the signed certificate in ''/etc/ssl/ca/newcerts'' named after its serial number (''01.pem'' for this example). Furthermore the script will record the serial and ID's of the generated certificate so that the next certificate will have a new serial number. And now: hey presto! We have a ''newcert.pem'' in our working directory! For good measure: * delete ''newreq.pem'' * rename the generated private key ''newkey.pem'' to ''shop.saruman.biz.seckey.pem'' * rename the generated public certificate ''newcert.pem'' to ''shop.saruman.biz.pem'' To remove the passphrase from the private key, use a command like this: openssl rsa -in shop.saruman.biz.seckey.key -out shop.saruman.biz.key.key This will make ''openssl'' ask for your passphrase, and then create the unsecured ''shop.saruman.biz.key.pem'' key file. Best practice: ALWAYS use a passphrase-protected key, unless the application cannot support it (e.g. Postfix). Save the secure private key and its PEM passphrase in a safe place (e.g. Keepass database). And if you removed the passphrase from the private key, then store it in an even safer place! Now you can deploy your certificate. (more on that in another section). === openssl - the hard way to certificate creation=== We don't actually need to use the ''CA.sh'' script, because we can do manually what the ''CA.sh'' script does. That gives us more control, but also more work. Let's see what we've got to do. We will now perform the first step in our "manual" certificate generation: we create a signing request with all the information that we want in our SSL certificate. We run the magic incantation - note how we already openssl req -new -nodes -keyout webmail.saruman.biz.key.pem -out webmail.saruman.biz.req.pem This generates a new private key (named ''webmail.saruman.biz.key.pem''), and a new, non-encrypted (because of ''-nodes''), key signing request named ''webmail.saruman.biz.req.pem''. We can leave out terms like ''-newkey rsa:2048'' and ''-days 370'' since we've put that in the configuration file. And naturally you're free to choose your own names for the keys. FIXME - need the full process here === Validating the generated certificates=== Again, we can use the ''openssl'' command to validate the keys we've generated. For instance, the ''CA.sh'' generated certificate, after renaming, is verified with openssl x509 -in shop.saruman.biz.pem -noout -purpose Certificate purposes: SSL client : Yes SSL client CA : No SSL server : Yes SSL server CA : No Netscape SSL server : Yes Netscape SSL server CA : No S/MIME signing : Yes S/MIME signing CA : No S/MIME encryption : Yes S/MIME encryption CA : No CRL signing : Yes CRL signing CA : No Any Purpose : Yes Any Purpose CA : Yes OCSP helper : Yes OCSP helper CA : No Notice that the certificate is valid for everything except CA tasks. Likewise, using ''-dates'' instead of ''-purpose'' lets you see the validity time period, and ''-text'' gives the whole text of the certificate. Note the line marked "issuer", and see how your own CA is referenced there. 4793d7efda9a324f01a1c03dcbee52029400cc95 0 1590 2446 2009-08-29T07:34:46Z Saruman! 2 skinning started wikitext text/x-wiki MediaWiki can have almost any look you want, because its look is determined by a "skin" that consists mainly of CSS stylesheets. For instance, on [http://www.chekmate.org/wiki/index.php/MediaWiki_Primer chekmate.org] we found this trick: #p-nav,#p-search,#p-tb,#footer { opacity:0.83; } /* make a few corners round, only supported by moz/firefox/other gecko browsers for now */ #p-cactions ul li, #p-cactions ul li a { -moz-border-radius-topleft: 0.4em; -moz-border-radius-topright: 0.4em; } #content { -moz-border-radius-topleft: 0.6em; -moz-border-radius-bottomleft: 0.6em; } div.pBody { -moz-border-radius-topright: 0.4em; -moz-border-radius-bottomright: 0.4em; } b5d2c4cb778733406eda745a710e3c01ab68539d 0 1466 2448 2293 2009-08-29T08:14:38Z Insomnia 3 /* Moving the MySQL databases */ wikitext text/x-wiki == MySQL installation == As with any package to be installed: use aptitude, update your APT, then make sure all your (other) software is up-to-date. Then find package ''mysql-server'' - under Debian 5.0 "Lenny" it'll be version 5.0.51a-something. Installing it will also automatically install some dependent packages, like mysql-common, mysql-client etcetera. So after downloading some 40MiB of files, MySQL is installed. The installation script under Debian Lenny asks you for a password for the MySQL root user. Think up a strong password for the MySQL root user; something like ''waYacUbaT2uW''. DON'T use this example password, [http://www.pctools.com/guides/password/ generate your own one!]. DO NOT use the password of the Linux ''root'' user. Should you consult [http://dev.mysql.com/doc/refman/5.0/en/unix-post-installation.html the official MySQL documentation], you might see mention of the ''mysql_install_db'' script - do not worry about that, since Debian has run it for you when it was setting up the database. The standard user accounts that have been created by the installation script are: * 'root'@'localhost' * 'root'@'<hostname>' * 'root'@'127.0.0.1' All three root accounts are secured with the same password, the one you specified when installing the package ''mysql-server''. ---- '''NOTE for Debian 4.0 "Etch"''' When you install MySQL under Etch, there are two root accounts with empty passwords, and two anonymous accounts. NOT safe! You'll want to rectify this in order to secure your MySQL server. Please take the following steps. Start the MySQL client from the command line: mysql -u root Then, from the mysql client prompt, set the password for the MySQL root users. They can be treated as two different accounts, but we don't recommend that. We thus give both accounts the same password: mysql> SET PASSWORD FOR 'root'@'localhost' = PASSWORD('waYacUbaT2uW'); mysql> SET PASSWORD FOR 'root'@'<hostname>' = PASSWORD('waYacUbaT2uW'); Furthermore, there are two anonymous accounts created. These also have no password, and get full permission on the ''test'' database, as well as on any database who's name begins with ''test_''. These accounts can be fitted with a password (like we did for root - just use two quotes with nothing in between them, instead of two quotes with ''root'' in between), or they can be removed - which we recommend. The (single) command for this is: <pre>mysql> DROP USER '';</pre> '''End of NOTE''' ---- To verify the installation you might want to take some of the following steps: * run ''mysqlshow -u root -p'', and see if that command outputs at least two databases (''information_schema'' and ''mysql''); * check out the settings of your MySQL server by running ''mysqladmin -u root -p variables'' (piping the output to ''less'' or a file, if necessary); * have a peek in ''/var/lib/mysql''; the database data files should be there; * check ''/var/log'' for two logfiles ''mysql.err'' and ''mysql.log''. ==Moving the MySQL databases== By default the location of your Debian MySQL databases is ''/var/lib/mysql/<database>''. However, sometimes you wish your databases to be in a different location. E.g. ''/data/mysql'', where ''/data'' is a mounted dedicated RAID array. Or perhaps even ''/data/mysql'' is its own array. Whatever the reason, to move ''all'' MySQL databases from ''/var/lib/mysql'' to another location, you can follow these steps: * Create the new directory, e.g. ''/data/mysql'' * Make this directory owned by user/group ''mysql'' cd /data mkdir mysql chown mysql:mysql mysql * Shut down the database server with one of the following commands: mysqladmin -u root -p shutdown invoke-rc.d mysql stop * Make a backup copy of ''/etc/mysql/my.cnf'', then edit this file. Find the section ''[mysqld]'' and change the line ''datadir = /var/lib/mysql'' to datadir = /data/mysql * As root, move (or better yet: copy) ''all'' of the content of ''/var/lib/mysql'' over to ''/data/mysql''. Make sure you don't accidentally change the ownership or permissions of the files and folders in the ''/var/lib/mysql'' folder. We expect each and every file and folder to be owned by ''mysql:mysql''. Copy command would be (as root): cp -p -r /var/lib/mysql/* /data/mysql * Check and doublecheck your ''my.cnf'' settings and your database file owners, attributes and size. After the next step, there ''may'' be no way back! * Start up your database server: invoke-rc.d mysql start * Check the working of your MySQL server: ** issue the following command to get status information (to see if MySQL is running after your start command): invoke-rc.d mysql status ** look under ''/var/log'' for the default MySQL log files ''mysql.log'' and ''mysql.err'' ** check your SysLog (standard: ''/var/log/syslog'') for MySQL error messages, since the default Debian configuration is to log MySQL errors there, rather than in the previously mentioned MySQL logfiles. == MYsql commands == DELETE FROM "table name" WHERE "colomn name"='VALUE' UPDATE "table name" set "colomn name" = 'VALUE' where "colomn name" = 'VALUE'; eac5475a64f77bbf61e4909b8c1fb9147d600537 0 1591 2449 2009-08-29T09:07:03Z Insomnia 3 Horde3 wikitext text/x-wiki apt-get install horde3 Now make the site available In etc/apache2-sites-available there is already a file horde3 Alias /horde3 /usr/share/horde3 <Directory /usr/share/horde3> Options FollowSymLinks AllowOverride Limit deny from all allow from all 192.168 127.0.0 </Directory> <Location /horde3> SSLCipherSuite HIGH:MEDIUM </Location> And make the site enabled ln -s /etc/apache2/sites-available/horde3 00X-horde3 == Database == To make the database there are several scripts. We use MYsql: gunzip /usr/share/doc/horde3/examples/scripts/sql/create.mysql.sql.gz and change the password in the script for the user horde Run the script mysql -u root -p source /usr/share/doc/horde3/examples/scripts/sql/create.mysql.sql Now we can browse to the site http://192.168.70.9/horde3/ This will give us the following Horde3 configuration disabled by default because the administration/install wizard gives the whole world too much access to the system. Read /usr/share /doc/horde3/README.Debian.gz on how to allow access. To use the web configuration wizard we need to change the following chgrp www-data /etc/horde/horde3/ db3c18590bf86f673f30149df28a8c6adbea9e97 2450 2449 2009-08-29T20:23:02Z 82.161.20.132 0 /* Database */ wikitext text/x-wiki apt-get install horde3 Now make the site available In etc/apache2-sites-available there is already a file horde3 Alias /horde3 /usr/share/horde3 <Directory /usr/share/horde3> Options FollowSymLinks AllowOverride Limit deny from all allow from all 192.168 127.0.0 </Directory> <Location /horde3> SSLCipherSuite HIGH:MEDIUM </Location> And make the site enabled ln -s /etc/apache2/sites-available/horde3 00X-horde3 == Database == To make the database there are several scripts in /usr/share/doc/horde3/examples/scripts/. We use MYsql: gunzip /usr/share/doc/horde3/examples/scripts/sql/create.mysql.sql.gz and change the password in the script for the user horde Run the script mysql -u root -p source /usr/share/doc/horde3/examples/scripts/sql/create.mysql.sql == Configure == To use the web configuration wizard we need to change the following chgrp -R www-data /etc/horde/horde3/ chmod -R 750 /etc/horde/horde3 chmod 777 /etc/horde/horde3/conf.php cp /etc/horde/horde3/conf.php /etc/horde/horde3/conf.php.bak chmod 777 /etc/horde/horde3/conf.php.bak Prepare log file: touch /var/log/horde/horde3.log chown root.www-data /var/log/horde/horde3.log chmod 770 /var/log/horde/horde3.log Now we can browse to the site http://192.168.70.9/horde3/ This will give us the following Horde3 configuration disabled by default because the administration/install wizard gives the whole world too much access to the system. Read /usr/share /doc/horde3/README.Debian.gz on how to allow access. Change /var/log/horde/horde3/conf.php and comment line 2 and 3 leave the first line as is. Klik op setup en klik 'horde setup' - edit database -> username en WW - connect to database = tcp/ip - localhost - naam database - edit preference system -> SQL database - edit authentication -> Administrator,user@sample.com - SQL authentication klik generate Horde Configurtion Could not save the backup configuration file /usr/share/horde3/config/conf.bak.php Not solved yet - edit users -> root 5100addc53b4c765b0c6ade2f78d7516327f6bd7 2451 2450 2009-08-30T08:08:05Z Saruman! 2 added link to debian wiki wikitext text/x-wiki A standard howto can be found at [http://wiki.debian.org/Horde]. Our notes on Horde3 installation are the following: apt-get install horde3 Now make the site available In etc/apache2-sites-available there is already a file horde3 Alias /horde3 /usr/share/horde3 <Directory /usr/share/horde3> Options FollowSymLinks AllowOverride Limit deny from all allow from all 192.168 127.0.0 </Directory> <Location /horde3> SSLCipherSuite HIGH:MEDIUM </Location> And make the site enabled ln -s /etc/apache2/sites-available/horde3 00X-horde3 == Database == To make the database there are several scripts in /usr/share/doc/horde3/examples/scripts/. We use MYsql: gunzip /usr/share/doc/horde3/examples/scripts/sql/create.mysql.sql.gz and change the password in the script for the user horde Run the script mysql -u root -p source /usr/share/doc/horde3/examples/scripts/sql/create.mysql.sql == Configure == To use the web configuration wizard we need to change the following chgrp -R www-data /etc/horde/horde3/ chmod -R 750 /etc/horde/horde3 chmod 777 /etc/horde/horde3/conf.php cp /etc/horde/horde3/conf.php /etc/horde/horde3/conf.php.bak chmod 777 /etc/horde/horde3/conf.php.bak Prepare log file: touch /var/log/horde/horde3.log chown root.www-data /var/log/horde/horde3.log chmod 770 /var/log/horde/horde3.log Now we can browse to the site http://192.168.70.9/horde3/ This will give us the following Horde3 configuration disabled by default because the administration/install wizard gives the whole world too much access to the system. Read /usr/share /doc/horde3/README.Debian.gz on how to allow access. Change /var/log/horde/horde3/conf.php and comment line 2 and 3 leave the first line as is. Klik op setup en klik 'horde setup' - edit database -> username en WW - connect to database = tcp/ip - localhost - naam database - edit preference system -> SQL database - edit authentication -> Administrator,user@sample.com - SQL authentication klik generate Horde Configurtion Could not save the backup configuration file /usr/share/horde3/config/conf.bak.php Not solved yet - edit users -> root 52c0809c1f8956bf8bc8b1b90e3e1e300eaedaec 2452 2451 2009-08-30T09:24:21Z Insomnia 3 /* Configure */ wikitext text/x-wiki A standard howto can be found at [http://wiki.debian.org/Horde]. Our notes on Horde3 installation are the following: apt-get install horde3 Now make the site available In etc/apache2-sites-available there is already a file horde3 Alias /horde3 /usr/share/horde3 <Directory /usr/share/horde3> Options FollowSymLinks AllowOverride Limit deny from all allow from all 192.168 127.0.0 </Directory> <Location /horde3> SSLCipherSuite HIGH:MEDIUM </Location> And make the site enabled ln -s /etc/apache2/sites-available/horde3 00X-horde3 == Database == To make the database there are several scripts in /usr/share/doc/horde3/examples/scripts/. We use MYsql: gunzip /usr/share/doc/horde3/examples/scripts/sql/create.mysql.sql.gz and change the password in the script for the user horde Run the script mysql -u root -p source /usr/share/doc/horde3/examples/scripts/sql/create.mysql.sql == Configure == To use the web configuration wizard we need to change the following chgrp -R www-data /etc/horde/horde3/ chmod -R 750 /etc/horde/horde3 chmod 777 /etc/horde/horde3/conf.php cp /etc/horde/horde3/conf.php /etc/horde/horde3/conf.php.bak chmod 777 /etc/horde/horde3/conf.php.bak Prepare log file: touch /var/log/horde/horde3.log chown root.www-data /var/log/horde/horde3.log chmod 770 /var/log/horde/horde3.log Now we can browse to the site http://192.168.70.9/horde3/ This will give us the following Horde3 configuration disabled by default because the administration/install wizard gives the whole world too much access to the system. Read /usr/share /doc/horde3/README.Debian.gz on how to allow access. Change /var/log/horde/horde3/conf.php and comment line 2 and 3 leave the first line as is. Choose setup from the menu 'horde setup' - edit database -> username en WW - connect to database = tcp/ip - localhost - naam database - edit preference system -> SQL database - edit authentication -> Administrator,user@sample.com - SQL authentication Choose Users from the menu - add users -> user@sample.com klik generate Horde Configurtion Could not save the backup configuration file /usr/share/horde3/config/conf.bak.php I had to change permissions on the /etc/horde/horde3 folder == IMP == apt-get install imp4 Now prepare file permissions for web configuration: chmod 777 /etc/horde/imp4/conf.php touch /etc/horde/imp4/conf.bak.php chmod 777 /etc/horde/imp4/conf.bak.php Choose setup from the menu 'mail(imp)' Generate your configuration (GPG/PGP, user constraints, enable spam/ham report, hooks...). And when you're done change the permissions back chmod 644 /etc/horde/imp4/conf.php chmod 700 /etc/horde/imp4/conf.bak.php And specify your mail server(s) in /etc/horde/imp4/servers.php file $servers['imap'] = array( 'name' => 'IMAP Server', 'server' => 'localhost', 'hordeauth' => 'full', 'protocol' => 'imap/notls', 'port' => 143, 'maildomain' => 'sample.com', 'smtphost' => 'localhost', 'smtpport' => 25, 'realm' => 'sample.com', 'preferred' => '', ); When you are ready, enable IMP in /etc/horde/horde3/registry.php file and verify if all is right. Yes, you read well, you MUST enable manually module in registry.php file after configuration! $this->applications['imp'] = array( 'fileroot' => '/usr/share/horde3/lib' . '/../imp', 'webroot' => $this->applications['horde']['webroot'] . '/imp', 'name' => _("Mail"), 'status' => 'active', 'provides' => array('mail', 'contacts/favouriteRecipients') ); Change the status from inactive to active b9bf30727e589d468cb8efc6ba76a0eda0f9b588 2453 2452 2009-08-30T18:58:17Z Saruman! 2 started updating wikitext text/x-wiki A standard howto for the Horde3 installation can be found at [http://wiki.debian.org/Horde wiki.debian.org]. Our notes on Horde3 installation are the following: ==Installation== First install the base package plus dependencies: apt-get install horde3 Now make the site available In ''/etc/apache2/sites-available'' the installation script has already placed a file horde3; the content will closely resemble Alias /horde3 /usr/share/horde3 <Directory /usr/share/horde3> Options FollowSymLinks AllowOverride Limit deny from all allow from all 192.168 127.0.0 </Directory> <Location /horde3> SSLCipherSuite HIGH:MEDIUM </Location> You could simply enable this site ln -s /etc/apache2/sites-available/horde3 00X-horde3 (or use ''a2ensite horde3''). Note that this makes the horde3 package available in every virtual host that you have. == Database == Horde needs its own database to keep information. To create that database there are several scripts in ''/usr/share/doc/horde3/examples/scripts/''. We use MySQL: gunzip /usr/share/doc/horde3/examples/scripts/sql/create.mysql.sql.gz and change the password in the script for the user ''horde''. We can run the script localhost:$ '''mysql -u root -p''' Enter password: Welcome to the MySQL monitor. Commands end with ; or \g. Your MySQL connection id is 4200 Server version: 5.0.51a-24+lenny1 (Debian) Type 'help;' or '\h' for help. Type '\c' to clear the buffer. mysql> '''source /usr/share/doc/horde3/examples/scripts/sql/create.mysql.sql''' == Configure == To use the web configuration wizard we need to change the following chgrp -R www-data /etc/horde/horde3/ chmod -R 750 /etc/horde/horde3 chmod 777 /etc/horde/horde3/conf.php cp /etc/horde/horde3/conf.php /etc/horde/horde3/conf.php.bak chmod 777 /etc/horde/horde3/conf.php.bak Prepare log file: touch /var/log/horde/horde3.log chown root.www-data /var/log/horde/horde3.log chmod 770 /var/log/horde/horde3.log Now we can browse to the site http://192.168.70.9/horde3/ This will give us the following Horde3 configuration disabled by default because the administration/install wizard gives the whole world too much access to the system. Read /usr/share /doc/horde3/README.Debian.gz on how to allow access. Change /var/log/horde/horde3/conf.php and comment line 2 and 3 leave the first line as is. Choose setup from the menu 'horde setup' - edit database -> username en WW - connect to database = tcp/ip - localhost - naam database - edit preference system -> SQL database - edit authentication -> Administrator,user@sample.com - SQL authentication Choose Users from the menu - add users -> user@sample.com klik generate Horde Configurtion Could not save the backup configuration file /usr/share/horde3/config/conf.bak.php I had to change permissions on the /etc/horde/horde3 folder == IMP == apt-get install imp4 Now prepare file permissions for web configuration: chmod 777 /etc/horde/imp4/conf.php touch /etc/horde/imp4/conf.bak.php chmod 777 /etc/horde/imp4/conf.bak.php Choose setup from the menu 'mail(imp)' Generate your configuration (GPG/PGP, user constraints, enable spam/ham report, hooks...). And when you're done change the permissions back chmod 644 /etc/horde/imp4/conf.php chmod 700 /etc/horde/imp4/conf.bak.php And specify your mail server(s) in /etc/horde/imp4/servers.php file $servers['imap'] = array( 'name' => 'IMAP Server', 'server' => 'localhost', 'hordeauth' => 'full', 'protocol' => 'imap/notls', 'port' => 143, 'maildomain' => 'sample.com', 'smtphost' => 'localhost', 'smtpport' => 25, 'realm' => 'sample.com', 'preferred' => '', ); When you are ready, enable IMP in /etc/horde/horde3/registry.php file and verify if all is right. Yes, you read well, you MUST enable manually module in registry.php file after configuration! $this->applications['imp'] = array( 'fileroot' => '/usr/share/horde3/lib' . '/../imp', 'webroot' => $this->applications['horde']['webroot'] . '/imp', 'name' => _("Mail"), 'status' => 'active', 'provides' => array('mail', 'contacts/favouriteRecipients') ); Change the status from inactive to active 5bec8c6ac4ad0b30a93fec9bc14fea85a3af57bb 2454 2453 2009-08-30T19:21:47Z Saruman! 2 installation procedure finished wikitext text/x-wiki A standard howto for the Horde3 installation can be found at [http://wiki.debian.org/Horde wiki.debian.org]. Our notes on Horde3 installation are the following: ==Installation== First make sure you have a nice little [[LAMP]] server running, with [[Database_101|MySQL]], [[Apache2_and_PHP5|Apache2, PHP5]] et cetera. Now install the base package plus dependencies: apt-get install horde3 Now make the site available: in ''/etc/apache2/sites-available'', find the site(s) that will get horde3 enabled. In the site definition files, include the following snippet: Alias /horde3 /usr/share/horde3 <Directory /usr/share/horde3> Options FollowSymLinks AllowOverride Limit deny from all allow from all 192.168 127.0.0 </Directory> <Files ~ "\.(inc|bak)$"> deny from all </Files> If you include the code in an SSL protected site, you can also add <Location /horde3> SSLCipherSuite HIGH:MEDIUM </Location> Restart your Apache webserver, and horde3 is operational. However, if you surf to ''<nowiki>http://your.web.server/horde3'' you read this: Horde3 configuration disabled by default because the administration/install wizard gives the whole world too much access to the system. Read /usr/share/doc/horde3/README.Debian.gz on how to allow access. ==Database== Horde needs its own database to keep information. To create that database there are several scripts in ''/usr/share/doc/horde3/examples/scripts/''. We use MySQL: gunzip /usr/share/doc/horde3/examples/scripts/sql/create.mysql.sql.gz and change the password in the script for the user ''horde''. We can run the script localhost:$ '''mysql -u root -p''' Enter password: Welcome to the MySQL monitor. Commands end with ; or \g. Your MySQL connection id is 4200 Server version: 5.0.51a-24+lenny1 (Debian) Type 'help;' or '\h' for help. Type '\c' to clear the buffer. mysql> '''source /usr/share/doc/horde3/examples/scripts/sql/create.mysql.sql''' ==Configure== To use the web configuration wizard we need to change the following chgrp -R www-data /etc/horde/horde3/ chmod -R 750 /etc/horde/horde3 chmod 777 /etc/horde/horde3/conf.php cp /etc/horde/horde3/conf.php /etc/horde/horde3/conf.php.bak chmod 777 /etc/horde/horde3/conf.php.bak Prepare log file: touch /var/log/horde/horde3.log chown root.www-data /var/log/horde/horde3.log chmod 770 /var/log/horde/horde3.log Now we can browse to the site http://192.168.70.9/horde3/ This will give us the following Horde3 configuration disabled by default because the administration/install wizard gives the whole world too much access to the system. Read /usr/share /doc/horde3/README.Debian.gz on how to allow access. Change /var/log/horde/horde3/conf.php and comment line 2 and 3 leave the first line as is. Choose setup from the menu 'horde setup' - edit database -> username en WW - connect to database = tcp/ip - localhost - naam database - edit preference system -> SQL database - edit authentication -> Administrator,user@sample.com - SQL authentication Choose Users from the menu - add users -> user@sample.com klik generate Horde Configurtion Could not save the backup configuration file /usr/share/horde3/config/conf.bak.php I had to change permissions on the /etc/horde/horde3 folder == IMP == apt-get install imp4 Now prepare file permissions for web configuration: chmod 777 /etc/horde/imp4/conf.php touch /etc/horde/imp4/conf.bak.php chmod 777 /etc/horde/imp4/conf.bak.php Choose setup from the menu 'mail(imp)' Generate your configuration (GPG/PGP, user constraints, enable spam/ham report, hooks...). And when you're done change the permissions back chmod 644 /etc/horde/imp4/conf.php chmod 700 /etc/horde/imp4/conf.bak.php And specify your mail server(s) in /etc/horde/imp4/servers.php file $servers['imap'] = array( 'name' => 'IMAP Server', 'server' => 'localhost', 'hordeauth' => 'full', 'protocol' => 'imap/notls', 'port' => 143, 'maildomain' => 'sample.com', 'smtphost' => 'localhost', 'smtpport' => 25, 'realm' => 'sample.com', 'preferred' => '', ); When you are ready, enable IMP in /etc/horde/horde3/registry.php file and verify if all is right. Yes, you read well, you MUST enable manually module in registry.php file after configuration! $this->applications['imp'] = array( 'fileroot' => '/usr/share/horde3/lib' . '/../imp', 'webroot' => $this->applications['horde']['webroot'] . '/imp', 'name' => _("Mail"), 'status' => 'active', 'provides' => array('mail', 'contacts/favouriteRecipients') ); Change the status from inactive to active 70e93334c0f9a8795c7c25ef6ac41e169802b13c 2455 2454 2009-08-30T19:34:53Z Saruman! 2 Database setup done wikitext text/x-wiki A standard howto for the Horde3 installation can be found at [http://wiki.debian.org/Horde wiki.debian.org]. Our notes on Horde3 installation are the following: ==Installation== First make sure you have a nice little [[LAMP]] server running, with [[Database_101|MySQL]], [[Apache2_and_PHP5|Apache2, PHP5]] et cetera. Now install the base package plus dependencies: apt-get install horde3 Now make the site available: in ''/etc/apache2/sites-available'', find the site(s) that will get horde3 enabled. In the site definition files, include the following snippet: Alias /horde3 /usr/share/horde3 <Directory /usr/share/horde3> Options FollowSymLinks AllowOverride Limit deny from all allow from all 192.168 127.0.0 </Directory> <Files ~ "\.(inc|bak)$"> deny from all </Files> If you include the code in an SSL protected site, you can also add <Location /horde3> SSLCipherSuite HIGH:MEDIUM </Location> Restart your Apache webserver, and horde3 is operational. However, if you surf to ''<nowiki>http://your.web.server/horde3</nowiki>'' you read this: {| border="1" |Horde3 configuration disabled by default because the administration/install wizard gives the whole world too much access to the system. Read /usr/share/doc/horde3/README.Debian.gz on how to allow access. |} No worries, we'll get horde operational with the following steps. ==Database== Horde needs its own database to keep information. To create that database there are several scripts in ''/usr/share/doc/horde3/examples/scripts/''. We use MySQL, so we unpack the MySQL setup script: cd /usr/share/doc/horde3/examples/scripts/sql gunzip create.mysql.sql.gz This unpacks ''create.mysql.sql'', in which we need to change the password for the user ''horde'', in line 27-29. They reads -- IMPORTANT: Change this password. PASSWORD('horde') ); We change the default password ''horde'' to something stronger. We can now run the script by feeding it into the MySQL client: localhost:# '''mysql -u root -p < /usr/share/doc/horde3/examples/scripts/sql/create.mysql.sql.gz''' Enter password: localhost:# _ Now remove the ''create.mysql.sql.gz'' file, or change the password back to 'horde', or secure access to the file! We don't want anyone to read the horde database password. ==Configure== To use the web configuration wizard we need to change the following chgrp -R www-data /etc/horde/horde3/ chmod -R 750 /etc/horde/horde3 chmod 777 /etc/horde/horde3/conf.php cp /etc/horde/horde3/conf.php /etc/horde/horde3/conf.php.bak chmod 777 /etc/horde/horde3/conf.php.bak Prepare log file: touch /var/log/horde/horde3.log chown root.www-data /var/log/horde/horde3.log chmod 770 /var/log/horde/horde3.log Now we can browse to the site http://192.168.70.9/horde3/ This will give us the following Horde3 configuration disabled by default because the administration/install wizard gives the whole world too much access to the system. Read /usr/share /doc/horde3/README.Debian.gz on how to allow access. Change /var/log/horde/horde3/conf.php and comment line 2 and 3 leave the first line as is. Choose setup from the menu 'horde setup' - edit database -> username en WW - connect to database = tcp/ip - localhost - naam database - edit preference system -> SQL database - edit authentication -> Administrator,user@sample.com - SQL authentication Choose Users from the menu - add users -> user@sample.com klik generate Horde Configurtion Could not save the backup configuration file /usr/share/horde3/config/conf.bak.php I had to change permissions on the /etc/horde/horde3 folder == IMP == apt-get install imp4 Now prepare file permissions for web configuration: chmod 777 /etc/horde/imp4/conf.php touch /etc/horde/imp4/conf.bak.php chmod 777 /etc/horde/imp4/conf.bak.php Choose setup from the menu 'mail(imp)' Generate your configuration (GPG/PGP, user constraints, enable spam/ham report, hooks...). And when you're done change the permissions back chmod 644 /etc/horde/imp4/conf.php chmod 700 /etc/horde/imp4/conf.bak.php And specify your mail server(s) in /etc/horde/imp4/servers.php file $servers['imap'] = array( 'name' => 'IMAP Server', 'server' => 'localhost', 'hordeauth' => 'full', 'protocol' => 'imap/notls', 'port' => 143, 'maildomain' => 'sample.com', 'smtphost' => 'localhost', 'smtpport' => 25, 'realm' => 'sample.com', 'preferred' => '', ); When you are ready, enable IMP in /etc/horde/horde3/registry.php file and verify if all is right. Yes, you read well, you MUST enable manually module in registry.php file after configuration! $this->applications['imp'] = array( 'fileroot' => '/usr/share/horde3/lib' . '/../imp', 'webroot' => $this->applications['horde']['webroot'] . '/imp', 'name' => _("Mail"), 'status' => 'active', 'provides' => array('mail', 'contacts/favouriteRecipients') ); Change the status from inactive to active 79d509164ad0b1e0dac048b2f523c3f8540fc617 2456 2455 2009-08-30T19:50:13Z Saruman! 2 /* Configure */ expounded wikitext text/x-wiki A standard howto for the Horde3 installation can be found at [http://wiki.debian.org/Horde wiki.debian.org]. Our notes on Horde3 installation are the following: ==Installation== First make sure you have a nice little [[LAMP]] server running, with [[Database_101|MySQL]], [[Apache2_and_PHP5|Apache2, PHP5]] et cetera. Now install the base package plus dependencies: apt-get install horde3 Now make the site available: in ''/etc/apache2/sites-available'', find the site(s) that will get horde3 enabled. In the site definition files, include the following snippet: Alias /horde3 /usr/share/horde3 <Directory /usr/share/horde3> Options FollowSymLinks AllowOverride Limit deny from all allow from all 192.168 127.0.0 </Directory> <Files ~ "\.(inc|bak)$"> deny from all </Files> If you include the code in an SSL protected site, you can also add <Location /horde3> SSLCipherSuite HIGH:MEDIUM </Location> Restart your Apache webserver, and horde3 is operational. However, if you surf to ''<nowiki>http://your.web.server/horde3</nowiki>'' you read this: {| border="1" |Horde3 configuration disabled by default because the administration/install wizard gives the whole world too much access to the system. Read /usr/share/doc/horde3/README.Debian.gz on how to allow access. |} No worries, we'll get horde operational with the following steps. ==Database== Horde needs its own database to keep information. To create that database there are several scripts in ''/usr/share/doc/horde3/examples/scripts/''. We use MySQL, so we unpack the MySQL setup script: cd /usr/share/doc/horde3/examples/scripts/sql gunzip create.mysql.sql.gz This unpacks ''create.mysql.sql'', in which we need to change the password for the user ''horde'', in line 27-29. They reads -- IMPORTANT: Change this password. PASSWORD('horde') ); We change the default password ''horde'' to something stronger. We can now run the script by feeding it into the MySQL client: localhost:# '''mysql -u root -p < /usr/share/doc/horde3/examples/scripts/sql/create.mysql.sql.gz''' Enter password: localhost:# _ Now remove the ''create.mysql.sql.gz'' file, or change the password back to 'horde', or secure access to the file! We don't want anyone to read the horde database password. ==Configure== To use the web configuration wizard we need to do a couple of things in directory ''/etc/horde/horde3''. First, we need most files to be owned by root:www-data and have permissions 750. Next, create a backup ''conf.php'' file, named ''conf.bak.php'', and change the permissions on both ''conf*.php'' files to 777: chgrp -R www-data /etc/horde/horde3/ chmod -R 750 /etc/horde/horde3 touch etc/horde/horde3/conf.bak.php chmod 777 /etc/horde/horde3/conf*.php Next, we can prepare an alternative location for the log file, in line with our [[Debian_Lenny_base_server|Lenny base server configuration]]: mkdir /var/appsloghorde touch /var/appsloghorde/horde3.log chown root.www-data /var/log/horde/horde3.log chmod 770 /var/log/horde/horde3.log Now edit ''/etc/horde/horde3/conf.php'' and remove line 2 and 3. We should now be able to browse to the Horde3 admin page, something like: http://server.local.lan/horde3/ ==Web configuration== Choose setup from the menu 'horde setup' - edit database -> username en WW - connect to database = tcp/ip - localhost - naam database - edit preference system -> SQL database - edit authentication -> Administrator,user@sample.com - SQL authentication Choose Users from the menu - add users -> user@sample.com klik generate Horde Configurtion Could not save the backup configuration file /usr/share/horde3/config/conf.bak.php I had to change permissions on the /etc/horde/horde3 folder == IMP == apt-get install imp4 Now prepare file permissions for web configuration: chmod 777 /etc/horde/imp4/conf.php touch /etc/horde/imp4/conf.bak.php chmod 777 /etc/horde/imp4/conf.bak.php Choose setup from the menu 'mail(imp)' Generate your configuration (GPG/PGP, user constraints, enable spam/ham report, hooks...). And when you're done change the permissions back chmod 644 /etc/horde/imp4/conf.php chmod 700 /etc/horde/imp4/conf.bak.php And specify your mail server(s) in /etc/horde/imp4/servers.php file $servers['imap'] = array( 'name' => 'IMAP Server', 'server' => 'localhost', 'hordeauth' => 'full', 'protocol' => 'imap/notls', 'port' => 143, 'maildomain' => 'sample.com', 'smtphost' => 'localhost', 'smtpport' => 25, 'realm' => 'sample.com', 'preferred' => '', ); When you are ready, enable IMP in /etc/horde/horde3/registry.php file and verify if all is right. Yes, you read well, you MUST enable manually module in registry.php file after configuration! $this->applications['imp'] = array( 'fileroot' => '/usr/share/horde3/lib' . '/../imp', 'webroot' => $this->applications['horde']['webroot'] . '/imp', 'name' => _("Mail"), 'status' => 'active', 'provides' => array('mail', 'contacts/favouriteRecipients') ); Change the status from inactive to active 7ceb2eefff8f3309a9d409520f1c6cd5beebb9cc 2457 2456 2009-08-30T20:24:06Z Saruman! 2 /* Web configuration */ adapted for ldap wikitext text/x-wiki A standard howto for the Horde3 installation can be found at [http://wiki.debian.org/Horde wiki.debian.org]. Our notes on Horde3 installation are the following: ==Installation== First make sure you have a nice little [[LAMP]] server running, with [[Database_101|MySQL]], [[Apache2_and_PHP5|Apache2, PHP5]] et cetera. Now install the base package plus dependencies: apt-get install horde3 Now make the site available: in ''/etc/apache2/sites-available'', find the site(s) that will get horde3 enabled. In the site definition files, include the following snippet: Alias /horde3 /usr/share/horde3 <Directory /usr/share/horde3> Options FollowSymLinks AllowOverride Limit deny from all allow from all 192.168 127.0.0 </Directory> <Files ~ "\.(inc|bak)$"> deny from all </Files> If you include the code in an SSL protected site, you can also add <Location /horde3> SSLCipherSuite HIGH:MEDIUM </Location> Restart your Apache webserver, and horde3 is operational. However, if you surf to ''<nowiki>http://your.web.server/horde3</nowiki>'' you read this: {| border="1" |Horde3 configuration disabled by default because the administration/install wizard gives the whole world too much access to the system. Read /usr/share/doc/horde3/README.Debian.gz on how to allow access. |} No worries, we'll get horde operational with the following steps. ==Database== Horde needs its own database to keep information. To create that database there are several scripts in ''/usr/share/doc/horde3/examples/scripts/''. We use MySQL, so we unpack the MySQL setup script: cd /usr/share/doc/horde3/examples/scripts/sql gunzip create.mysql.sql.gz This unpacks ''create.mysql.sql'', in which we need to change the password for the user ''horde'', in line 27-29. They reads -- IMPORTANT: Change this password. PASSWORD('horde') ); We change the default password ''horde'' to something stronger. We can now run the script by feeding it into the MySQL client: localhost:# '''mysql -u root -p < /usr/share/doc/horde3/examples/scripts/sql/create.mysql.sql.gz''' Enter password: localhost:# _ Now remove the ''create.mysql.sql.gz'' file, or change the password back to 'horde', or secure access to the file! We don't want anyone to read the horde database password. ==Configure== To use the web configuration wizard we need to do a couple of things in directory ''/etc/horde/horde3''. First, we need most files to be owned by root:www-data and have permissions 750. Next, create a backup ''conf.php'' file, named ''conf.bak.php'', and change the permissions on both ''conf*.php'' files to 777: chgrp -R www-data /etc/horde/horde3/ chmod -R 750 /etc/horde/horde3 touch etc/horde/horde3/conf.bak.php chmod 777 /etc/horde/horde3/conf*.php Next, we can prepare an alternative location for the log file, in line with our [[Debian_Lenny_base_server|Lenny base server configuration]]: mkdir /var/appsloghorde touch /var/appsloghorde/horde3.log chown root.www-data /var/log/horde/horde3.log chmod 770 /var/log/horde/horde3.log Now edit ''/etc/horde/horde3/conf.php'' and remove line 2 and 3. We should now be able to browse to the Horde3 admin page, something like: http://server.local.lan/horde3/ ==Web configuration== Choose setup from the menu 'horde setup'. Note: fill at LEAST all the data mentioned hereunder, and only THEN click "Generate Horde Configuration". You '''cannot''' click that button in the mean time to "save your progress", because it will then shut you out of your Horde setup. * edit the data in tab "database" ** username: <nowiki>$conf[sql][username]</nowiki> = ''horde'' ** password: put after <nowiki>$conf[sql][password]</nowiki> the strong password we put in ''create.mysql.sql.gz'' ** connect to database: select <nowiki>$conf[sql][protocol]</nowiki> = ''tcp/ip'' ** where is that database located: <nowiki>$conf[sql][hostspec]</nowiki> = ''localhost'' ** The database name: <nowiki>$conf[sql][database]</nowiki> = ''horde'' * edit the data in tab "preference system ** set the preferences driver <nowiki>$conf[prefs][driver]</nowiki> to ''SQL database'' * edit the data in tab "authentication" - this section depends heavily on how you want to authenticate. Suppose you have an OpenLDAP server on your network, perhaps even on this same server, then it could be something like this: ** <nowiki>$conf[auth][admins]</nowiki> should have your own LDAP login, e.g. "john" ** <nowiki>$conf[auth][driver]</nowiki> must be ''LDAP authentication'' ** <nowiki>$conf[auth][params][hostspec]</nowiki> must be the LDAP server, e.g. "localhost" ** <nowiki>$conf[auth][params][basedn]</nowiki> will be the standard base DN, e.g. "dc=saruman,dc=biz" ** <nowiki>$conf[auth][params][binddn]</nowiki> must be the account that is allowed to bind, so it can check users; we use "cn=authenticator,dc=saruman,dc=biz" ** <nowiki>$conf[auth][params][password]</nowiki> contains the password of the binddn, in our case "authenticator"s password ("letmein", I believe it was :-) ** <nowiki>$conf[auth][params][uid]</nowiki> contains the attribute that contains the login name. This will often be "uid", as it is with us ** <nowiki>$conf[auth][params][objectclass]</nowiki> must contain an object class filter, with which horde can limit the results of its search. If all your horde users are in one single class, you can simply use that. E.g. we have all users member of "inetOrgPerson" so we can use that value. More settings can be made, but that can also be done at a later time. For now, click "Generate Horde Configuration". You will be thrown out, and must log back in with the specified admin account (LDAP account "john" in our example). == IMP == apt-get install imp4 Now prepare file permissions for web configuration: chmod 777 /etc/horde/imp4/conf.php touch /etc/horde/imp4/conf.bak.php chmod 777 /etc/horde/imp4/conf.bak.php Choose setup from the menu 'mail(imp)' Generate your configuration (GPG/PGP, user constraints, enable spam/ham report, hooks...). And when you're done change the permissions back chmod 644 /etc/horde/imp4/conf.php chmod 700 /etc/horde/imp4/conf.bak.php And specify your mail server(s) in /etc/horde/imp4/servers.php file $servers['imap'] = array( 'name' => 'IMAP Server', 'server' => 'localhost', 'hordeauth' => 'full', 'protocol' => 'imap/notls', 'port' => 143, 'maildomain' => 'sample.com', 'smtphost' => 'localhost', 'smtpport' => 25, 'realm' => 'sample.com', 'preferred' => '', ); When you are ready, enable IMP in /etc/horde/horde3/registry.php file and verify if all is right. Yes, you read well, you MUST enable manually module in registry.php file after configuration! $this->applications['imp'] = array( 'fileroot' => '/usr/share/horde3/lib' . '/../imp', 'webroot' => $this->applications['horde']['webroot'] . '/imp', 'name' => _("Mail"), 'status' => 'active', 'provides' => array('mail', 'contacts/favouriteRecipients') ); Change the status from inactive to active d47bb8ebf31cbca83ca6f113a0ac04f88e5ec6a8 2458 2457 2009-08-31T18:56:26Z Saruman! 2 link to imp wikitext text/x-wiki A standard howto for the Horde3 installation can be found at [http://wiki.debian.org/Horde wiki.debian.org]. Our notes on Horde3 installation are the following: ==Installation== First make sure you have a nice little [[LAMP]] server running, with [[Database_101|MySQL]], [[Apache2_and_PHP5|Apache2, PHP5]] et cetera. Now install the base package plus dependencies: apt-get install horde3 Now make the site available: in ''/etc/apache2/sites-available'', find the site(s) that will get horde3 enabled. In the site definition files, include the following snippet: Alias /horde3 /usr/share/horde3 <Directory /usr/share/horde3> Options FollowSymLinks AllowOverride Limit deny from all allow from all 192.168 127.0.0 </Directory> <Files ~ "\.(inc|bak)$"> deny from all </Files> If you include the code in an SSL protected site, you can also add <Location /horde3> SSLCipherSuite HIGH:MEDIUM </Location> Restart your Apache webserver, and horde3 is operational. However, if you surf to ''<nowiki>http://your.web.server/horde3</nowiki>'' you read this: {| border="1" |Horde3 configuration disabled by default because the administration/install wizard gives the whole world too much access to the system. Read /usr/share/doc/horde3/README.Debian.gz on how to allow access. |} No worries, we'll get horde operational with the following steps. ==Database== Horde needs its own database to keep information. To create that database there are several scripts in ''/usr/share/doc/horde3/examples/scripts/''. We use MySQL, so we unpack the MySQL setup script: cd /usr/share/doc/horde3/examples/scripts/sql gunzip create.mysql.sql.gz This unpacks ''create.mysql.sql'', in which we need to change the password for the user ''horde'', in line 27-29. They reads -- IMPORTANT: Change this password. PASSWORD('horde') ); We change the default password ''horde'' to something stronger. We can now run the script by feeding it into the MySQL client: localhost:# '''mysql -u root -p < /usr/share/doc/horde3/examples/scripts/sql/create.mysql.sql.gz''' Enter password: localhost:# _ Now remove the ''create.mysql.sql.gz'' file, or change the password back to 'horde', or secure access to the file! We don't want anyone to read the horde database password. ==Configure== To use the web configuration wizard we need to do a couple of things in directory ''/etc/horde/horde3''. First, we need most files to be owned by root:www-data and have permissions 750. Next, create a backup ''conf.php'' file, named ''conf.bak.php'', and change the permissions on both ''conf*.php'' files to 777: chgrp -R www-data /etc/horde/horde3/ chmod -R 750 /etc/horde/horde3 touch etc/horde/horde3/conf.bak.php chmod 777 /etc/horde/horde3/conf*.php Next, we can prepare an alternative location for the log file, in line with our [[Debian_Lenny_base_server|Lenny base server configuration]]: mkdir /var/appsloghorde touch /var/appsloghorde/horde3.log chown root.www-data /var/log/horde/horde3.log chmod 770 /var/log/horde/horde3.log Now edit ''/etc/horde/horde3/conf.php'' and remove line 2 and 3. We should now be able to browse to the Horde3 admin page, something like: http://server.local.lan/horde3/ ==Web configuration== Choose setup from the menu 'horde setup'. Note: fill at LEAST all the data mentioned hereunder, and only THEN click "Generate Horde Configuration". You '''cannot''' click that button in the mean time to "save your progress", because it will then shut you out of your Horde setup. * edit the data in tab "database" ** username: <nowiki>$conf[sql][username]</nowiki> = ''horde'' ** password: put after <nowiki>$conf[sql][password]</nowiki> the strong password we put in ''create.mysql.sql.gz'' ** connect to database: select <nowiki>$conf[sql][protocol]</nowiki> = ''tcp/ip'' ** where is that database located: <nowiki>$conf[sql][hostspec]</nowiki> = ''localhost'' ** The database name: <nowiki>$conf[sql][database]</nowiki> = ''horde'' * edit the data in tab "preference system ** set the preferences driver <nowiki>$conf[prefs][driver]</nowiki> to ''SQL database'' * edit the data in tab "authentication" - this section depends heavily on how you want to authenticate. Suppose you have an OpenLDAP server on your network, perhaps even on this same server, then it could be something like this: ** <nowiki>$conf[auth][admins]</nowiki> should have your own LDAP login, e.g. "john" ** <nowiki>$conf[auth][driver]</nowiki> must be ''LDAP authentication'' ** <nowiki>$conf[auth][params][hostspec]</nowiki> must be the LDAP server, e.g. "localhost" ** <nowiki>$conf[auth][params][basedn]</nowiki> will be the standard base DN, e.g. "dc=saruman,dc=biz" ** <nowiki>$conf[auth][params][binddn]</nowiki> must be the account that is allowed to bind, so it can check users; we use "cn=authenticator,dc=saruman,dc=biz" ** <nowiki>$conf[auth][params][password]</nowiki> contains the password of the binddn, in our case "authenticator"s password ("letmein", I believe it was :-) ** <nowiki>$conf[auth][params][uid]</nowiki> contains the attribute that contains the login name. This will often be "uid", as it is with us ** <nowiki>$conf[auth][params][objectclass]</nowiki> must contain an object class filter, with which horde can limit the results of its search. If all your horde users are in one single class, you can simply use that. E.g. we have all users member of "inetOrgPerson" so we can use that value. More settings can be made, but that can also be done at a later time. For now, click "Generate Horde Configuration". You will be thrown out, and must log back in with the specified admin account (LDAP account "john" in our example). When ''horde3'' is installed, you can start installing Horde applications. The central part of this is [[IMP - the Internet Mail Program]] f5f1b256db2080e8a9ed0a2f765dec9376ea2038 2459 2458 2009-08-31T18:57:21Z Saruman! 2 changed link wikitext text/x-wiki A standard howto for the Horde3 installation can be found at [http://wiki.debian.org/Horde wiki.debian.org]. Our notes on Horde3 installation are the following: ==Installation== First make sure you have a nice little [[LAMP]] server running, with [[Database_101|MySQL]], [[Apache2_and_PHP5|Apache2, PHP5]] et cetera. Now install the base package plus dependencies: apt-get install horde3 Now make the site available: in ''/etc/apache2/sites-available'', find the site(s) that will get horde3 enabled. In the site definition files, include the following snippet: Alias /horde3 /usr/share/horde3 <Directory /usr/share/horde3> Options FollowSymLinks AllowOverride Limit deny from all allow from all 192.168 127.0.0 </Directory> <Files ~ "\.(inc|bak)$"> deny from all </Files> If you include the code in an SSL protected site, you can also add <Location /horde3> SSLCipherSuite HIGH:MEDIUM </Location> Restart your Apache webserver, and horde3 is operational. However, if you surf to ''<nowiki>http://your.web.server/horde3</nowiki>'' you read this: {| border="1" |Horde3 configuration disabled by default because the administration/install wizard gives the whole world too much access to the system. Read /usr/share/doc/horde3/README.Debian.gz on how to allow access. |} No worries, we'll get horde operational with the following steps. ==Database== Horde needs its own database to keep information. To create that database there are several scripts in ''/usr/share/doc/horde3/examples/scripts/''. We use MySQL, so we unpack the MySQL setup script: cd /usr/share/doc/horde3/examples/scripts/sql gunzip create.mysql.sql.gz This unpacks ''create.mysql.sql'', in which we need to change the password for the user ''horde'', in line 27-29. They reads -- IMPORTANT: Change this password. PASSWORD('horde') ); We change the default password ''horde'' to something stronger. We can now run the script by feeding it into the MySQL client: localhost:# '''mysql -u root -p < /usr/share/doc/horde3/examples/scripts/sql/create.mysql.sql.gz''' Enter password: localhost:# _ Now remove the ''create.mysql.sql.gz'' file, or change the password back to 'horde', or secure access to the file! We don't want anyone to read the horde database password. ==Configure== To use the web configuration wizard we need to do a couple of things in directory ''/etc/horde/horde3''. First, we need most files to be owned by root:www-data and have permissions 750. Next, create a backup ''conf.php'' file, named ''conf.bak.php'', and change the permissions on both ''conf*.php'' files to 777: chgrp -R www-data /etc/horde/horde3/ chmod -R 750 /etc/horde/horde3 touch etc/horde/horde3/conf.bak.php chmod 777 /etc/horde/horde3/conf*.php Next, we can prepare an alternative location for the log file, in line with our [[Debian_Lenny_base_server|Lenny base server configuration]]: mkdir /var/appsloghorde touch /var/appsloghorde/horde3.log chown root.www-data /var/log/horde/horde3.log chmod 770 /var/log/horde/horde3.log Now edit ''/etc/horde/horde3/conf.php'' and remove line 2 and 3. We should now be able to browse to the Horde3 admin page, something like: http://server.local.lan/horde3/ ==Web configuration== Choose setup from the menu 'horde setup'. Note: fill at LEAST all the data mentioned hereunder, and only THEN click "Generate Horde Configuration". You '''cannot''' click that button in the mean time to "save your progress", because it will then shut you out of your Horde setup. * edit the data in tab "database" ** username: <nowiki>$conf[sql][username]</nowiki> = ''horde'' ** password: put after <nowiki>$conf[sql][password]</nowiki> the strong password we put in ''create.mysql.sql.gz'' ** connect to database: select <nowiki>$conf[sql][protocol]</nowiki> = ''tcp/ip'' ** where is that database located: <nowiki>$conf[sql][hostspec]</nowiki> = ''localhost'' ** The database name: <nowiki>$conf[sql][database]</nowiki> = ''horde'' * edit the data in tab "preference system ** set the preferences driver <nowiki>$conf[prefs][driver]</nowiki> to ''SQL database'' * edit the data in tab "authentication" - this section depends heavily on how you want to authenticate. Suppose you have an OpenLDAP server on your network, perhaps even on this same server, then it could be something like this: ** <nowiki>$conf[auth][admins]</nowiki> should have your own LDAP login, e.g. "john" ** <nowiki>$conf[auth][driver]</nowiki> must be ''LDAP authentication'' ** <nowiki>$conf[auth][params][hostspec]</nowiki> must be the LDAP server, e.g. "localhost" ** <nowiki>$conf[auth][params][basedn]</nowiki> will be the standard base DN, e.g. "dc=saruman,dc=biz" ** <nowiki>$conf[auth][params][binddn]</nowiki> must be the account that is allowed to bind, so it can check users; we use "cn=authenticator,dc=saruman,dc=biz" ** <nowiki>$conf[auth][params][password]</nowiki> contains the password of the binddn, in our case "authenticator"s password ("letmein", I believe it was :-) ** <nowiki>$conf[auth][params][uid]</nowiki> contains the attribute that contains the login name. This will often be "uid", as it is with us ** <nowiki>$conf[auth][params][objectclass]</nowiki> must contain an object class filter, with which horde can limit the results of its search. If all your horde users are in one single class, you can simply use that. E.g. we have all users member of "inetOrgPerson" so we can use that value. More settings can be made, but that can also be done at a later time. For now, click "Generate Horde Configuration". You will be thrown out, and must log back in with the specified admin account (LDAP account "john" in our example). When ''horde3'' is installed, you can start installing Horde applications. The central part of this is [[IMP - the Internet Messaging Program]] 06cd6a7860cd657bcbc961c096460c49889a3533 0 1592 2460 2009-08-31T19:03:32Z Saruman! 2 page started wikitext text/x-wiki == IMP == With Debian Lenny come standard, stable applications. The [http://www.horde.org/imp/ IMP webmail application] that is packaged for Debian is version 4.2. The quickest way to install IMP is apt-get install imp4 With both ''horde3'' and a mailserver (e.g. [[E-mail_server_section|Postfix]]) completely installed and configured, no extra packages will get installed. Before you configure IMP, you need to prepare file permissions for web configuration (this is a recurring theme for any horde3 application): touch /etc/horde/imp4/conf.bak.php chmod 777 /etc/horde/imp4/conf*.php Now you can log in to horde3 web interface as a user with administrative rights. In the Horde3 tree, choose setup from the menu 'mail(imp)' Generate your configuration (GPG/PGP, user constraints, enable spam/ham report, hooks...). And when you're done change the permissions back chmod 644 /etc/horde/imp4/conf.php chmod 700 /etc/horde/imp4/conf.bak.php And specify your mail server(s) in /etc/horde/imp4/servers.php file $servers['imap'] = array( 'name' => 'IMAP Server', 'server' => 'localhost', 'hordeauth' => 'full', 'protocol' => 'imap/notls', 'port' => 143, 'maildomain' => 'sample.com', 'smtphost' => 'localhost', 'smtpport' => 25, 'realm' => 'sample.com', 'preferred' => '', ); When you are ready, enable IMP in /etc/horde/horde3/registry.php file and verify if all is right. Yes, you read well, you MUST enable manually module in registry.php file after configuration! $this->applications['imp'] = array( 'fileroot' => '/usr/share/horde3/lib' . '/../imp', 'webroot' => $this->applications['horde']['webroot'] . '/imp', 'name' => _("Mail"), 'status' => 'active', 'provides' => array('mail', 'contacts/favouriteRecipients') ); Change the status from inactive to active cd91ea57fdf8d22d5a27578d3a7a855e9cb3f4c9 2462 2460 2009-08-31T19:26:53Z Saruman! 2 first description of mail configuration wikitext text/x-wiki == IMP == With Debian Lenny come standard, stable applications. The [http://www.horde.org/imp/ IMP webmail application] that is packaged for Debian is version 4.2. The quickest way to install IMP is apt-get install imp4 With both ''horde3'' and a mailserver (e.g. [[E-mail_server_section|Postfix]]) completely installed and configured, no extra packages will get installed. Before you configure IMP, you need to prepare file permissions for web configuration (this is a recurring theme for any horde3 application): touch /etc/horde/imp4/conf.bak.php chmod 777 /etc/horde/imp4/conf*.php [[Image:Horde3-imp-setup-1.PNG|thumb|300px|Horde IPM4 configuration screen 1]]Now you can log in to horde3 web interface as a user with administrative rights. In the Horde3 tree view, choose Administration -> Setup -> '' Mail (imp) H3 (4.2)''' (see picture). This results in a configuration generation screen with something like 8 tabs; you could safely go with the defaults, but for lots of interesting special features you'll have to actively make a selection. Funny enough you do NOT select your mailserver(s) in this menu; that's left to manually editing another file (see further down). Now generate your configuration. When you're done, you can change the permissions back for safety: chmod 644 /etc/horde/imp4/conf.php chmod 600 /etc/horde/imp4/conf.bak.php Note that this also prevents you from changing the configuration with the web interface in the future. When you want to do that, you'll have to reset the permissions for the ''conf*.php'' files to 777, generate a new configuration, and then set the permissions back. Note that if you DO NOT change the permissions to 644/600, then your IMP client will still run flawlessly. However, you now run a serious risk of a malicious web client altering your web mail configuration. Time to specify your mail server(s) in ''/etc/horde/imp4/servers.php'' file. Depending on your mail server setup, your settings can be something like $servers['imap'] = array( 'name' => 'IMAP Server', 'server' => 'localhost', 'hordeauth' => 'full', 'protocol' => 'imap/notls', 'port' => 143, 'maildomain' => 'saruman.biz', 'smtphost' => 'localhost', 'smtpport' => 25, 'realm' => 'sample.com', 'preferred' => '', ); When you are ready, enable IMP in the file ''/etc/horde/horde3/registry.php'' and verify if all is right. Yes, you read well, you MUST enable manually module in registry.php file after configuration! $this->applications['imp'] = array( 'fileroot' => '/usr/share/horde3/lib' . '/../imp', 'webroot' => $this->applications['horde']['webroot'] . '/imp', 'name' => _("Mail"), 'status' => 'active', 'provides' => array('mail', 'contacts/favouriteRecipients') ); Change the status from inactive to active 2093663d97ce24cbd2b0ca6a7238e43e117e56fb 6 1593 2461 2009-08-31T19:06:45Z Saruman! 2 Admin user's Administration screen after installation of IMP4, but before configuration wikitext text/x-wiki Admin user's Administration screen after installation of IMP4, but before configuration b0ebe42129ff2b904f7b721d7ef740fc0f2a01d5 0 1476 2464 2393 2009-10-10T16:36:09Z Saruman! 2 /* Digium Zaptel driver for your custom kernel */ updated wikitext text/x-wiki =Zaptel driver= ==Prerequisites== To compile the Zaptel driver, we first install support for certain functions (a.o. deflate compression method): sudo apt-get install zlib1g-dev libssl-dev bison debhelper Specifically the last one (''debhelper'') can bring a whole slew of extra packages with it, a.o. ''build-essential'', ''po-debconf'', ''liburi-perl'' and ''patch'', just to name a few. ==Debian version of Zaptel== Next up is to get the zaptel source code, as is delivered with Debian Lenny. Note, however, that as of march 2009, this driver has a little bug in the ''ztdummy'' driver that prevents the driver to compile under a 2.6.28 kernel. If you have a custom kernel (i.e. not the Debian stock kernel) then skip down to the ''next'' section! For plain Debian Lenny: sudo apt-get install zaptel-source If there are any dependencies not yet satisfied, you'll see those packages come with the source code (e.g. ''module-assistant''). Once the Zaptel source code is on our system, it is up to us to create the driver. Debian can't handle this for us, as the Zaptel driver has to precisely match both our hardware platform and the Linux kernel we're using. So we're going to compile our own driver - yippee!<br> Debian has placed the source file package in ''/usr/src'', and it's named ''zaptel.tar.bz2''. Normally you would think about unpacking it with ''sudo tar xjvf'' and get going with the code that's in it. HOWEVER Debian has a really cool utility called the ''module-assistant''. This program is the command-line tool for handling module-source packages that have been prepared for the Debian distribution. It helps users to build and install module packages easily for one or more kernels, even custom ones. We start from the beginning: * boot your system under the kernel for which you want to create the Zaptel drivers, if you haven't already done so * as root, run ''module-assistant prepare''. This checks the availability of your kernel source header files, creates a symlink ''/usr/src/linux'' that points to your kernel source files, and checks if you have all Debian packages you're going to need (e.g. ''build-essentials''). * Then, again as root, run ''module-assistant auto-install zaptel'' (or abbreviate it to ''m-a a-i zaptel''). After a while (may be multiple minutes) the command completes.The output hopefully ends with something like "Setting up zaptel-modules-2.6.27.5 (1:1.4.11~dfsg-2) ..." - note: the number before the parenthesis should match the kernel version for which you're compiling the module - in this case we're running kernel 2.6.27.5, and the Zaptel module we've compiled is for this specific kernel. * Some howto's now instruct you to run ''update-modules'', but with modern Debian distributions like 4.0 "Etch" or 5.0 "Lenny" this is not the case; running it won't harm you, because there's a pseudo-command installed, but it won't do a single thing either... * If you have hardware installed, you now run ''genzaptelconf -svdM''. It will stop any Asterisk you might have running, be verbose, detect any modules on your hardware, update ''/etc/modules'', and finally create your hardware config file ''/etc/zaptel.conf''; it probably will give you a nice error message too about not being able to write in the ''/etc/asterisk'' directory - that's simply because we haven't installed asterisk itself yet! Note: if you live outside the U.S.A., you might want to specify which country you live in, to get the correct dialing tones etcetera. It is as simple as specifying your country (two-letter code): ''genzaptelconf -svdM -c nl''. The output is pretty clear in what the command finds, and what it does with that information. * You may want to now edit the configuration file that's created for the channels. The configuration file should be ''/etc/zaptel.conf'', and its contents could look like the file given below. However, you rarely need to edit this file by hand: ''genzaptelconf'' can handle this bit usually better than we can. # Span 1: WCTDM/0 "Wildcard TDM410P Board 1" (MASTER) fxols=1 fxols=2 fxsks=3 # channel 4, WCTDM/0/3, no module. # Global data loadzone = us defaultzone = us * If you wish, you can create directory ''/etc/asterisk'', and run the ''genzaptelconf'' again; that way you can see the ''zapata-channels.conf'' file that is created as well. * If you now reboot (into the same kernel), then the ''dmesg'' command should confirm the presence of your Zaptel drivers with a short section like this: Zapata Telephony Interface Registered on major 196 Zaptel Version: 1.4.11 Zaptel Echo Canceller: MG2 Furthermore, you can find lines like these, if you have hardware installed: ACPI: PCI Interrupt 0000:03:07.0[A] -> GSI 21 (level, low) -> IRQ 21 Port 1: Installed -- AUTO FXS/DPO Port 2: Installed -- AUTO FXS/DPO Port 3: Installed -- AUTO FXO (FCC mode) Port 4: Not installed VPM100: Not Present Found a Wildcard TDM: Wildcard TDM410P (4 modules) ==Digium Zaptel driver for your custom kernel== In March 2009 I decided to upgrade my custom-configured vanilla kernel from 2.6.27.5 to 2.6.28.9. After that, I found I couldn't compile the Debian Zaptel driver, because of an error in the compilation of ''ztdummy''. The error looked something like this: CC [M] /usr/src/modules/zaptel/kernel/ztdummy.o /usr/src/modules/zaptel/kernel/ztdummy.c: In function 'ztdummy_hr_int': /usr/src/modules/zaptel/kernel/ztdummy.c:203: error: 'struct hrtimer' has no member named 'expires' make[4]: *** [/usr/src/modules/zaptel/kernel/ztdummy.o] Error 1 make[3]: *** [_module_/usr/src/modules/zaptel/kernel] Error 2 make[3]: Leaving directory `/usr/src/linux-2.6.28' make[2]: *** [modules] Error 2 make[2]: Leaving directory `/usr/src/modules/zaptel' make[1]: *** [binary-modules] Error 2 make[1]: Leaving directory `/usr/src/modules/zaptel' make: *** [kdist_build] Error 2 The solution to this was either to: * go back to a 2.6.27 kernel (I didn't want to), * get my hands on an updated Debian Zaptel package that was not released yet (''zaptel 1:1.4.11~dfsg-4'') (couldn't get it), * find a way to patch the Debian Zaptel source code (couldn't figure out how), * or use the latest Digium Zaptel driver from [http://downloads.digium.com/pub/zaptel/ their website]. It turned out that even the latest Zaptel driver from Digium (version 1.4.12.1) couldn't compile because of this error. But after a while I found this solution: I downloaded the latest ''SVN snapshot'' from the Digium website (release r4636), instead of the tarball with the latest stable release (revision r4504), and manually compiled and installed that. The way to do that is (with only a little explanation): # Get Subversion, and make sure we have three necessary packages apt-get install subversion apt-get install build-essential libnewt-dev libusb-dev # Go to /usr/src and get the 1.4 branch for Zaptel from Digium, in # the right revision cd /usr/src svn co --revision 4690 <nowiki>http://svn.digium.com/svn/zaptel/branches/1.4</nowiki> mv 1.4 zaptel # go in the source directory, and compile cd zaptel ./install_prereq test ./install_prereq install ./configure make make install # Make a configuration (only if it doesn't exist already!) make config # Now load the drivers modprobe zaptel modprobe wctdm24xxp # Of course the last driver is specific to my TDM410p # Check if it worked ztcfg -vvv =Zaptel tools= Next up, if you haven't yet done so during the preceding step, you now need to install the ''zaptel'' userland tools (v1.4.11 under Debian 5.0), which will in turn require ''fxload'' and ''libtonezone1''. Installation is simply performed by sudo apt-get install zaptel fxload libtonezone1 After installation, the ''zaptel'' driver checks for the existance of ''/etc/zaptel.conf''. When you've never before had Zaptel on your system, or haven't finished configuration in the preceding step, then you probably get the message zaptel : /etc/zaptel.conf fails test for exists and readable This is in fact a friendly reminder that you first have to create this file, before you try to load the driver. =libpri installation= Asterisk needs the ''libpri'' package; not only to handle ISDN-cards, but also for some other functions (although currently I don't know which ones :-). Before installing Asterisk, you could start by installing this package. In Debian 5.0 "Lenny", the packages is named ''libpri1.0'': apt-get install libpri1.0 d0a90f5f85b04c0efd6a6487230f91132af843a5 2478 2464 2009-12-31T06:59:41Z Saruman! 2 /* Digium Zaptel driver for your custom kernel */ updated for kernel 2.6.32.2 wikitext text/x-wiki =Zaptel driver= ==Prerequisites== To compile the Zaptel driver, we first install support for certain functions (a.o. deflate compression method): sudo apt-get install zlib1g-dev libssl-dev bison debhelper Specifically the last one (''debhelper'') can bring a whole slew of extra packages with it, a.o. ''build-essential'', ''po-debconf'', ''liburi-perl'' and ''patch'', just to name a few. ==Debian version of Zaptel== Next up is to get the zaptel source code, as is delivered with Debian Lenny. Note, however, that as of march 2009, this driver has a little bug in the ''ztdummy'' driver that prevents the driver to compile under a 2.6.28 kernel. If you have a custom kernel (i.e. not the Debian stock kernel) then skip down to the ''next'' section! For plain Debian Lenny: sudo apt-get install zaptel-source If there are any dependencies not yet satisfied, you'll see those packages come with the source code (e.g. ''module-assistant''). Once the Zaptel source code is on our system, it is up to us to create the driver. Debian can't handle this for us, as the Zaptel driver has to precisely match both our hardware platform and the Linux kernel we're using. So we're going to compile our own driver - yippee!<br> Debian has placed the source file package in ''/usr/src'', and it's named ''zaptel.tar.bz2''. Normally you would think about unpacking it with ''sudo tar xjvf'' and get going with the code that's in it. HOWEVER Debian has a really cool utility called the ''module-assistant''. This program is the command-line tool for handling module-source packages that have been prepared for the Debian distribution. It helps users to build and install module packages easily for one or more kernels, even custom ones. We start from the beginning: * boot your system under the kernel for which you want to create the Zaptel drivers, if you haven't already done so * as root, run ''module-assistant prepare''. This checks the availability of your kernel source header files, creates a symlink ''/usr/src/linux'' that points to your kernel source files, and checks if you have all Debian packages you're going to need (e.g. ''build-essentials''). * Then, again as root, run ''module-assistant auto-install zaptel'' (or abbreviate it to ''m-a a-i zaptel''). After a while (may be multiple minutes) the command completes.The output hopefully ends with something like "Setting up zaptel-modules-2.6.27.5 (1:1.4.11~dfsg-2) ..." - note: the number before the parenthesis should match the kernel version for which you're compiling the module - in this case we're running kernel 2.6.27.5, and the Zaptel module we've compiled is for this specific kernel. * Some howto's now instruct you to run ''update-modules'', but with modern Debian distributions like 4.0 "Etch" or 5.0 "Lenny" this is not the case; running it won't harm you, because there's a pseudo-command installed, but it won't do a single thing either... * If you have hardware installed, you now run ''genzaptelconf -svdM''. It will stop any Asterisk you might have running, be verbose, detect any modules on your hardware, update ''/etc/modules'', and finally create your hardware config file ''/etc/zaptel.conf''; it probably will give you a nice error message too about not being able to write in the ''/etc/asterisk'' directory - that's simply because we haven't installed asterisk itself yet! Note: if you live outside the U.S.A., you might want to specify which country you live in, to get the correct dialing tones etcetera. It is as simple as specifying your country (two-letter code): ''genzaptelconf -svdM -c nl''. The output is pretty clear in what the command finds, and what it does with that information. * You may want to now edit the configuration file that's created for the channels. The configuration file should be ''/etc/zaptel.conf'', and its contents could look like the file given below. However, you rarely need to edit this file by hand: ''genzaptelconf'' can handle this bit usually better than we can. # Span 1: WCTDM/0 "Wildcard TDM410P Board 1" (MASTER) fxols=1 fxols=2 fxsks=3 # channel 4, WCTDM/0/3, no module. # Global data loadzone = us defaultzone = us * If you wish, you can create directory ''/etc/asterisk'', and run the ''genzaptelconf'' again; that way you can see the ''zapata-channels.conf'' file that is created as well. * If you now reboot (into the same kernel), then the ''dmesg'' command should confirm the presence of your Zaptel drivers with a short section like this: Zapata Telephony Interface Registered on major 196 Zaptel Version: 1.4.11 Zaptel Echo Canceller: MG2 Furthermore, you can find lines like these, if you have hardware installed: ACPI: PCI Interrupt 0000:03:07.0[A] -> GSI 21 (level, low) -> IRQ 21 Port 1: Installed -- AUTO FXS/DPO Port 2: Installed -- AUTO FXS/DPO Port 3: Installed -- AUTO FXO (FCC mode) Port 4: Not installed VPM100: Not Present Found a Wildcard TDM: Wildcard TDM410P (4 modules) ==Digium Zaptel driver for your custom kernel== In March 2009 I decided to upgrade my custom-configured vanilla kernel from 2.6.27.5 to 2.6.28.9. After that, I found I couldn't compile the Debian Zaptel driver, because of an error in the compilation of ''ztdummy''. The error looked something like this: CC [M] /usr/src/modules/zaptel/kernel/ztdummy.o /usr/src/modules/zaptel/kernel/ztdummy.c: In function 'ztdummy_hr_int': /usr/src/modules/zaptel/kernel/ztdummy.c:203: error: 'struct hrtimer' has no member named 'expires' make[4]: *** [/usr/src/modules/zaptel/kernel/ztdummy.o] Error 1 make[3]: *** [_module_/usr/src/modules/zaptel/kernel] Error 2 make[3]: Leaving directory `/usr/src/linux-2.6.28' make[2]: *** [modules] Error 2 make[2]: Leaving directory `/usr/src/modules/zaptel' make[1]: *** [binary-modules] Error 2 make[1]: Leaving directory `/usr/src/modules/zaptel' make: *** [kdist_build] Error 2 The solution to this was either to: * go back to a 2.6.27 kernel (I didn't want to), * get my hands on an updated Debian Zaptel package that was not released yet (''zaptel 1:1.4.11~dfsg-4'') (couldn't get it), * find a way to patch the Debian Zaptel source code (couldn't figure out how), * or use the latest Digium Zaptel driver from [http://downloads.digium.com/pub/zaptel/ their website]. It turned out that even the latest Zaptel driver from Digium (version 1.4.12.1) couldn't compile because of this error. But after a while I found this solution: I downloaded the latest ''SVN snapshot'' from the Digium website (back then release r4636), instead of the tarball with the latest stable release (revision r4504), and manually compiled and installed that. The way to do that is (with only a little explanation): # Get Subversion, and make sure we have three necessary packages apt-get install subversion apt-get install build-essential libnewt-dev libusb-dev # Go to /usr/src and get the 1.4 branch for Zaptel from Digium, in # the right revision cd /usr/src svn co --revision 4692 <nowiki>http://svn.digium.com/svn/zaptel/branches/1.4</nowiki> mv 1.4 zaptel.r4692 # go in the source directory, and compile cd zaptel.r4692 ./install_prereq test ./install_prereq install ./configure make make install # Make a configuration (only if it doesn't exist already!) make config # Now load the drivers modprobe zaptel modprobe wctdm24xxp # Of course the last driver is specific to my TDM410p # Check if it worked ztcfg -vvv Furthermore, in december 2009 I switched to kernel 2.6.32.2, and for that I needed subversion release 4692. To find info on the latest Zaptel commits, look at the archives of the [http://lists.digium.com/pipermail/zaptel-commits/ zaptel-commits mailing list]. =Zaptel tools= Next up, if you haven't yet done so during the preceding step, you now need to install the ''zaptel'' userland tools (v1.4.11 under Debian 5.0), which will in turn require ''fxload'' and ''libtonezone1''. Installation is simply performed by sudo apt-get install zaptel fxload libtonezone1 After installation, the ''zaptel'' driver checks for the existance of ''/etc/zaptel.conf''. When you've never before had Zaptel on your system, or haven't finished configuration in the preceding step, then you probably get the message zaptel : /etc/zaptel.conf fails test for exists and readable This is in fact a friendly reminder that you first have to create this file, before you try to load the driver. =libpri installation= Asterisk needs the ''libpri'' package; not only to handle ISDN-cards, but also for some other functions (although currently I don't know which ones :-). Before installing Asterisk, you could start by installing this package. In Debian 5.0 "Lenny", the packages is named ''libpri1.0'': apt-get install libpri1.0 39e51241dcfeaf30ea35861897ff32db6c7a7584 2565 2478 2010-05-16T09:49:25Z Saruman! 2 /* Digium Zaptel driver for your custom kernel */ added2.6.33.4 note wikitext text/x-wiki =Zaptel driver= ==Prerequisites== To compile the Zaptel driver, we first install support for certain functions (a.o. deflate compression method): sudo apt-get install zlib1g-dev libssl-dev bison debhelper Specifically the last one (''debhelper'') can bring a whole slew of extra packages with it, a.o. ''build-essential'', ''po-debconf'', ''liburi-perl'' and ''patch'', just to name a few. ==Debian version of Zaptel== Next up is to get the zaptel source code, as is delivered with Debian Lenny. Note, however, that as of march 2009, this driver has a little bug in the ''ztdummy'' driver that prevents the driver to compile under a 2.6.28 kernel. If you have a custom kernel (i.e. not the Debian stock kernel) then skip down to the ''next'' section! For plain Debian Lenny: sudo apt-get install zaptel-source If there are any dependencies not yet satisfied, you'll see those packages come with the source code (e.g. ''module-assistant''). Once the Zaptel source code is on our system, it is up to us to create the driver. Debian can't handle this for us, as the Zaptel driver has to precisely match both our hardware platform and the Linux kernel we're using. So we're going to compile our own driver - yippee!<br> Debian has placed the source file package in ''/usr/src'', and it's named ''zaptel.tar.bz2''. Normally you would think about unpacking it with ''sudo tar xjvf'' and get going with the code that's in it. HOWEVER Debian has a really cool utility called the ''module-assistant''. This program is the command-line tool for handling module-source packages that have been prepared for the Debian distribution. It helps users to build and install module packages easily for one or more kernels, even custom ones. We start from the beginning: * boot your system under the kernel for which you want to create the Zaptel drivers, if you haven't already done so * as root, run ''module-assistant prepare''. This checks the availability of your kernel source header files, creates a symlink ''/usr/src/linux'' that points to your kernel source files, and checks if you have all Debian packages you're going to need (e.g. ''build-essentials''). * Then, again as root, run ''module-assistant auto-install zaptel'' (or abbreviate it to ''m-a a-i zaptel''). After a while (may be multiple minutes) the command completes.The output hopefully ends with something like "Setting up zaptel-modules-2.6.27.5 (1:1.4.11~dfsg-2) ..." - note: the number before the parenthesis should match the kernel version for which you're compiling the module - in this case we're running kernel 2.6.27.5, and the Zaptel module we've compiled is for this specific kernel. * Some howto's now instruct you to run ''update-modules'', but with modern Debian distributions like 4.0 "Etch" or 5.0 "Lenny" this is not the case; running it won't harm you, because there's a pseudo-command installed, but it won't do a single thing either... * If you have hardware installed, you now run ''genzaptelconf -svdM''. It will stop any Asterisk you might have running, be verbose, detect any modules on your hardware, update ''/etc/modules'', and finally create your hardware config file ''/etc/zaptel.conf''; it probably will give you a nice error message too about not being able to write in the ''/etc/asterisk'' directory - that's simply because we haven't installed asterisk itself yet! Note: if you live outside the U.S.A., you might want to specify which country you live in, to get the correct dialing tones etcetera. It is as simple as specifying your country (two-letter code): ''genzaptelconf -svdM -c nl''. The output is pretty clear in what the command finds, and what it does with that information. * You may want to now edit the configuration file that's created for the channels. The configuration file should be ''/etc/zaptel.conf'', and its contents could look like the file given below. However, you rarely need to edit this file by hand: ''genzaptelconf'' can handle this bit usually better than we can. # Span 1: WCTDM/0 "Wildcard TDM410P Board 1" (MASTER) fxols=1 fxols=2 fxsks=3 # channel 4, WCTDM/0/3, no module. # Global data loadzone = us defaultzone = us * If you wish, you can create directory ''/etc/asterisk'', and run the ''genzaptelconf'' again; that way you can see the ''zapata-channels.conf'' file that is created as well. * If you now reboot (into the same kernel), then the ''dmesg'' command should confirm the presence of your Zaptel drivers with a short section like this: Zapata Telephony Interface Registered on major 196 Zaptel Version: 1.4.11 Zaptel Echo Canceller: MG2 Furthermore, you can find lines like these, if you have hardware installed: ACPI: PCI Interrupt 0000:03:07.0[A] -> GSI 21 (level, low) -> IRQ 21 Port 1: Installed -- AUTO FXS/DPO Port 2: Installed -- AUTO FXS/DPO Port 3: Installed -- AUTO FXO (FCC mode) Port 4: Not installed VPM100: Not Present Found a Wildcard TDM: Wildcard TDM410P (4 modules) ==Digium Zaptel driver for your custom kernel== In March 2009 I decided to upgrade my custom-configured vanilla kernel from 2.6.27.5 to 2.6.28.9. After that, I found I couldn't compile the Debian Zaptel driver, because of an error in the compilation of ''ztdummy''. The error looked something like this: CC [M] /usr/src/modules/zaptel/kernel/ztdummy.o /usr/src/modules/zaptel/kernel/ztdummy.c: In function 'ztdummy_hr_int': /usr/src/modules/zaptel/kernel/ztdummy.c:203: error: 'struct hrtimer' has no member named 'expires' make[4]: *** [/usr/src/modules/zaptel/kernel/ztdummy.o] Error 1 make[3]: *** [_module_/usr/src/modules/zaptel/kernel] Error 2 make[3]: Leaving directory `/usr/src/linux-2.6.28' make[2]: *** [modules] Error 2 make[2]: Leaving directory `/usr/src/modules/zaptel' make[1]: *** [binary-modules] Error 2 make[1]: Leaving directory `/usr/src/modules/zaptel' make: *** [kdist_build] Error 2 The solution to this was either to: * go back to a 2.6.27 kernel (I didn't want to), * get my hands on an updated Debian Zaptel package that was not released yet (''zaptel 1:1.4.11~dfsg-4'') (couldn't get it), * find a way to patch the Debian Zaptel source code (couldn't figure out how), * or use the latest Digium Zaptel driver from [http://downloads.digium.com/pub/zaptel/ their website]. It turned out that even the latest Zaptel driver from Digium (version 1.4.12.1) couldn't compile because of this error. But after a while I found this solution: I downloaded the latest ''SVN snapshot'' from the Digium website (back then release r4636), instead of the tarball with the latest stable release (revision r4504), and manually compiled and installed that. The way to do that is (with only a little explanation): # Get Subversion, and make sure we have three necessary packages apt-get install subversion apt-get install build-essential libnewt-dev libusb-dev # Go to /usr/src and get the 1.4 branch for Zaptel from Digium, in # the right revision cd /usr/src svn co --revision 4692 <nowiki>http://svn.digium.com/svn/zaptel/branches/1.4</nowiki> mv 1.4 zaptel.r4692 # go in the source directory, and compile cd zaptel.r4692 ./install_prereq test ./install_prereq install ./configure make make install # Make a configuration (only if it doesn't exist already!) make config # Now load the drivers modprobe zaptel modprobe wctdm24xxp # Of course the last driver is specific to my TDM410p # Check if it worked ztcfg -vvv Furthermore, in december 2009 I switched to kernel 2.6.32.2, and for that I needed subversion release 4692. To find info on the latest Zaptel commits, look at the archives of the [http://lists.digium.com/pipermail/zaptel-commits/ zaptel-commits mailing list]. Another note: when compiling kernel 2.6.33.4, I found that this kernel moves a file to where the zaptel driver cannot find it. To solve this particular problem ("error: linux/autoconf.h: No such file or directory") you could do this: cp /usr/src/linux-2.6.33.4/include/generated/autoconf.h /usr/src/linux-2.6.33.4/include/linux =Zaptel tools= Next up, if you haven't yet done so during the preceding step, you now need to install the ''zaptel'' userland tools (v1.4.11 under Debian 5.0), which will in turn require ''fxload'' and ''libtonezone1''. Installation is simply performed by sudo apt-get install zaptel fxload libtonezone1 After installation, the ''zaptel'' driver checks for the existance of ''/etc/zaptel.conf''. When you've never before had Zaptel on your system, or haven't finished configuration in the preceding step, then you probably get the message zaptel : /etc/zaptel.conf fails test for exists and readable This is in fact a friendly reminder that you first have to create this file, before you try to load the driver. =libpri installation= Asterisk needs the ''libpri'' package; not only to handle ISDN-cards, but also for some other functions (although currently I don't know which ones :-). Before installing Asterisk, you could start by installing this package. In Debian 5.0 "Lenny", the packages is named ''libpri1.0'': apt-get install libpri1.0 61e3ded7a2d4331534862b1fb74535ebaff7a944 0 1507 2465 2436 2009-10-12T17:50:38Z Saruman! 2 /* Configuring WebDAV and LDAP for your SSL-enabled Virtual Host */ added test section wikitext text/x-wiki ==Apache2== ===Installation of Apache2=== Installation of Apache2 is quite simple: apt-get install apache2 This brings a slew of packages, a.o. ''apache2-mpm-worker'', ''apache2-utils'', ''libapr1'' et cetera. When you want a different worker (e.g. , you should use ''aptitude'' to select that different worker (prefork etc.). ===Configuration of Apache2=== Once Apache2 is in place, you might want to [[Enabling SSL for Apache2 | enable SSL]] for it. Furthermore, you have to realise that mail sent by your webserver, or any PHP program running under it (e.g. MediaWiki) will have the envelope sender address of www-data@<your.maildomain>. To make sure that your maildomain is actually a real mail domain (necessary for reverse lookup, which is something that real mail servers do), you have to take care to put the right mail domain in ''/etc/mailname'' (e.g. "saruman.biz"). Furthermore, at the top of your Postfix ''main.cf'' you might like to add myorigin = /etc/mailname If you now restart Postfix, outgoing mail from user ''www-data'' will have an envelope sender address of ''www-data@saruman.biz'' ==Installation of PHP5== Installing PHP5 is as easy as sudo apt-get install php5 php5-cli Note that if you had installed Apache2 module ''apache2-mpm-worker'', it will get replaced with ''apache2-mpm-prefork''. Furthermore, note that ''php5-cli'' is only needed if you want to run PHP commands at the prompt - but our guess is that you want it (e.g. to perform maintenance tasks for your [[Mediawiki_Installation|MediaWiki wikiserver]]. ==Adding WebDAV to your Apache2== ===Thoughts about WebDAV and your configuration=== Out of the box, your Debian Apache2 is prepared to start using WebDAV. All you need is to enable two modules: one for WebDAV itself, one for the authentication that you want to use. Since our server mainly uses LDAP, we'll describe WebDAV+LDAP here. Furthermore, because WebDAV allows editing files on your server, security is paramount (well, it always is, of course. What we mean is that it's even '''more''' important now). The Apache project recommends:<br> ''The use of HTTP Basic Authentication is not recommended. You should use at least HTTP Digest Authentication, which is provided by the mod_auth_digest module. Nearly all WebDAV clients support this authentication method. An alternative is Basic Authentication over an SSL enabled connection.''<br> Thus you should not using Basic Authentication (which is pretty simple to set up) unless you run it over SSL - so we do that as well. We choose the Virtual Host that defines our SSL-site, and extend it with WebDAV functionality. If this is not what you want, consider stepping your authentication up to Digest Authentication. ===Configuring WebDAV and LDAP for your SSL-enabled Virtual Host=== First, enable the WebDAV and authnz_ldap modules: a2enmod dav a2enmod dav_fs a2enmod authnz_ldap Do not restart Apache2 just yet, because we haven't configured either the WebDAV site or its authentication! Furthermore, a location for the DAV lock database must be specified in the global section of your Apache2 configuration file using the [http://httpd.apache.org/docs/2.2/mod/mod_dav_fs.html#davlockdb DavLockDB directive]. To this end, create a file under ''/etc/apache2/conf.d'' named ''webdav'' containing this single line: DavLockDB /var/run/apache2/DavLock This will act as the (global) lock database for WebDAV; we don't need to specify it in any other configuration file (like the Virtual Host configuration files). Of course, your server should have a directory ''/var/run/apache2'', and it must be writable for the user ''www-data'' under which Apache2 runs. Next, adapt the virtual host that may employ WebDAV and LDAP authentication. The virtual host file needs a section that enables WebDAV (using the directive ''Dav On''), and some directives on how to authorize users within this section. Suppose we want to enable WebDAV only for subdirectory ''webdav'' within virtual host ''<nowiki>http://www.saruman.biz/</nowiki>''. Then in the correspondig Virtual Host file (something like ''/etc/apache2/sites-available/000-saruman.biz'') we need to include the following section: <Location /webdav> Order Allow,Deny Allow from all Dav On These lines turn on WebDAV for the location ''/webdav''. This of course means that there should ''be'' a directory in your server's filesystem named ''webdav'' and located under the root of this virtual host, e.g. ''/var/www/saruman.biz/webdav'' AuthType Basic AuthBasicProvider ldap AuthzLDAPAuthoritative On This section sets up the authentication as HTTP Basic, with LDAP as the provider, and NOT allowing the authorization phase to fall back to other providers if LDAP cannot provide the required answer. If you want to use "require" statements from some other authorization provider, then you must set ''AuthzLDAPAuthoritative'' to "off". AuthName "Enter your Saruman.biz login" AuthLDAPURL "ldap://myserver.saruman.biz/ou=people,dc=saruman,dc=biz?mail" NONE AuthLDAPBindDN "cn=admin,dc=saruman,dc=biz" AuthLDAPBindPassword "mypassword" The ''AuthName'' directive "sets the name of the authorization realm". The string provided for the AuthName is what will appear in the password dialog provided by most browsers.<br> The ''AuthLDAPURL'' should point to your server, and the word behind the question mark should be the LDAP field that you want to use as login. We use ''mail'' so that we can log in with our mail address.<br> The ''AuthLDAPBindDN'' should be of a user with the right to view the passwords of the users that will be using the WebDAV server, and the ''AuthLDAPBindPassword'' should be that user's password.<br> require valid-user </Location> This last directive means that any user who has authenticated is granted access. Since only LDAP users can authenticate, this is just fine. Next up, you need to create folder ''webdav'' under the root of your Virtual Host. Do not forget to make that folder owned by ''www-data:www-data'' and readable/writable only by that user: cd /data/wwwroot/yoursite mkdir webdav chown www-data:www-data webdav chmod 660 webdav Now you can restart Apache2, see if it restarts ok, and then test your new WebDAV folder. ===Testing WebDAV=== To test WebDAV, you can most easily install the ''cadaver'' WebDAV client: apt-get install cadaver After that, you can start cadaver, and have it write a file in your WebDAV environment: localhost:/data/wwwroot/yoursite/webdav# '''cadaver https://www.saruman.biz/webdav''' WARNING: Untrusted server certificate presented for `*.saruman.biz': Issued to: Internet Dept., Saruman.biz, Utrecht, NL Issued by: Saruman.biz, Utrecht, NL Certificate is valid from Tue, 28 Oct 2008 07:34:41 GMT to Mon, 02 Nov 2009 07:34:41 GMT Do you wish to accept the certificate? (y/n) y Authentication required for Enter your Saruman.biz login on server `www.saruman.biz': Username: sixpacjo Password: dav:/webdav/> _ When presented with the cadaver prompt, you can use the following commands: * ''edit <filename>'': this causes cadaver to open an existing file named ''<filename>''; or, failing that, to create a new file. Your default text editor is used. * ''lock <filename>'' or ''unlock <filename>'': set or remove a lock on a WebDAV published file. He who owns the lock can edit the file, others can only read it. * ''discover <filename>'': see the lock status of the file * ''quit'': well that one's easy... Use ''man cadaver'' for the full description. Errors that might occur if you have a problem in your WebDAV setup include: * Lock problems: if you fail to provide a webserver-writable place for the lock file, you will encounter HTTP 500 errors. In ''cadaver'': dav:/webdav/> edit test.html Locking `test.html': failed: 500 Internal Server Error dav:/webdav/> discover test.html Discovering locks on `test.html': no locks found. dav:/webdav/> d4af14c06e15f5ded7f1112b69943094dddfe7bf 2473 2465 2009-12-29T06:08:46Z Saruman! 2 added link to Visitor wikitext text/x-wiki ==Apache2== ===Installation of Apache2=== Installation of Apache2 is quite simple: apt-get install apache2 This brings a slew of packages, a.o. ''apache2-mpm-worker'', ''apache2-utils'', ''libapr1'' et cetera. When you want a different worker (e.g. , you should use ''aptitude'' to select that different worker (prefork etc.). ===Configuration of Apache2=== Once Apache2 is in place, you might want to [[Enabling SSL for Apache2 | enable SSL]] for it. And if you want to keep track of any visitor to your website(s), you might want to install [[Apache2 and Visitor|Visitor]]. Furthermore, you have to realise that mail sent by your webserver, or any PHP program running under it (e.g. MediaWiki) will have the envelope sender address of www-data@<your.maildomain>. To make sure that your maildomain is actually a real mail domain (necessary for reverse lookup, which is something that real mail servers do), you have to take care to put the right mail domain in ''/etc/mailname'' (e.g. "saruman.biz"). Furthermore, at the top of your Postfix ''main.cf'' you might like to add myorigin = /etc/mailname If you now restart Postfix, outgoing mail from user ''www-data'' will have an envelope sender address of ''www-data@saruman.biz'' ==Installation of PHP5== Installing PHP5 is as easy as sudo apt-get install php5 php5-cli Note that if you had installed Apache2 module ''apache2-mpm-worker'', it will get replaced with ''apache2-mpm-prefork''. Furthermore, note that ''php5-cli'' is only needed if you want to run PHP commands at the prompt - but our guess is that you want it (e.g. to perform maintenance tasks for your [[Mediawiki_Installation|MediaWiki wikiserver]]. ==Adding WebDAV to your Apache2== ===Thoughts about WebDAV and your configuration=== Out of the box, your Debian Apache2 is prepared to start using WebDAV. All you need is to enable two modules: one for WebDAV itself, one for the authentication that you want to use. Since our server mainly uses LDAP, we'll describe WebDAV+LDAP here. Furthermore, because WebDAV allows editing files on your server, security is paramount (well, it always is, of course. What we mean is that it's even '''more''' important now). The Apache project recommends:<br> ''The use of HTTP Basic Authentication is not recommended. You should use at least HTTP Digest Authentication, which is provided by the mod_auth_digest module. Nearly all WebDAV clients support this authentication method. An alternative is Basic Authentication over an SSL enabled connection.''<br> Thus you should not using Basic Authentication (which is pretty simple to set up) unless you run it over SSL - so we do that as well. We choose the Virtual Host that defines our SSL-site, and extend it with WebDAV functionality. If this is not what you want, consider stepping your authentication up to Digest Authentication. ===Configuring WebDAV and LDAP for your SSL-enabled Virtual Host=== First, enable the WebDAV and authnz_ldap modules: a2enmod dav a2enmod dav_fs a2enmod authnz_ldap Do not restart Apache2 just yet, because we haven't configured either the WebDAV site or its authentication! Furthermore, a location for the DAV lock database must be specified in the global section of your Apache2 configuration file using the [http://httpd.apache.org/docs/2.2/mod/mod_dav_fs.html#davlockdb DavLockDB directive]. To this end, create a file under ''/etc/apache2/conf.d'' named ''webdav'' containing this single line: DavLockDB /var/run/apache2/DavLock This will act as the (global) lock database for WebDAV; we don't need to specify it in any other configuration file (like the Virtual Host configuration files). Of course, your server should have a directory ''/var/run/apache2'', and it must be writable for the user ''www-data'' under which Apache2 runs. Next, adapt the virtual host that may employ WebDAV and LDAP authentication. The virtual host file needs a section that enables WebDAV (using the directive ''Dav On''), and some directives on how to authorize users within this section. Suppose we want to enable WebDAV only for subdirectory ''webdav'' within virtual host ''<nowiki>http://www.saruman.biz/</nowiki>''. Then in the correspondig Virtual Host file (something like ''/etc/apache2/sites-available/000-saruman.biz'') we need to include the following section: <Location /webdav> Order Allow,Deny Allow from all Dav On These lines turn on WebDAV for the location ''/webdav''. This of course means that there should ''be'' a directory in your server's filesystem named ''webdav'' and located under the root of this virtual host, e.g. ''/var/www/saruman.biz/webdav'' AuthType Basic AuthBasicProvider ldap AuthzLDAPAuthoritative On This section sets up the authentication as HTTP Basic, with LDAP as the provider, and NOT allowing the authorization phase to fall back to other providers if LDAP cannot provide the required answer. If you want to use "require" statements from some other authorization provider, then you must set ''AuthzLDAPAuthoritative'' to "off". AuthName "Enter your Saruman.biz login" AuthLDAPURL "ldap://myserver.saruman.biz/ou=people,dc=saruman,dc=biz?mail" NONE AuthLDAPBindDN "cn=admin,dc=saruman,dc=biz" AuthLDAPBindPassword "mypassword" The ''AuthName'' directive "sets the name of the authorization realm". The string provided for the AuthName is what will appear in the password dialog provided by most browsers.<br> The ''AuthLDAPURL'' should point to your server, and the word behind the question mark should be the LDAP field that you want to use as login. We use ''mail'' so that we can log in with our mail address.<br> The ''AuthLDAPBindDN'' should be of a user with the right to view the passwords of the users that will be using the WebDAV server, and the ''AuthLDAPBindPassword'' should be that user's password.<br> require valid-user </Location> This last directive means that any user who has authenticated is granted access. Since only LDAP users can authenticate, this is just fine. Next up, you need to create folder ''webdav'' under the root of your Virtual Host. Do not forget to make that folder owned by ''www-data:www-data'' and readable/writable only by that user: cd /data/wwwroot/yoursite mkdir webdav chown www-data:www-data webdav chmod 660 webdav Now you can restart Apache2, see if it restarts ok, and then test your new WebDAV folder. ===Testing WebDAV=== To test WebDAV, you can most easily install the ''cadaver'' WebDAV client: apt-get install cadaver After that, you can start cadaver, and have it write a file in your WebDAV environment: localhost:/data/wwwroot/yoursite/webdav# '''cadaver https://www.saruman.biz/webdav''' WARNING: Untrusted server certificate presented for `*.saruman.biz': Issued to: Internet Dept., Saruman.biz, Utrecht, NL Issued by: Saruman.biz, Utrecht, NL Certificate is valid from Tue, 28 Oct 2008 07:34:41 GMT to Mon, 02 Nov 2009 07:34:41 GMT Do you wish to accept the certificate? (y/n) y Authentication required for Enter your Saruman.biz login on server `www.saruman.biz': Username: sixpacjo Password: dav:/webdav/> _ When presented with the cadaver prompt, you can use the following commands: * ''edit <filename>'': this causes cadaver to open an existing file named ''<filename>''; or, failing that, to create a new file. Your default text editor is used. * ''lock <filename>'' or ''unlock <filename>'': set or remove a lock on a WebDAV published file. He who owns the lock can edit the file, others can only read it. * ''discover <filename>'': see the lock status of the file * ''quit'': well that one's easy... Use ''man cadaver'' for the full description. Errors that might occur if you have a problem in your WebDAV setup include: * Lock problems: if you fail to provide a webserver-writable place for the lock file, you will encounter HTTP 500 errors. In ''cadaver'': dav:/webdav/> edit test.html Locking `test.html': failed: 500 Internal Server Error dav:/webdav/> discover test.html Discovering locks on `test.html': no locks found. dav:/webdav/> 26eb30ccb4dd08977d674560535ebff1945bc02b 0 1466 2466 2448 2009-10-16T10:46:30Z Saruman! 2 /* MYsql commands */ expanded wikitext text/x-wiki == MySQL installation == As with any package to be installed: use aptitude, update your APT, then make sure all your (other) software is up-to-date. Then find package ''mysql-server'' - under Debian 5.0 "Lenny" it'll be version 5.0.51a-something. Installing it will also automatically install some dependent packages, like mysql-common, mysql-client etcetera. So after downloading some 40MiB of files, MySQL is installed. The installation script under Debian Lenny asks you for a password for the MySQL root user. Think up a strong password for the MySQL root user; something like ''waYacUbaT2uW''. DON'T use this example password, [http://www.pctools.com/guides/password/ generate your own one!]. DO NOT use the password of the Linux ''root'' user. Should you consult [http://dev.mysql.com/doc/refman/5.0/en/unix-post-installation.html the official MySQL documentation], you might see mention of the ''mysql_install_db'' script - do not worry about that, since Debian has run it for you when it was setting up the database. The standard user accounts that have been created by the installation script are: * 'root'@'localhost' * 'root'@'<hostname>' * 'root'@'127.0.0.1' All three root accounts are secured with the same password, the one you specified when installing the package ''mysql-server''. ---- '''NOTE for Debian 4.0 "Etch"''' When you install MySQL under Etch, there are two root accounts with empty passwords, and two anonymous accounts. NOT safe! You'll want to rectify this in order to secure your MySQL server. Please take the following steps. Start the MySQL client from the command line: mysql -u root Then, from the mysql client prompt, set the password for the MySQL root users. They can be treated as two different accounts, but we don't recommend that. We thus give both accounts the same password: mysql> SET PASSWORD FOR 'root'@'localhost' = PASSWORD('waYacUbaT2uW'); mysql> SET PASSWORD FOR 'root'@'<hostname>' = PASSWORD('waYacUbaT2uW'); Furthermore, there are two anonymous accounts created. These also have no password, and get full permission on the ''test'' database, as well as on any database who's name begins with ''test_''. These accounts can be fitted with a password (like we did for root - just use two quotes with nothing in between them, instead of two quotes with ''root'' in between), or they can be removed - which we recommend. The (single) command for this is: <pre>mysql> DROP USER '';</pre> '''End of NOTE''' ---- To verify the installation you might want to take some of the following steps: * run ''mysqlshow -u root -p'', and see if that command outputs at least two databases (''information_schema'' and ''mysql''); * check out the settings of your MySQL server by running ''mysqladmin -u root -p variables'' (piping the output to ''less'' or a file, if necessary); * have a peek in ''/var/lib/mysql''; the database data files should be there; * check ''/var/log'' for two logfiles ''mysql.err'' and ''mysql.log''. ==Moving the MySQL databases== By default the location of your Debian MySQL databases is ''/var/lib/mysql/<database>''. However, sometimes you wish your databases to be in a different location. E.g. ''/data/mysql'', where ''/data'' is a mounted dedicated RAID array. Or perhaps even ''/data/mysql'' is its own array. Whatever the reason, to move ''all'' MySQL databases from ''/var/lib/mysql'' to another location, you can follow these steps: * Create the new directory, e.g. ''/data/mysql'' * Make this directory owned by user/group ''mysql'' cd /data mkdir mysql chown mysql:mysql mysql * Shut down the database server with one of the following commands: mysqladmin -u root -p shutdown invoke-rc.d mysql stop * Make a backup copy of ''/etc/mysql/my.cnf'', then edit this file. Find the section ''[mysqld]'' and change the line ''datadir = /var/lib/mysql'' to datadir = /data/mysql * As root, move (or better yet: copy) ''all'' of the content of ''/var/lib/mysql'' over to ''/data/mysql''. Make sure you don't accidentally change the ownership or permissions of the files and folders in the ''/var/lib/mysql'' folder. We expect each and every file and folder to be owned by ''mysql:mysql''. Copy command would be (as root): cp -p -r /var/lib/mysql/* /data/mysql * Check and doublecheck your ''my.cnf'' settings and your database file owners, attributes and size. After the next step, there ''may'' be no way back! * Start up your database server: invoke-rc.d mysql start * Check the working of your MySQL server: ** issue the following command to get status information (to see if MySQL is running after your start command): invoke-rc.d mysql status ** look under ''/var/log'' for the default MySQL log files ''mysql.log'' and ''mysql.err'' ** check your SysLog (standard: ''/var/log/syslog'') for MySQL error messages, since the default Debian configuration is to log MySQL errors there, rather than in the previously mentioned MySQL logfiles. == MySQL commands == The following are examples of the most common MySQL commands <pre><nowiki> SHOW DATABASES; USE <database>; SHOW TABLES; DESCRIBE <table>; SELECT <col1>,<col2>...<col_i> FROM <table> WHERE <column> = '<value>'; INSERT INTO <table> (<col1>,<col2>...<col_i>) VALUES (<val1>,<val2>...<val_i>); UPDATE <table> set <col1> = '<value1>' WHERE <column> = '<value>'; DELETE FROM <table> WHERE <column> = '<value>'; </nowiki></pre> e5d4fabfbe05bcd3468164c47eb8bbaf1cc6e5ff 2467 2466 2009-10-23T09:34:18Z Saruman! 2 /* MySQL commands */ wikitext text/x-wiki == MySQL installation == As with any package to be installed: use aptitude, update your APT, then make sure all your (other) software is up-to-date. Then find package ''mysql-server'' - under Debian 5.0 "Lenny" it'll be version 5.0.51a-something. Installing it will also automatically install some dependent packages, like mysql-common, mysql-client etcetera. So after downloading some 40MiB of files, MySQL is installed. The installation script under Debian Lenny asks you for a password for the MySQL root user. Think up a strong password for the MySQL root user; something like ''waYacUbaT2uW''. DON'T use this example password, [http://www.pctools.com/guides/password/ generate your own one!]. DO NOT use the password of the Linux ''root'' user. Should you consult [http://dev.mysql.com/doc/refman/5.0/en/unix-post-installation.html the official MySQL documentation], you might see mention of the ''mysql_install_db'' script - do not worry about that, since Debian has run it for you when it was setting up the database. The standard user accounts that have been created by the installation script are: * 'root'@'localhost' * 'root'@'<hostname>' * 'root'@'127.0.0.1' All three root accounts are secured with the same password, the one you specified when installing the package ''mysql-server''. ---- '''NOTE for Debian 4.0 "Etch"''' When you install MySQL under Etch, there are two root accounts with empty passwords, and two anonymous accounts. NOT safe! You'll want to rectify this in order to secure your MySQL server. Please take the following steps. Start the MySQL client from the command line: mysql -u root Then, from the mysql client prompt, set the password for the MySQL root users. They can be treated as two different accounts, but we don't recommend that. We thus give both accounts the same password: mysql> SET PASSWORD FOR 'root'@'localhost' = PASSWORD('waYacUbaT2uW'); mysql> SET PASSWORD FOR 'root'@'<hostname>' = PASSWORD('waYacUbaT2uW'); Furthermore, there are two anonymous accounts created. These also have no password, and get full permission on the ''test'' database, as well as on any database who's name begins with ''test_''. These accounts can be fitted with a password (like we did for root - just use two quotes with nothing in between them, instead of two quotes with ''root'' in between), or they can be removed - which we recommend. The (single) command for this is: <pre>mysql> DROP USER '';</pre> '''End of NOTE''' ---- To verify the installation you might want to take some of the following steps: * run ''mysqlshow -u root -p'', and see if that command outputs at least two databases (''information_schema'' and ''mysql''); * check out the settings of your MySQL server by running ''mysqladmin -u root -p variables'' (piping the output to ''less'' or a file, if necessary); * have a peek in ''/var/lib/mysql''; the database data files should be there; * check ''/var/log'' for two logfiles ''mysql.err'' and ''mysql.log''. ==Moving the MySQL databases== By default the location of your Debian MySQL databases is ''/var/lib/mysql/<database>''. However, sometimes you wish your databases to be in a different location. E.g. ''/data/mysql'', where ''/data'' is a mounted dedicated RAID array. Or perhaps even ''/data/mysql'' is its own array. Whatever the reason, to move ''all'' MySQL databases from ''/var/lib/mysql'' to another location, you can follow these steps: * Create the new directory, e.g. ''/data/mysql'' * Make this directory owned by user/group ''mysql'' cd /data mkdir mysql chown mysql:mysql mysql * Shut down the database server with one of the following commands: mysqladmin -u root -p shutdown invoke-rc.d mysql stop * Make a backup copy of ''/etc/mysql/my.cnf'', then edit this file. Find the section ''[mysqld]'' and change the line ''datadir = /var/lib/mysql'' to datadir = /data/mysql * As root, move (or better yet: copy) ''all'' of the content of ''/var/lib/mysql'' over to ''/data/mysql''. Make sure you don't accidentally change the ownership or permissions of the files and folders in the ''/var/lib/mysql'' folder. We expect each and every file and folder to be owned by ''mysql:mysql''. Copy command would be (as root): cp -p -r /var/lib/mysql/* /data/mysql * Check and doublecheck your ''my.cnf'' settings and your database file owners, attributes and size. After the next step, there ''may'' be no way back! * Start up your database server: invoke-rc.d mysql start * Check the working of your MySQL server: ** issue the following command to get status information (to see if MySQL is running after your start command): invoke-rc.d mysql status ** look under ''/var/log'' for the default MySQL log files ''mysql.log'' and ''mysql.err'' ** check your SysLog (standard: ''/var/log/syslog'') for MySQL error messages, since the default Debian configuration is to log MySQL errors there, rather than in the previously mentioned MySQL logfiles. == MySQL commands == The following are examples of the most common MySQL commands <pre><nowiki> SHOW DATABASES; USE <database>; SHOW TABLES; DESCRIBE <table>; SELECT <col1>,<col2>...<col_i> FROM <table> WHERE <column> = '<value>'; INSERT INTO <table> (<col1>,<col2>...<col_i>) VALUES (<val1>,<val2>...<val_i>); UPDATE <table> set <col1> = '<value1>' WHERE <column> = '<value>'; DELETE FROM <table> WHERE <column> = '<value>'; </nowiki></pre> Ofcourse there are more useful commands, see the MySQL website. ce854f749e9a3166258da1dbbe66cea465027d3c 2567 2467 2010-05-18T14:41:09Z JamilaCloud 16 wikitext text/x-wiki == MySQL installation == As with any package to be installed: use aptitude, update your APT, then make sure all your (other) software is up-to-date. Then find package ''mysql-server'' - under Debian 5.0 "Lenny" it'll be version 5.0.51a-something. Installing it will also automatically install some dependent packages, like mysql-common, mysql-client etcetera. So after downloading some 40MiB of files, MySQL is installed. The installation script under Debian Lenny asks you for a password for the MySQL root user. Think up a strong password for the MySQL root user; something like ''waYacUbaT2uW''. DON'T use this example password, [http://www.pctools.com/guides/password/ generate your own one!]. DO NOT use the password of the Linux ''root'' user. [http://www.writers.ph writing jobs] Should you consult [http://dev.mysql.com/doc/refman/5.0/en/unix-post-installation.html the official MySQL documentation], you might see mention of the ''mysql_install_db'' script - do not worry about that, since Debian has run it for you when it was setting up the database. The standard user accounts that have been created by the installation script are: * 'root'@'localhost' * 'root'@'<hostname>' * 'root'@'127.0.0.1' All three root accounts are secured with the same password, the one you specified when installing the package ''mysql-server''. ---- '''NOTE for Debian 4.0 "Etch"''' When you install MySQL under Etch, there are two root accounts with empty passwords, and two anonymous accounts. NOT safe! You'll want to rectify this in order to secure your MySQL server. Please take the following steps. Start the MySQL client from the command line: mysql -u root Then, from the mysql client prompt, set the password for the MySQL root users. They can be treated as two different accounts, but we don't recommend that. We thus give both accounts the same password: mysql> SET PASSWORD FOR 'root'@'localhost' = PASSWORD('waYacUbaT2uW'); mysql> SET PASSWORD FOR 'root'@'<hostname>' = PASSWORD('waYacUbaT2uW'); Furthermore, there are two anonymous accounts created. These also have no password, and get full permission on the ''test'' database, as well as on any database who's name begins with ''test_''. These accounts can be fitted with a password (like we did for root - just use two quotes with nothing in between them, instead of two quotes with ''root'' in between), or they can be removed - which we recommend. The (single) command for this is: <pre>mysql> DROP USER '';</pre> '''End of NOTE''' ---- To verify the installation you might want to take some of the following steps: * run ''mysqlshow -u root -p'', and see if that command outputs at least two databases (''information_schema'' and ''mysql''); * check out the settings of your MySQL server by running ''mysqladmin -u root -p variables'' (piping the output to ''less'' or a file, if necessary); * have a peek in ''/var/lib/mysql''; the database data files should be there; * check ''/var/log'' for two logfiles ''mysql.err'' and ''mysql.log''. ==Moving the MySQL databases== By default the location of your Debian MySQL databases is ''/var/lib/mysql/<database>''. However, sometimes you wish your databases to be in a different location. E.g. ''/data/mysql'', where ''/data'' is a mounted dedicated RAID array. Or perhaps even ''/data/mysql'' is its own array. Whatever the reason, to move ''all'' MySQL databases from ''/var/lib/mysql'' to another location, you can follow these steps: * Create the new directory, e.g. ''/data/mysql'' * Make this directory owned by user/group ''mysql'' cd /data mkdir mysql chown mysql:mysql mysql * Shut down the database server with one of the following commands: mysqladmin -u root -p shutdown invoke-rc.d mysql stop * Make a backup copy of ''/etc/mysql/my.cnf'', then edit this file. Find the section ''[mysqld]'' and change the line ''datadir = /var/lib/mysql'' to datadir = /data/mysql * As root, move (or better yet: copy) ''all'' of the content of ''/var/lib/mysql'' over to ''/data/mysql''. Make sure you don't accidentally change the ownership or permissions of the files and folders in the ''/var/lib/mysql'' folder. We expect each and every file and folder to be owned by ''mysql:mysql''. Copy command would be (as root): cp -p -r /var/lib/mysql/* /data/mysql * Check and doublecheck your ''my.cnf'' settings and your database file owners, attributes and size. After the next step, there ''may'' be no way back! * Start up your database server: invoke-rc.d mysql start * Check the working of your MySQL server: ** issue the following command to get status information (to see if MySQL is running after your start command): invoke-rc.d mysql status ** look under ''/var/log'' for the default MySQL log files ''mysql.log'' and ''mysql.err'' ** check your SysLog (standard: ''/var/log/syslog'') for MySQL error messages, since the default Debian configuration is to log MySQL errors there, rather than in the previously mentioned MySQL logfiles. == MySQL commands == The following are examples of the most common MySQL commands <pre><nowiki> SHOW DATABASES; USE <database>; SHOW TABLES; DESCRIBE <table>; SELECT <col1>,<col2>...<col_i> FROM <table> WHERE <column> = '<value>'; INSERT INTO <table> (<col1>,<col2>...<col_i>) VALUES (<val1>,<val2>...<val_i>); UPDATE <table> set <col1> = '<value1>' WHERE <column> = '<value>'; DELETE FROM <table> WHERE <column> = '<value>'; </nowiki></pre> Ofcourse there are more useful commands, see the MySQL website. 758d4da92517056415eb1d3f75e41596c0243686 2568 2567 2010-05-18T16:00:09Z Saruman! 2 Reverted edits by [[Special:Contributions/JamilaCloud|JamilaCloud]] ([[User talk:JamilaCloud|Talk]]) to last revision by [[User:Saruman!|Saruman!]] wikitext text/x-wiki == MySQL installation == As with any package to be installed: use aptitude, update your APT, then make sure all your (other) software is up-to-date. Then find package ''mysql-server'' - under Debian 5.0 "Lenny" it'll be version 5.0.51a-something. Installing it will also automatically install some dependent packages, like mysql-common, mysql-client etcetera. So after downloading some 40MiB of files, MySQL is installed. The installation script under Debian Lenny asks you for a password for the MySQL root user. Think up a strong password for the MySQL root user; something like ''waYacUbaT2uW''. DON'T use this example password, [http://www.pctools.com/guides/password/ generate your own one!]. DO NOT use the password of the Linux ''root'' user. Should you consult [http://dev.mysql.com/doc/refman/5.0/en/unix-post-installation.html the official MySQL documentation], you might see mention of the ''mysql_install_db'' script - do not worry about that, since Debian has run it for you when it was setting up the database. The standard user accounts that have been created by the installation script are: * 'root'@'localhost' * 'root'@'<hostname>' * 'root'@'127.0.0.1' All three root accounts are secured with the same password, the one you specified when installing the package ''mysql-server''. ---- '''NOTE for Debian 4.0 "Etch"''' When you install MySQL under Etch, there are two root accounts with empty passwords, and two anonymous accounts. NOT safe! You'll want to rectify this in order to secure your MySQL server. Please take the following steps. Start the MySQL client from the command line: mysql -u root Then, from the mysql client prompt, set the password for the MySQL root users. They can be treated as two different accounts, but we don't recommend that. We thus give both accounts the same password: mysql> SET PASSWORD FOR 'root'@'localhost' = PASSWORD('waYacUbaT2uW'); mysql> SET PASSWORD FOR 'root'@'<hostname>' = PASSWORD('waYacUbaT2uW'); Furthermore, there are two anonymous accounts created. These also have no password, and get full permission on the ''test'' database, as well as on any database who's name begins with ''test_''. These accounts can be fitted with a password (like we did for root - just use two quotes with nothing in between them, instead of two quotes with ''root'' in between), or they can be removed - which we recommend. The (single) command for this is: <pre>mysql> DROP USER '';</pre> '''End of NOTE''' ---- To verify the installation you might want to take some of the following steps: * run ''mysqlshow -u root -p'', and see if that command outputs at least two databases (''information_schema'' and ''mysql''); * check out the settings of your MySQL server by running ''mysqladmin -u root -p variables'' (piping the output to ''less'' or a file, if necessary); * have a peek in ''/var/lib/mysql''; the database data files should be there; * check ''/var/log'' for two logfiles ''mysql.err'' and ''mysql.log''. ==Moving the MySQL databases== By default the location of your Debian MySQL databases is ''/var/lib/mysql/<database>''. However, sometimes you wish your databases to be in a different location. E.g. ''/data/mysql'', where ''/data'' is a mounted dedicated RAID array. Or perhaps even ''/data/mysql'' is its own array. Whatever the reason, to move ''all'' MySQL databases from ''/var/lib/mysql'' to another location, you can follow these steps: * Create the new directory, e.g. ''/data/mysql'' * Make this directory owned by user/group ''mysql'' cd /data mkdir mysql chown mysql:mysql mysql * Shut down the database server with one of the following commands: mysqladmin -u root -p shutdown invoke-rc.d mysql stop * Make a backup copy of ''/etc/mysql/my.cnf'', then edit this file. Find the section ''[mysqld]'' and change the line ''datadir = /var/lib/mysql'' to datadir = /data/mysql * As root, move (or better yet: copy) ''all'' of the content of ''/var/lib/mysql'' over to ''/data/mysql''. Make sure you don't accidentally change the ownership or permissions of the files and folders in the ''/var/lib/mysql'' folder. We expect each and every file and folder to be owned by ''mysql:mysql''. Copy command would be (as root): cp -p -r /var/lib/mysql/* /data/mysql * Check and doublecheck your ''my.cnf'' settings and your database file owners, attributes and size. After the next step, there ''may'' be no way back! * Start up your database server: invoke-rc.d mysql start * Check the working of your MySQL server: ** issue the following command to get status information (to see if MySQL is running after your start command): invoke-rc.d mysql status ** look under ''/var/log'' for the default MySQL log files ''mysql.log'' and ''mysql.err'' ** check your SysLog (standard: ''/var/log/syslog'') for MySQL error messages, since the default Debian configuration is to log MySQL errors there, rather than in the previously mentioned MySQL logfiles. == MySQL commands == The following are examples of the most common MySQL commands <pre><nowiki> SHOW DATABASES; USE <database>; SHOW TABLES; DESCRIBE <table>; SELECT <col1>,<col2>...<col_i> FROM <table> WHERE <column> = '<value>'; INSERT INTO <table> (<col1>,<col2>...<col_i>) VALUES (<val1>,<val2>...<val_i>); UPDATE <table> set <col1> = '<value1>' WHERE <column> = '<value>'; DELETE FROM <table> WHERE <column> = '<value>'; </nowiki></pre> Ofcourse there are more useful commands, see the MySQL website. ce854f749e9a3166258da1dbbe66cea465027d3c 0 1436 2468 1507 2009-10-23T11:52:16Z Saruman! 2 updated with credits and version wikitext text/x-wiki ==PHP Source Code== <source lang="php"> <?php # to activate the extension, include it from your LocalSettings.php # with: include_once("extensions/websiteFrame/websiteFrame.php"); $wgExtensionFunctions[] = "wfwebsiteFrame"; // Credits $wgExtensionCredits['parserhook'][] = array( 'name' => 'websiteFrame', 'author' => array( 'unknown', 'Jan Schoonderbeek' ), 'version' => '0.1.0', 'url' => 'https://www.saruman.biz/wiki/index.php/The_websiteFrame_PHP_extension', 'description' => 'Allow inclusion of iFrames.', 'descriptionmsg' => 'websiteframe-desc', ); function wfwebsiteFrame() { global $wgParser; $wgParser->setHook( "websiteFrame", "websiteFrame" ); } # the callback function for converting the input text to HTML output function websiteFrame($input) { # set default arguments $allParams['height'] = 800; $allParams['width'] = 800; $allParams['scroll'] = "no"; $allParams['border'] = "0"; $allParams['name'] = "Page1"; $allParams['align'] = "middle"; $allParams['allowtransparency'] = "false"; # get input args $aParams = explode("\n", $input); foreach($aParams as $sParam) { $aParam = explode("=", $sParam, 2); if( count( $aParam ) < 2 ) continue; $sType = $aParam[0]; $sArg = $aParam[1]; switch ($sType) { case 'website': $sType = trim($sType); $sArg = trim($sArg); $allParams['website'] = $sArg; break; case 'height': $sType = trim($sType); $sArg = trim($sArg); $allParams['height'] = $sArg; break; case 'width': $sType = trim($sType); $sArg = trim($sArg); $allParams['width'] = $sArg; break; case 'scroll': $sType = trim($sType); $sArg = trim($sArg); $allParams['scroll'] = $sArg; break; case 'border': $sType = trim($sType); $sArg = trim($sArg); $allParams['border'] = $sArg; break; case 'name': $sType = trim($sType); $sArg = trim($sArg); $allParams['name'] = $sArg; break; case 'align': $sType = trim($sType); $sArg = trim($sArg); $allParams['align'] = $sArg; break; case 'allowtransparency': $sType = trim($sType); $sArg = trim($sArg); $allParams['allowtransparency'] = $sArg; break; } } $output = "<iframe src=\"".$allParams['website']."\" align=\"".$allParams['align']."\" name=\"".$allParams['name']."\" frameborder=\"".$allParams['border']."\" height=\"".$allParams['height']."\" scrolling=\"".$allParams['scroll']."\" width=\"".$allParams['width']."\" allowtransparency=\"".$allParams['allowtransparency']."\"></iframe>"; return $output; } ?> </source> '''Notes:''' * I DO NOT KNOW the original author(s). I'd love to include him/her/them in the credits (I did almost nothing to the code myself). If you are or know the author(s), please [[User:Saruman!|contact me]]! * it isn't hard to add support for another attribute; however, security can be an issue, especially when you allow anonymous editors to use this. 581f102bf8b563bf42fe652d9f47b1a0bdec1452 2 1410 2469 1999 2009-10-23T11:53:09Z Saruman! 2 added mail address wikitext text/x-wiki <big>'''Saruman!'''</big> I'm part of the [[Saruwiki:about | Administrators team]] of this site. As you can read under the team description, I work as a technical infrastructure consultant at a large IT company. As such, I help customers with Unix and Linux servers, identity management, security, virtualization, networks and documentation - although occasionally I have to work with Microsoft Windows networks as well. My qualifications are, amongst others, [http://www.lpi.org/ LPI] certifications ([http://www.lpi.org/en/lpi/english/certification/the_lpic_program LPIC1 and LPIC2] - LPIC 3 is too difficult for me, I fear). I give a small number of Linux/Unix classes and workshops to co-workers. Furthermore, I'm very interested in infrastructure architecture ("technical architecture"), and I'm working on the credentials needed to perform in that particular field. In my spare time (if any), I listen to progressive rock music (especially work by [http://www.the-company.com/ Fish]), organize my music in my oversized iTunes library, ride a hi-tech hybrid car, read sci-fi and fantasy (not nearly often enough, though :-(, and play a bit with my digital camera, a [http://www.canon-europe.com/For_Home/Product_Finder/Cameras/Digital_SLR/EOS_20th_Anniversary/2004-2007.asp Canon EOS350D]. I'm married and have one daughter. You can contact me by e-mail at "Saruman" -at- saruman dot biz. 838640b48c1af80a2d9f26afb650924d8f772b11 0 1434 2470 2445 2009-12-27T16:36:54Z Saruman! 2 added tricks section wikitext text/x-wiki ==Installation of MediaWiki== Here we have the [[Basic MediaWiki Installation|basic installation]] of [http://www.mediawiki.org/ MediaWiki] outlined for you. The default installation will create your wiki in subdirectory ''/mediawiki''. Should you wish to have another name, e.g. ''<nowiki>http://www.yourserver.com/wiki</nowiki>'', then you must make [[Change MediaWiki subpath|two changes]]. ==Extra configuration== After installation of MediaWiki, your Wiki is available on ''every'' Virtual Host you run - unless you follow the instructions to [[place MediaWiki inside a Virtual Host]]. An extra feature we added was support for iFrames by means of a little PHP script that we googled; the extension is called [[The websiteFrame PHP extension| websiteFrame.php]]. Furthermore, we [[wiki footer change |changed the Creative Commons picture]] in the footer from a remote one to a local one. For performance, the following tricks can be used (which we found on [http://mituzas.lt/2007/01/26/mediawiki-performance-tuning this site]): * <pre>apt-get install php-apc</pre> to install a PHP accelerator; * add ''$wgMainCacheType = CACHE_ACCEL;'' (instead of ''CACHE_NONE'') into ''LocalSettings.php'' to enable that installed APC PHP accelerator; * add ''$wgDisableCounters = true;'' into ''LocalSettings.php'' to disable the page counters. On the example site referenced, the cache reduced rendering of an (almost empty) main page from 217ms to 50ms; disabling the page view counter took off another 10ms. Should you wish to customize the look of your MediaWiki wiki, then you must [[MediaWiki skinning|edit the MediaWiki skins]]. ==Extensions== One of the nice things about using something as popular as MediaWiki is the availability of a great number of [http://www.mediawiki.org/wiki/Manual:Extensions extensions]. One of the first things to do, therefor, is to [[mediawiki-extensions under Debian| install the default Debian Mediawiki Extensions package]]. For user management, we added the extensions [[MediaWikiExtension_Password_Reset | Password Reset]] and [[MediaWiki_Extension_-_GroupPermissionsManager | Group Permissions Manager]]. A feature we needed to gain experience for another project was the [http://semantic-mediawiki.org/wiki/Semantic_MediaWiki Semantic MediaWiki (SMW)] extension; it also has a pretty [[Semantic MediaWiki under Debian | simple installation]]. ==Multiple Wiki's on a single server== Some people want to run multiple Wiki instances on one single server - especially so if that server runs multiple websites (the forementioned [[place MediaWiki inside a Virtual Host|Virtual Hosts]]). The answer to that is to [[Create a Wikifarm | create a Wikifarm]].<br> Note that we've set up a [http://www.mediawikifarm.nl/wiki/index.php/Main_Page separate site] for this problem - you're welcome there with any questions you might have on wikifarms on Debian. ==User Rights management== The MediaWiki documentation quite clearly documents [http://www.mediawiki.org/wiki/Manual:$wgGroupPermissions how to manage user rights], but here is a very quick recap: The following user rights are granted implicitly to non-logged-in users: // Implicit group for all visitors $wgGroupPermissions['*' ]['createaccount'] = true; // 1.5.0 $wgGroupPermissions['*' ]['read'] = true; // 1.5.0 $wgGroupPermissions['*' ]['edit'] = true; // 1.5.0 $wgGroupPermissions['*' ]['createpage'] = true; // 1.6.0 $wgGroupPermissions['*' ]['createtalk'] = true; // 1.6.0 So if you want to limit the rights of anonymous users, paste these lines into ''LocalSettings.php'' and change to false those rights that you want to take away. e.g. if you do not want anonymous users to edit pages, set the 'edit' permission to false. Setting 'read' to false requires users to log in before they can read your wiki (but they can still see the sidebar!) The following rights are implicitly granted to all logged-in users. // Implicit group for all logged-in accounts $wgGroupPermissions['user' ]['move'] = true; // 1.5.0 $wgGroupPermissions['user' ]['read'] = true; // 1.5.0 $wgGroupPermissions['user' ]['edit'] = true; // 1.5.0 $wgGroupPermissions['user' ]['createpage'] = true; // 1.6.0 $wgGroupPermissions['user' ]['createtalk'] = true; // 1.6.0 $wgGroupPermissions['user' ]['upload'] = true; // 1.5.0 $wgGroupPermissions['user' ]['reupload'] = true; // 1.6.0 $wgGroupPermissions['user' ]['reupload-shared'] = true; // 1.6.0 $wgGroupPermissions['user' ]['minoredit'] = true; // 1.6.0 $wgGroupPermissions['user' ]['purge'] = true; // 1.10.0 '''NOTE:''' you '''cannot''' let normal users keep a right like 'edit' and take it away for a special group that you create, like 'students'. You MUST grant the group 'user' the ''fewest'' rights that anyone should have, grant extra rights to other groups, and place the right users in these other groups. Examples: $wgGroupPermissions['student' ]['edit'] = false; // WILL NOT WORK The above will NOT "give everyone edit rights except for students". $wgGroupPermissions['*' ]['edit'] = false; // $wgGroupPermissions['user' ]['edit'] = false; // explicitly take away edit from all logged-in users $wgGroupPermissions['staff' ]['edit'] = true; // then give back edit to everyone except standard $wgGroupPermissions['visitingstaff' ]['edit'] = true; // users This WILL work: the edit right is taken away from everyone, including students, untill that right is explicitly restored. Just restore it to the necessary groups, taking care not to restore it to 'students'. So if you want to grant everyone 'edit' except for a particular account - sorry, don't know how that'd work. ==Other interesting tricks== * [[Wiki news items|Creating news items in a semantic wiki]] a6ffa752557c8959ebc616315f5a013c66d21c1b 0 1594 2471 2009-12-27T16:39:01Z Saruman! 2 Started wikitext text/x-wiki ==Namespace== To create the News: namespace, ''and'' have it recognized by SMW, we add to ''LocalSettings.php'': define("NS_NEWS", 112); define("NS_NEWS_TALK", 113); $wgExtraNamespaces[NS_NEWS] = "News"; $wgExtraNamespaces[NS_NEWS_TALK] = "News_talk"; $smwgNamespacesWithSemanticLinks[NS_NEWS] = true; $smwgQDefaultNamespaces = NULL; Of course this section must occur after the line that enables SMW 76d523f7f3d52545e8cf7987082495dc3263c8ed 2472 2471 2009-12-27T16:48:21Z Saruman! 2 item added wikitext text/x-wiki ==Namespace== To create the News: namespace, ''and'' have it recognized by SMW, we add to ''LocalSettings.php'': define("NS_NEWS", 112); define("NS_NEWS_TALK", 113); $wgExtraNamespaces[NS_NEWS] = "News"; $wgExtraNamespaces[NS_NEWS_TALK] = "News_talk"; $smwgNamespacesWithSemanticLinks[NS_NEWS] = true; $smwgQDefaultNamespaces = NULL; Of course this section must occur after the line that enables SMW (''enableSemantics(<name>);'') ==News item== To create a news item, we use a template that sets certain semantic parameters: * headline:: of type string, contains the headline. * newsdate:: of type date, contains the entry date of the news item. * newsauthor:: of type string, contains the author of the news item. * news expires:: of type date, contains the date at which the news item is no longer valid. * newsblurb:: of type string, contains a short excerpt of the news item. When called, the template sets the semantic properties, and produces the headline, the byline with author and dates, and a nice box containing the blurb. To create a news item, we now create a new page in the News: namespace, invoke the template, and put the news item text below it. ==News form== eee70b7e9c6431ce60666399f5b732d47ddb33f4 2497 2472 2010-03-23T16:03:01Z Kimberly 15 /* News item */ wikitext text/x-wiki ==Namespace== To create the News: namespace, ''and'' have it recognized by SMW, we add to ''LocalSettings.php'': define("NS_NEWS", 112); define("NS_NEWS_TALK", 113); $wgExtraNamespaces[NS_NEWS] = "News"; $wgExtraNamespaces[NS_NEWS_TALK] = "News_talk"; $smwgNamespacesWithSemanticLinks[NS_NEWS] = true; $smwgQDefaultNamespaces = NULL; Of course this section must occur after the line that enables SMW (''enableSemantics(<name>);'') ==News item== To create a news item, we use a template that sets certain semantic parameters: * headline:: of type string, contains the headline. * newsdate:: of type date, contains the entry date of the news item. * newsauthor:: of type string, contains the author of the news item. * news expires:: of type date, contains the date at which the news item is no longer valid. * newsblurb:: of type string, contains a short excerpt of the news item. When called, the template sets the semantic properties, and produces the headline, the byline with author and dates, and a nice box containing the blurb. [http://www.bestessays.com buy papers] To create a news item, we now create a new page in the News: namespace, invoke the template, and put the news item text below it. ==News form== a609e1428cf4407067bcda7748e8cd74066aef52 2513 2497 2010-03-29T10:05:01Z Saruman! 2 Removed spam wikitext text/x-wiki ==Namespace== To create the News: namespace, ''and'' have it recognized by SMW, we add to ''LocalSettings.php'': define("NS_NEWS", 112); define("NS_NEWS_TALK", 113); $wgExtraNamespaces[NS_NEWS] = "News"; $wgExtraNamespaces[NS_NEWS_TALK] = "News_talk"; $smwgNamespacesWithSemanticLinks[NS_NEWS] = true; $smwgQDefaultNamespaces = NULL; Of course this section must occur after the line that enables SMW (''enableSemantics(<name>);'') ==News item== To create a news item, we use a template that sets certain semantic parameters: * headline:: of type string, contains the headline. * newsdate:: of type date, contains the entry date of the news item. * newsauthor:: of type string, contains the author of the news item. * news expires:: of type date, contains the date at which the news item is no longer valid. * newsblurb:: of type string, contains a short excerpt of the news item. When called, the template sets the semantic properties, and produces the headline, the byline with author and dates, and a nice box containing the blurb. To create a news item, we now create a new page in the News: namespace, invoke the template, and put the news item text below it. ==News form== eee70b7e9c6431ce60666399f5b732d47ddb33f4 0 1595 2474 2009-12-29T06:17:51Z Saruman! 2 page created wikitext text/x-wiki Visitor is an Apache2 log analyzer that can show which people visited your website. I found a simple cron-based setup [http://www.codealpha.net/441/easy-apache-log-statistics-using-visitors/ here]. The setup for our Debian system goes like this: First install ''ip2host'' and ''visitor'' using the well understood sudo apt-get install ip2host visitor It will install the two requested packages, and probably also some extra packages like ''graphviz'' and ''ttf-liberation''. Next we create a cache directory for ''ip2host'' sudo mkdir /var/cache/ip2host Then we create the following script, which we save in ''/etc/cron.daily/visitors'': <source lang="bash"> #!/bin/bash MYIP="192.168" # i want to exclude my home network from the logs SERVERIP="222.222.222.222" # my server's ip REPORTDIR="/var/www/webstats" # folder where to store reports, this folder must exist ALOGDIR="/var/log/apache2" # folder containing the logs VISITORS="/usr/bin/visitors -A --exclude wp-cron.php --exclude robots.txt" # i exclude some files from the reports IP2H="ip2host --cache=/var/cache/ip2host/cache.db" GREPOPTIONS="-hv -e ^$MYIP -e ^$SERVERIP" # exclude my home network and my server's ip from the logs # we create a tmp file that will hold the logs TMPFILE=$(mktemp) if [[ ! -f "$TMPFILE" ]]; then echo "tmpfile doesn't exist." exit 1 fi # if you only have one site, or you want all the logs in a single report /bin/grep $GREPOPTIONS $ALOGDIR/access*.log{.1,} 2>/dev/null > $TMPFILE # get all the logs into the tmpfile, notice the GREPOPTIONS variable. # resolve all the ips and generate the reports, note that "--trails --prefix http://www.domain.com" is optional it's only needed for generating trails stats ($IP2H < $TMPFILE ) | $VISITORS --trails --prefix http://www.domain.com - > $REPORTDIR/stats.html # -OR- # if you have multiple vhosts/prefixes and want separate reports, you can use this: # replace all the "www prefix1 prefix2 prefix3" by your own prefixes (as in http://PREFIX.domain.com) for name in www prefix1 prefix2 prefix3; do /bin/grep $GREPOPTIONS $ALOGDIR/access-$name.log{.1,} 2>/dev/null > $TMPFILE ($IP2H < $TMPFILE ) | $VISITORS --trails --prefix http://$name.domain.com - > $REPORTDIR/stats-$name.html done rm -f $TMPFILE </source> a5483e2f12dc99273dfd612a1db04b0dd0d57a31 2475 2474 2009-12-29T08:27:40Z Saruman! 2 added location note wikitext text/x-wiki Visitor is an Apache2 log analyzer that can show which people visited your website. I found a simple cron-based setup [http://www.codealpha.net/441/easy-apache-log-statistics-using-visitors/ here]. The setup for our Debian system goes like this: First install ''ip2host'' and ''visitor'' using the well understood sudo apt-get install ip2host visitor It will install the two requested packages, and probably also some extra packages like ''graphviz'' and ''ttf-liberation''. Next we create a cache directory for ''ip2host'' sudo mkdir /var/cache/ip2host Then we create the following script, which we save in ''/etc/cron.daily/visitors'': <source lang="bash"> #!/bin/bash MYIP="192.168" # i want to exclude my home network from the logs SERVERIP="222.222.222.222" # my server's ip REPORTDIR="/var/www/webstats" # folder where to store reports, this folder must exist ALOGDIR="/var/log/apache2" # folder containing the logs VISITORS="/usr/bin/visitors -A --exclude wp-cron.php --exclude robots.txt" # i exclude some files from the reports IP2H="ip2host --cache=/var/cache/ip2host/cache.db" GREPOPTIONS="-hv -e ^$MYIP -e ^$SERVERIP" # exclude my home network and my server's ip from the logs # we create a tmp file that will hold the logs TMPFILE=$(mktemp) if [[ ! -f "$TMPFILE" ]]; then echo "tmpfile doesn't exist." exit 1 fi # if you only have one site, or you want all the logs in a single report # /bin/grep $GREPOPTIONS $ALOGDIR/access*.log{.1,} 2>/dev/null > $TMPFILE # get all the logs into the tmpfile, notice the GREPOPTIONS variable. # resolve all the ips and generate the reports, note that "--trails --prefix http://www.domain.com" is optional it's only needed for generating trails stats # ($IP2H < $TMPFILE ) | $VISITORS --trails --prefix http://www.domain.com - > $REPORTDIR/stats.html # -OR- # if you have multiple vhosts/prefixes and want separate reports, you can use this: # replace all the "saruman.biz mediawikifarm.nl" by your own prefixes (as they appear in the apache.conf for each vhost) for name in saruman.biz mediawikifarm.nl; do /bin/grep $GREPOPTIONS $ALOGDIR/$name-access.log{.1,} 2>/dev/null > $TMPFILE ($IP2H < $TMPFILE ) | $VISITORS --trails --prefix http://$name - > $REPORTDIR/stats-$name.html done rm -f $TMPFILE </source> Note that the resulting files get stored in ''/var/www/webstats'' and are readable for world. You could thus simply create a symlink somewhere in the directory tree of your website that links to these statistics (provided your apache configuration follows symlinks). Note that you might want to protect your statistics in some way, like with ''.htaccess''. 97e4bc9ab51f9d685e0988cf8fb1b26d8ffcf32c 0 1596 2476 2009-12-29T22:25:57Z 192.168.67.171 0 lirc wikitext text/x-wiki == lirc == LIRC CVS is hosted at SourceForge. You can get a copy of the current CVS tree using anonymous CVS login. First log in to the cvs server (press <enter> for password): cvs -d:pserver:anonymous@lirc.cvs.sourceforge.net:/cvsroot/lirc login Get the sources: cvs -z8 -d:pserver:anonymous@lirc.cvs.sourceforge.net:/cvsroot/lirc co lirc After initial checkout, you can change into this directory and execute cvs commands without the -d option. For example: cvs update Compile: cd lirc ./autogen.sh ./setup.sh make 492145f105c937cc0c9acc6dfe12197000002a0b 2477 2476 2009-12-30T15:12:46Z Insomnia 3 wikitext text/x-wiki == lirc == LIRC CVS is hosted at SourceForge. You can get a copy of the current CVS tree using anonymous CVS login. First log in to the cvs server (press <enter> for password): cvs -d:pserver:anonymous@lirc.cvs.sourceforge.net:/cvsroot/lirc login Get the sources: cvs -z8 -d:pserver:anonymous@lirc.cvs.sourceforge.net:/cvsroot/lirc co lirc After initial checkout, you can change into this directory and execute cvs commands without the -d option. For example: cvs update Compile: cd lirc ./autogen.sh ./setup.sh make == Metadata == Make sure you have set the filepaths right. Go to Mythtv setup - 6. Storage Directories Choose (create Fanart group) and choose the right directory Now go to the mythfrontend and choose to watch a video. Select the video and press W. Based on the filename [http://www.mythtv.org/wiki/MythVideo_File_Parsing] the right data will be searched. a827dc5950c37c3bd560d2fb784cc42e1229078a 2479 2477 2009-12-31T10:05:15Z 193.67.158.169 0 /* Metadata */ wikitext text/x-wiki == lirc == LIRC CVS is hosted at SourceForge. You can get a copy of the current CVS tree using anonymous CVS login. First log in to the cvs server (press <enter> for password): cvs -d:pserver:anonymous@lirc.cvs.sourceforge.net:/cvsroot/lirc login Get the sources: cvs -z8 -d:pserver:anonymous@lirc.cvs.sourceforge.net:/cvsroot/lirc co lirc After initial checkout, you can change into this directory and execute cvs commands without the -d option. For example: cvs update Compile: cd lirc ./autogen.sh ./setup.sh make == Metadata == Make sure you have set the filepaths right. Go to Mythtv setup - 6. Storage Directories Choose (create Fanart group) and choose the right directory Now go to the mythfrontend and choose to watch a video. Select the video and press W. Based on the filename [http://www.mythtv.org/wiki/MythVideo_File_Parsing] the right data will be searched. To configure the metadata yourself you can select the video and press I. Now configure the metadata. d1c045b041397dec29899c679590fd02d8d2f990 2480 2479 2010-01-06T20:12:07Z 82.161.20.132 0 /* lirc */ wikitext text/x-wiki == lirc == LIRC CVS is hosted at SourceForge. You can get a copy of the current CVS tree using anonymous CVS login. First log in to the cvs server (press <enter> for password): cvs -d:pserver:anonymous@lirc.cvs.sourceforge.net:/cvsroot/lirc login Get the sources: cvs -z8 -d:pserver:anonymous@lirc.cvs.sourceforge.net:/cvsroot/lirc co lirc After initial checkout, you can change into this directory and execute cvs commands without the -d option. For example: cvs update Compile: cd lirc ./autogen.sh ./setup.sh make /etc/lirc/hardware.conf # /etc/lirc/hardware.conf # # Arguments which will be used when launching lircd LIRCD_ARGS="" #Don't start lircmd even if there seems to be a good config file START_LIRCMD=false #Try to load appropriate kernel modules LOAD_MODULES=true # Run "lircd --driver=help" for a list of supported drivers. #DRIVER="pinsys" # If DEVICE is set to /dev/lirc and devfs is in use /dev/lirc/0 will be # automatically used instead DEVICE="/dev/lirc0" MODULES="lirc_mceusb" # Default configuration files for your hardware if any LIRCD_CONF="" LIRCMD_CONF="" /etc/lirc/lircd.conf ################################################################################ # lircd.conf file for the new Microsoft Media Center remote using a new # Microsoft Media Center receiver. ################################################################################ begin remote name mceusb bits 16 flags RC6|CONST_LENGTH eps 30 aeps 100 header 2667 889 one 444 444 zero 444 444 pre_data_bits 21 pre_data 0x37FF0 gap 105000 toggle_bit 22 rc6_mask 0x100000000 begin codes # starts at A1 BLUE 0x00007BA1 YELLOW 0x00007BA2 GREEN 0x00007BA3 RED 0x00007BA4 TELETEXT 0x00007BA5 RADIO 0x00007BAF PRINT 0x00007BB1 VIDEO 0x00007BB5 # VIDEOS button IMAGE 0x00007BB6 # PICTURES button PVR 0x00007BB7 # RECORDED TV button AUDIO 0x00007BB8 # MUSIC button TV 0x00007BB9 == Metadata == Make sure you have set the filepaths right. Go to Mythtv setup - 6. Storage Directories Choose (create Fanart group) and choose the right directory Now go to the mythfrontend and choose to watch a video. Select the video and press W. Based on the filename [http://www.mythtv.org/wiki/MythVideo_File_Parsing] the right data will be searched. To configure the metadata yourself you can select the video and press I. Now configure the metadata. 3e4e692842a9acb390fac9f1addae17b30c10f47 2481 2480 2010-01-06T21:30:54Z Insomnia 3 /* lirc */ wikitext text/x-wiki == lirc == LIRC CVS is hosted at SourceForge. You can get a copy of the current CVS tree using anonymous CVS login. First log in to the cvs server (press <enter> for password): cvs -d:pserver:anonymous@lirc.cvs.sourceforge.net:/cvsroot/lirc login Get the sources: cvs -z8 -d:pserver:anonymous@lirc.cvs.sourceforge.net:/cvsroot/lirc co lirc After initial checkout, you can change into this directory and execute cvs commands without the -d option. For example: cvs update Compile: cd lirc ./autogen.sh ./setup.sh make /etc/lirc/hardware.conf # /etc/lirc/hardware.conf # # Arguments which will be used when launching lircd LIRCD_ARGS="" #Don't start lircmd even if there seems to be a good config file START_LIRCMD=false #Try to load appropriate kernel modules LOAD_MODULES=true # Run "lircd --driver=help" for a list of supported drivers. #DRIVER="pinsys" # If DEVICE is set to /dev/lirc and devfs is in use /dev/lirc/0 will be # automatically used instead DEVICE="/dev/lirc0" MODULES="lirc_mceusb" # Default configuration files for your hardware if any LIRCD_CONF="" LIRCMD_CONF="" /etc/lirc/lircd.conf ################################################################################ # lircd.conf file for the new Microsoft Media Center remote using a new # Microsoft Media Center receiver. ################################################################################ begin remote name mceusb bits 16 flags RC6|CONST_LENGTH eps 30 aeps 100 header 2667 889 one 444 444 zero 444 444 pre_data_bits 21 pre_data 0x37FF0 gap 105000 toggle_bit 22 rc6_mask 0x100000000 begin codes # starts at A1 BLUE 0x00007BA1 YELLOW 0x00007BA2 GREEN 0x00007BA3 RED 0x00007BA4 TELETEXT 0x00007BA5 RADIO 0x00007BAF PRINT 0x00007BB1 VIDEO 0x00007BB5 # VIDEOS button IMAGE 0x00007BB6 # PICTURES button PVR 0x00007BB7 # RECORDED TV button AUDIO 0x00007BB8 # MUSIC button TV 0x00007BB9 # no BA - D8 Guide 0x00007BD9 TV 0x00007BDA # LIVE TV button Dvd 0x00007BDB Back 0x00007BDC OK 0x00007BDD Right 0x00007BDE Left 0x00007BDF Down 0x00007BE0 Up 0x00007BE1 STAR 0x00007BE2 Hash 0x00007BE3 PREVIOUS 0x00007BE4 # REPLAY button Next 0x00007BE5 # SKIP button Stop 0x00007BE6 Pause 0x00007BE7 Record 0x00007BE8 Play 0x00007BE9 Rewind 0x00007BEA Forward 0x00007BEB CHANNELDOWN 0x00007BEC CHANNELUP 0x00007BED Volumedown 0x00007BEE Volumeup 0x00007BEF INFO 0x00007BF0 # MORE (i) button Mute 0x00007BF1 MENU 0x00007BF2 # START (Windows) button POWER 0x00007BF3 ENTER 0x00007BF4 CLEAR 0x00007BF5 9 0x00007BF6 8 0x00007BF7 7 0x00007BF8 6 0x00007BF9 5 0x00007BFA 4 0x00007BFB 3 0x00007BFC 2 0x00007BFD 1 0x00007BFE 0 0x00007BFF end codes end remote ~/.lircrc begin prog = mythtv button = Two config = 2 end begin prog = mythtv button = Three config = 3 end begin prog = mythtv button = Four config = 4 end begin prog = mythtv button = Five config = 5 end begin prog = mythtv button = Six config = 6 end begin prog = mythtv button = Seven config = 7 end begin prog = mythtv button = Eight config = 8 end begin prog = mythtv button = Nine config = 9 end == Metadata == Make sure you have set the filepaths right. Go to Mythtv setup - 6. Storage Directories Choose (create Fanart group) and choose the right directory Now go to the mythfrontend and choose to watch a video. Select the video and press W. Based on the filename [http://www.mythtv.org/wiki/MythVideo_File_Parsing] the right data will be searched. To configure the metadata yourself you can select the video and press I. Now configure the metadata. fce1f3b2400ef970ad721019eba894ec9201f68d 2482 2481 2010-01-06T22:07:32Z 82.161.20.132 0 /* lirc */ wikitext text/x-wiki == lirc == LIRC CVS is hosted at SourceForge. You can get a copy of the current CVS tree using anonymous CVS login. First log in to the cvs server (press <enter> for password): cvs -d:pserver:anonymous@lirc.cvs.sourceforge.net:/cvsroot/lirc login Get the sources: cvs -z8 -d:pserver:anonymous@lirc.cvs.sourceforge.net:/cvsroot/lirc co lirc After initial checkout, you can change into this directory and execute cvs commands without the -d option. For example: cvs update Compile: cd lirc ./autogen.sh ./setup.sh make /etc/lirc/hardware.conf # /etc/lirc/hardware.conf # # Arguments which will be used when launching lircd LIRCD_ARGS="" #Don't start lircmd even if there seems to be a good config file START_LIRCMD=false #Try to load appropriate kernel modules LOAD_MODULES=true # Run "lircd --driver=help" for a list of supported drivers. #DRIVER="pinsys" # If DEVICE is set to /dev/lirc and devfs is in use /dev/lirc/0 will be # automatically used instead DEVICE="/dev/lirc0" MODULES="lirc_mceusb" TRANSMITTER_DEVICE="/dev/lirc0" # Default configuration files for your hardware if any LIRCD_CONF="" LIRCMD_CONF="" /etc/lirc/lircd.conf ################################################################################ # lircd.conf file for the new Microsoft Media Center remote using a new # Microsoft Media Center receiver. ################################################################################ begin remote name mceusb bits 16 flags RC6|CONST_LENGTH eps 30 aeps 100 header 2667 889 one 444 444 zero 444 444 pre_data_bits 21 pre_data 0x37FF0 gap 105000 toggle_bit 22 rc6_mask 0x100000000 begin codes # starts at A1 BLUE 0x00007BA1 YELLOW 0x00007BA2 GREEN 0x00007BA3 RED 0x00007BA4 TELETEXT 0x00007BA5 RADIO 0x00007BAF PRINT 0x00007BB1 VIDEO 0x00007BB5 # VIDEOS button IMAGE 0x00007BB6 # PICTURES button PVR 0x00007BB7 # RECORDED TV button AUDIO 0x00007BB8 # MUSIC button TV 0x00007BB9 # no BA - D8 Guide 0x00007BD9 TV 0x00007BDA # LIVE TV button Dvd 0x00007BDB Back 0x00007BDC OK 0x00007BDD Right 0x00007BDE Left 0x00007BDF Down 0x00007BE0 Up 0x00007BE1 STAR 0x00007BE2 Hash 0x00007BE3 PREVIOUS 0x00007BE4 # REPLAY button Next 0x00007BE5 # SKIP button Stop 0x00007BE6 Pause 0x00007BE7 Record 0x00007BE8 Play 0x00007BE9 Rewind 0x00007BEA Forward 0x00007BEB CHANNELDOWN 0x00007BEC CHANNELUP 0x00007BED Volumedown 0x00007BEE Volumeup 0x00007BEF INFO 0x00007BF0 # MORE (i) button Mute 0x00007BF1 MENU 0x00007BF2 # START (Windows) button POWER 0x00007BF3 ENTER 0x00007BF4 CLEAR 0x00007BF5 9 0x00007BF6 8 0x00007BF7 7 0x00007BF8 6 0x00007BF9 5 0x00007BFA 4 0x00007BFB 3 0x00007BFC 2 0x00007BFD 1 0x00007BFE 0 0x00007BFF end codes end remote ~/.lircrc begin prog = mythtv button = Two config = 2 end begin prog = mythtv button = Three config = 3 end begin prog = mythtv button = Four config = 4 end begin prog = mythtv button = Five config = 5 end begin prog = mythtv button = Six config = 6 end begin prog = mythtv button = Seven config = 7 end begin prog = mythtv button = Eight config = 8 end begin prog = mythtv button = Nine config = 9 end == Metadata == Make sure you have set the filepaths right. Go to Mythtv setup - 6. Storage Directories Choose (create Fanart group) and choose the right directory Now go to the mythfrontend and choose to watch a video. Select the video and press W. Based on the filename [http://www.mythtv.org/wiki/MythVideo_File_Parsing] the right data will be searched. To configure the metadata yourself you can select the video and press I. Now configure the metadata. 066e40d281556264aa78aca09dbe23cff019f354 2502 2482 2010-03-24T20:21:52Z Insomnia 3 /* Metadata */ wikitext text/x-wiki == lirc == LIRC CVS is hosted at SourceForge. You can get a copy of the current CVS tree using anonymous CVS login. First log in to the cvs server (press <enter> for password): cvs -d:pserver:anonymous@lirc.cvs.sourceforge.net:/cvsroot/lirc login Get the sources: cvs -z8 -d:pserver:anonymous@lirc.cvs.sourceforge.net:/cvsroot/lirc co lirc After initial checkout, you can change into this directory and execute cvs commands without the -d option. For example: cvs update Compile: cd lirc ./autogen.sh ./setup.sh make /etc/lirc/hardware.conf # /etc/lirc/hardware.conf # # Arguments which will be used when launching lircd LIRCD_ARGS="" #Don't start lircmd even if there seems to be a good config file START_LIRCMD=false #Try to load appropriate kernel modules LOAD_MODULES=true # Run "lircd --driver=help" for a list of supported drivers. #DRIVER="pinsys" # If DEVICE is set to /dev/lirc and devfs is in use /dev/lirc/0 will be # automatically used instead DEVICE="/dev/lirc0" MODULES="lirc_mceusb" TRANSMITTER_DEVICE="/dev/lirc0" # Default configuration files for your hardware if any LIRCD_CONF="" LIRCMD_CONF="" /etc/lirc/lircd.conf ################################################################################ # lircd.conf file for the new Microsoft Media Center remote using a new # Microsoft Media Center receiver. ################################################################################ begin remote name mceusb bits 16 flags RC6|CONST_LENGTH eps 30 aeps 100 header 2667 889 one 444 444 zero 444 444 pre_data_bits 21 pre_data 0x37FF0 gap 105000 toggle_bit 22 rc6_mask 0x100000000 begin codes # starts at A1 BLUE 0x00007BA1 YELLOW 0x00007BA2 GREEN 0x00007BA3 RED 0x00007BA4 TELETEXT 0x00007BA5 RADIO 0x00007BAF PRINT 0x00007BB1 VIDEO 0x00007BB5 # VIDEOS button IMAGE 0x00007BB6 # PICTURES button PVR 0x00007BB7 # RECORDED TV button AUDIO 0x00007BB8 # MUSIC button TV 0x00007BB9 # no BA - D8 Guide 0x00007BD9 TV 0x00007BDA # LIVE TV button Dvd 0x00007BDB Back 0x00007BDC OK 0x00007BDD Right 0x00007BDE Left 0x00007BDF Down 0x00007BE0 Up 0x00007BE1 STAR 0x00007BE2 Hash 0x00007BE3 PREVIOUS 0x00007BE4 # REPLAY button Next 0x00007BE5 # SKIP button Stop 0x00007BE6 Pause 0x00007BE7 Record 0x00007BE8 Play 0x00007BE9 Rewind 0x00007BEA Forward 0x00007BEB CHANNELDOWN 0x00007BEC CHANNELUP 0x00007BED Volumedown 0x00007BEE Volumeup 0x00007BEF INFO 0x00007BF0 # MORE (i) button Mute 0x00007BF1 MENU 0x00007BF2 # START (Windows) button POWER 0x00007BF3 ENTER 0x00007BF4 CLEAR 0x00007BF5 9 0x00007BF6 8 0x00007BF7 7 0x00007BF8 6 0x00007BF9 5 0x00007BFA 4 0x00007BFB 3 0x00007BFC 2 0x00007BFD 1 0x00007BFE 0 0x00007BFF end codes end remote ~/.lircrc begin prog = mythtv button = Two config = 2 end begin prog = mythtv button = Three config = 3 end begin prog = mythtv button = Four config = 4 end begin prog = mythtv button = Five config = 5 end begin prog = mythtv button = Six config = 6 end begin prog = mythtv button = Seven config = 7 end begin prog = mythtv button = Eight config = 8 end begin prog = mythtv button = Nine config = 9 end == IRblaster == To get the right codes from youre remote you can record it with irrecord #irrecord /tmp/remote.conf Now follow the instructions To get the raw codes #irrecord -f /tmp/remoteraw.conf You wil get this file for a topfield tf6000cok remote # Please make this file available to others # by sending it to <lirc@bartelmus.de> # # this config file was automatically generated # using lirc-0.8.6(default) on Wed Mar 24 20:58:54 2010 # # contributed by # # brand:Topfield # model no. of remote control: TP-014 # devices being controlled by this remote: Topfield TF6000COK # begin remote name topfield flags RAW_CODES|CONST_LENGTH eps 30 aeps 100 gap 107620 begin raw_codes name KEY_1 9000 4450 600 500 650 450 650 1650 600 500 600 500 650 500 600 500 600 500 650 1600 650 1600 600 1650 600 1650 600 1650 600 1650 600 1600 650 1600 600 1650 600 550 600 500 600 500 600 1650 600 550 550 550 600 500 650 500 600 1650 600 1650 600 1600 600 550 600 1650 550 1650 650 1650 550 name KEY_2 9050 4400 600 500 650 500 600 1650 600 500 600 500 650 500 600 500 600 500 650 1650 600 1600 600 1650 600 1650 600 1650 600 1650 600 1650 600 1600 600 550 600 1650 600 500 600 500 650 1600 600 550 600 500 600 550 600 1600 600 550 600 1650 550 1650 650 500 600 1650 600 1650 600 1600 600 name KEY_3 9000 4450 600 500 650 500 600 1600 650 500 600 500 600 550 600 500 600 550 600 1600 600 1650 650 1600 600 1650 600 1650 600 1650 600 1600 600 1650 600 1650 600 1650 600 500 600 550 600 1650 600 500 600 500 600 550 600 500 600 550 600 1600 650 1650 550 550 600 1650 600 1600 600 1650 600 name KEY_4 9050 4450 600 500 600 500 650 1600 600 500 650 500 600 500 650 500 600 500 600 1650 600 1650 600 1650 600 1600 650 1600 650 1600 600 1650 600 1650 600 500 600 550 600 1650 550 550 600 1650 600 500 600 500 650 500 600 1650 600 1650 600 500 600 1650 600 500 650 1600 600 1650 600 1650 600 name KEY_5 9050 4400 650 450 650 500 600 1650 600 500 650 500 600 500 600 500 650 500 600 1650 600 1600 650 1650 600 1600 600 1650 600 1650 600 1650 600 1650 600 1650 600 500 600 1650 600 500 600 1650 600 500 650 500 600 500 600 550 600 1650 600 500 600 1650 600 500 600 1650 600 1650 600 1650 600 name KEY_6 9050 4400 650 500 600 500 600 1650 600 500 650 500 600 500 600 500 650 500 600 1650 600 1650 600 1600 600 1650 600 1650 600 1650 600 1650 600 1650 600 500 600 1650 600 1650 600 500 600 1650 600 550 550 550 600 500 600 1650 600 500 600 550 600 1650 600 500 600 1650 600 1650 600 1650 600 name KEY_7 9000 4450 600 500 600 500 650 1600 650 450 650 500 600 500 650 500 600 500 600 1650 600 1650 600 1650 600 1650 600 1600 650 1600 600 1650 600 1650 600 1650 600 1650 550 1650 650 500 600 1650 600 500 600 550 600 500 600 500 600 550 600 500 600 1650 600 500 650 1600 600 1650 600 1650 600 name KEY_8 9050 4400 650 450 650 500 600 1650 600 500 650 500 600 500 600 500 650 500 600 1650 600 1600 650 1650 550 1650 600 1650 600 1650 600 1650 600 1600 650 500 600 550 550 550 600 1650 600 1650 550 550 600 500 650 500 600 1600 650 1650 550 1650 600 550 600 500 600 1650 600 1650 600 1650 600 name KEY_9 9050 4400 650 500 600 500 600 1650 600 500 650 500 600 500 600 500 650 500 600 1650 600 1650 600 1600 600 1650 650 1600 600 1650 600 1650 600 1650 600 1600 600 550 600 500 600 1650 600 1650 600 550 550 550 600 500 600 550 600 1600 600 1650 600 550 600 500 600 1650 600 1650 600 1650 600 name KEY_0 9000 4450 600 500 650 450 650 1600 650 500 600 500 600 500 650 500 600 550 600 1600 600 1650 600 1650 600 1650 600 1650 600 1650 600 1600 600 1650 600 550 600 500 600 500 650 500 600 1650 600 500 600 550 600 500 600 1650 600 1650 600 1600 650 1650 550 550 600 1650 600 1600 600 1650 600 name KEY_CHANNELUP 9050 4400 650 500 600 500 650 1600 650 500 600 500 600 500 650 500 600 500 650 1600 600 1650 600 1650 600 1650 600 1600 600 1650 650 1600 600 1650 600 1650 600 500 600 1650 600 500 600 1650 650 500 600 1600 650 500 600 550 550 1650 600 550 600 1650 550 550 600 1650 600 500 600 1650 600 name KEY_CHANNELDOWN 9050 4400 650 500 600 500 650 1600 600 500 650 500 600 550 600 500 600 500 600 1650 600 1650 600 1650 600 1600 650 1650 600 1600 600 1650 600 1650 600 500 650 1600 600 1650 600 550 600 1600 600 550 600 1650 550 550 600 1650 600 500 600 550 600 1650 550 550 600 1650 600 500 600 1650 600 name KEY_VOLUMEUP 9050 4400 650 500 600 500 600 1650 600 500 650 500 600 500 600 500 650 500 600 1650 600 1650 600 1600 600 1650 650 1600 600 1650 600 1650 600 1650 600 1600 600 1650 650 1600 600 500 650 1650 550 550 600 1650 600 500 600 500 600 550 600 500 650 1600 600 500 650 1650 550 550 600 1650 600 name KEY_VOLUMEDOWN 9050 4400 650 500 600 550 600 1600 650 500 600 500 600 500 650 500 600 500 650 1600 600 1650 600 1650 600 1650 600 1650 600 1600 650 1600 600 1650 600 550 600 500 600 500 600 1650 600 1650 600 500 650 1600 600 550 600 1650 600 1600 600 1650 600 550 550 550 600 1650 600 500 600 1650 600 end raw_codes end remote == Metadata == Make sure you have set the filepaths right. Go to Mythtv setup - 6. Storage Directories Choose (create Fanart group) and choose the right directory Now go to the mythfrontend and choose to watch a video. Select the video and press W. Based on the filename [http://www.mythtv.org/wiki/MythVideo_File_Parsing] the right data will be searched. To configure the metadata yourself you can select the video and press I. Now configure the metadata. f4c92ead0adbc842d864e7750641ed58df44bedc 2503 2502 2010-03-24T20:26:09Z Insomnia 3 /* IRblaster */ wikitext text/x-wiki == lirc == LIRC CVS is hosted at SourceForge. You can get a copy of the current CVS tree using anonymous CVS login. First log in to the cvs server (press <enter> for password): cvs -d:pserver:anonymous@lirc.cvs.sourceforge.net:/cvsroot/lirc login Get the sources: cvs -z8 -d:pserver:anonymous@lirc.cvs.sourceforge.net:/cvsroot/lirc co lirc After initial checkout, you can change into this directory and execute cvs commands without the -d option. For example: cvs update Compile: cd lirc ./autogen.sh ./setup.sh make /etc/lirc/hardware.conf # /etc/lirc/hardware.conf # # Arguments which will be used when launching lircd LIRCD_ARGS="" #Don't start lircmd even if there seems to be a good config file START_LIRCMD=false #Try to load appropriate kernel modules LOAD_MODULES=true # Run "lircd --driver=help" for a list of supported drivers. #DRIVER="pinsys" # If DEVICE is set to /dev/lirc and devfs is in use /dev/lirc/0 will be # automatically used instead DEVICE="/dev/lirc0" MODULES="lirc_mceusb" TRANSMITTER_DEVICE="/dev/lirc0" # Default configuration files for your hardware if any LIRCD_CONF="" LIRCMD_CONF="" /etc/lirc/lircd.conf ################################################################################ # lircd.conf file for the new Microsoft Media Center remote using a new # Microsoft Media Center receiver. ################################################################################ begin remote name mceusb bits 16 flags RC6|CONST_LENGTH eps 30 aeps 100 header 2667 889 one 444 444 zero 444 444 pre_data_bits 21 pre_data 0x37FF0 gap 105000 toggle_bit 22 rc6_mask 0x100000000 begin codes # starts at A1 BLUE 0x00007BA1 YELLOW 0x00007BA2 GREEN 0x00007BA3 RED 0x00007BA4 TELETEXT 0x00007BA5 RADIO 0x00007BAF PRINT 0x00007BB1 VIDEO 0x00007BB5 # VIDEOS button IMAGE 0x00007BB6 # PICTURES button PVR 0x00007BB7 # RECORDED TV button AUDIO 0x00007BB8 # MUSIC button TV 0x00007BB9 # no BA - D8 Guide 0x00007BD9 TV 0x00007BDA # LIVE TV button Dvd 0x00007BDB Back 0x00007BDC OK 0x00007BDD Right 0x00007BDE Left 0x00007BDF Down 0x00007BE0 Up 0x00007BE1 STAR 0x00007BE2 Hash 0x00007BE3 PREVIOUS 0x00007BE4 # REPLAY button Next 0x00007BE5 # SKIP button Stop 0x00007BE6 Pause 0x00007BE7 Record 0x00007BE8 Play 0x00007BE9 Rewind 0x00007BEA Forward 0x00007BEB CHANNELDOWN 0x00007BEC CHANNELUP 0x00007BED Volumedown 0x00007BEE Volumeup 0x00007BEF INFO 0x00007BF0 # MORE (i) button Mute 0x00007BF1 MENU 0x00007BF2 # START (Windows) button POWER 0x00007BF3 ENTER 0x00007BF4 CLEAR 0x00007BF5 9 0x00007BF6 8 0x00007BF7 7 0x00007BF8 6 0x00007BF9 5 0x00007BFA 4 0x00007BFB 3 0x00007BFC 2 0x00007BFD 1 0x00007BFE 0 0x00007BFF end codes end remote ~/.lircrc begin prog = mythtv button = Two config = 2 end begin prog = mythtv button = Three config = 3 end begin prog = mythtv button = Four config = 4 end begin prog = mythtv button = Five config = 5 end begin prog = mythtv button = Six config = 6 end begin prog = mythtv button = Seven config = 7 end begin prog = mythtv button = Eight config = 8 end begin prog = mythtv button = Nine config = 9 end == IRblaster == To get the right codes from youre remote you can record it with irrecord #irrecord /tmp/remote.conf Now follow the instructions To get the raw codes #irrecord -f /tmp/remoteraw.conf You wil get this file for a topfield tf6000cok remote # Please make this file available to others # by sending it to <lirc@bartelmus.de> # # this config file was automatically generated # using lirc-0.8.6(default) on Wed Mar 24 20:58:54 2010 # # contributed by # # brand:Topfield # model no. of remote control: TP-014 # devices being controlled by this remote: Topfield TF6000COK # begin remote name topfield flags RAW_CODES|CONST_LENGTH eps 30 aeps 100 gap 107620 begin raw_codes name KEY_1 9000 4450 600 500 650 450 650 1650 600 500 600 500 650 500 600 500 600 500 650 1600 650 1600 600 1650 600 1650 600 1650 600 1650 600 1600 650 1600 600 1650 600 550 600 500 600 500 600 1650 600 550 550 550 600 500 650 500 600 1650 600 1650 600 1600 600 550 600 1650 550 1650 650 1650 550 name KEY_2 9050 4400 600 500 650 500 600 1650 600 500 600 500 650 500 600 500 600 500 650 1650 600 1600 600 1650 600 1650 600 1650 600 1650 600 1650 600 1600 600 550 600 1650 600 500 600 500 650 1600 600 550 600 500 600 550 600 1600 600 550 600 1650 550 1650 650 500 600 1650 600 1650 600 1600 600 name KEY_3 9000 4450 600 500 650 500 600 1600 650 500 600 500 600 550 600 500 600 550 600 1600 600 1650 650 1600 600 1650 600 1650 600 1650 600 1600 600 1650 600 1650 600 1650 600 500 600 550 600 1650 600 500 600 500 600 550 600 500 600 550 600 1600 650 1650 550 550 600 1650 600 1600 600 1650 600 name KEY_4 9050 4450 600 500 600 500 650 1600 600 500 650 500 600 500 650 500 600 500 600 1650 600 1650 600 1650 600 1600 650 1600 650 1600 600 1650 600 1650 600 500 600 550 600 1650 550 550 600 1650 600 500 600 500 650 500 600 1650 600 1650 600 500 600 1650 600 500 650 1600 600 1650 600 1650 600 name KEY_5 9050 4400 650 450 650 500 600 1650 600 500 650 500 600 500 600 500 650 500 600 1650 600 1600 650 1650 600 1600 600 1650 600 1650 600 1650 600 1650 600 1650 600 500 600 1650 600 500 600 1650 600 500 650 500 600 500 600 550 600 1650 600 500 600 1650 600 500 600 1650 600 1650 600 1650 600 name KEY_6 9050 4400 650 500 600 500 600 1650 600 500 650 500 600 500 600 500 650 500 600 1650 600 1650 600 1600 600 1650 600 1650 600 1650 600 1650 600 1650 600 500 600 1650 600 1650 600 500 600 1650 600 550 550 550 600 500 600 1650 600 500 600 550 600 1650 600 500 600 1650 600 1650 600 1650 600 name KEY_7 9000 4450 600 500 600 500 650 1600 650 450 650 500 600 500 650 500 600 500 600 1650 600 1650 600 1650 600 1650 600 1600 650 1600 600 1650 600 1650 600 1650 600 1650 550 1650 650 500 600 1650 600 500 600 550 600 500 600 500 600 550 600 500 600 1650 600 500 650 1600 600 1650 600 1650 600 name KEY_8 9050 4400 650 450 650 500 600 1650 600 500 650 500 600 500 600 500 650 500 600 1650 600 1600 650 1650 550 1650 600 1650 600 1650 600 1650 600 1600 650 500 600 550 550 550 600 1650 600 1650 550 550 600 500 650 500 600 1600 650 1650 550 1650 600 550 600 500 600 1650 600 1650 600 1650 600 name KEY_9 9050 4400 650 500 600 500 600 1650 600 500 650 500 600 500 600 500 650 500 600 1650 600 1650 600 1600 600 1650 650 1600 600 1650 600 1650 600 1650 600 1600 600 550 600 500 600 1650 600 1650 600 550 550 550 600 500 600 550 600 1600 600 1650 600 550 600 500 600 1650 600 1650 600 1650 600 name KEY_0 9000 4450 600 500 650 450 650 1600 650 500 600 500 600 500 650 500 600 550 600 1600 600 1650 600 1650 600 1650 600 1650 600 1650 600 1600 600 1650 600 550 600 500 600 500 650 500 600 1650 600 500 600 550 600 500 600 1650 600 1650 600 1600 650 1650 550 550 600 1650 600 1600 600 1650 600 name KEY_CHANNELUP 9050 4400 650 500 600 500 650 1600 650 500 600 500 600 500 650 500 600 500 650 1600 600 1650 600 1650 600 1650 600 1600 600 1650 650 1600 600 1650 600 1650 600 500 600 1650 600 500 600 1650 650 500 600 1600 650 500 600 550 550 1650 600 550 600 1650 550 550 600 1650 600 500 600 1650 600 name KEY_CHANNELDOWN 9050 4400 650 500 600 500 650 1600 600 500 650 500 600 550 600 500 600 500 600 1650 600 1650 600 1650 600 1600 650 1650 600 1600 600 1650 600 1650 600 500 650 1600 600 1650 600 550 600 1600 600 550 600 1650 550 550 600 1650 600 500 600 550 600 1650 550 550 600 1650 600 500 600 1650 600 name KEY_VOLUMEUP 9050 4400 650 500 600 500 600 1650 600 500 650 500 600 500 600 500 650 500 600 1650 600 1650 600 1600 600 1650 650 1600 600 1650 600 1650 600 1650 600 1600 600 1650 650 1600 600 500 650 1650 550 550 600 1650 600 500 600 500 600 550 600 500 650 1600 600 500 650 1650 550 550 600 1650 600 name KEY_VOLUMEDOWN 9050 4400 650 500 600 550 600 1600 650 500 600 500 600 500 650 500 600 500 650 1600 600 1650 600 1650 600 1650 600 1650 600 1600 650 1600 600 1650 600 550 600 500 600 500 600 1650 600 1650 600 500 650 1600 600 550 600 1650 600 1600 600 1650 600 550 550 550 600 1650 600 500 600 1650 600 end raw_codes end remote Now save this file in /etc/lirc and edit /etc/lirc/lircd.conf include "/etc/lirc/remote.conf" Now we can test irblaster #irsend SEND_ONCE remote KEY_1 The channel on the topfield DVB must jump to channel 1 == Metadata == Make sure you have set the filepaths right. Go to Mythtv setup - 6. Storage Directories Choose (create Fanart group) and choose the right directory Now go to the mythfrontend and choose to watch a video. Select the video and press W. Based on the filename [http://www.mythtv.org/wiki/MythVideo_File_Parsing] the right data will be searched. To configure the metadata yourself you can select the video and press I. Now configure the metadata. bcbe98e6bdc3c607c2a509203cfac3470dca3688 2504 2503 2010-03-24T20:27:04Z Insomnia 3 /* IRblaster */ wikitext text/x-wiki == lirc == LIRC CVS is hosted at SourceForge. You can get a copy of the current CVS tree using anonymous CVS login. First log in to the cvs server (press <enter> for password): cvs -d:pserver:anonymous@lirc.cvs.sourceforge.net:/cvsroot/lirc login Get the sources: cvs -z8 -d:pserver:anonymous@lirc.cvs.sourceforge.net:/cvsroot/lirc co lirc After initial checkout, you can change into this directory and execute cvs commands without the -d option. For example: cvs update Compile: cd lirc ./autogen.sh ./setup.sh make /etc/lirc/hardware.conf # /etc/lirc/hardware.conf # # Arguments which will be used when launching lircd LIRCD_ARGS="" #Don't start lircmd even if there seems to be a good config file START_LIRCMD=false #Try to load appropriate kernel modules LOAD_MODULES=true # Run "lircd --driver=help" for a list of supported drivers. #DRIVER="pinsys" # If DEVICE is set to /dev/lirc and devfs is in use /dev/lirc/0 will be # automatically used instead DEVICE="/dev/lirc0" MODULES="lirc_mceusb" TRANSMITTER_DEVICE="/dev/lirc0" # Default configuration files for your hardware if any LIRCD_CONF="" LIRCMD_CONF="" /etc/lirc/lircd.conf ################################################################################ # lircd.conf file for the new Microsoft Media Center remote using a new # Microsoft Media Center receiver. ################################################################################ begin remote name mceusb bits 16 flags RC6|CONST_LENGTH eps 30 aeps 100 header 2667 889 one 444 444 zero 444 444 pre_data_bits 21 pre_data 0x37FF0 gap 105000 toggle_bit 22 rc6_mask 0x100000000 begin codes # starts at A1 BLUE 0x00007BA1 YELLOW 0x00007BA2 GREEN 0x00007BA3 RED 0x00007BA4 TELETEXT 0x00007BA5 RADIO 0x00007BAF PRINT 0x00007BB1 VIDEO 0x00007BB5 # VIDEOS button IMAGE 0x00007BB6 # PICTURES button PVR 0x00007BB7 # RECORDED TV button AUDIO 0x00007BB8 # MUSIC button TV 0x00007BB9 # no BA - D8 Guide 0x00007BD9 TV 0x00007BDA # LIVE TV button Dvd 0x00007BDB Back 0x00007BDC OK 0x00007BDD Right 0x00007BDE Left 0x00007BDF Down 0x00007BE0 Up 0x00007BE1 STAR 0x00007BE2 Hash 0x00007BE3 PREVIOUS 0x00007BE4 # REPLAY button Next 0x00007BE5 # SKIP button Stop 0x00007BE6 Pause 0x00007BE7 Record 0x00007BE8 Play 0x00007BE9 Rewind 0x00007BEA Forward 0x00007BEB CHANNELDOWN 0x00007BEC CHANNELUP 0x00007BED Volumedown 0x00007BEE Volumeup 0x00007BEF INFO 0x00007BF0 # MORE (i) button Mute 0x00007BF1 MENU 0x00007BF2 # START (Windows) button POWER 0x00007BF3 ENTER 0x00007BF4 CLEAR 0x00007BF5 9 0x00007BF6 8 0x00007BF7 7 0x00007BF8 6 0x00007BF9 5 0x00007BFA 4 0x00007BFB 3 0x00007BFC 2 0x00007BFD 1 0x00007BFE 0 0x00007BFF end codes end remote ~/.lircrc begin prog = mythtv button = Two config = 2 end begin prog = mythtv button = Three config = 3 end begin prog = mythtv button = Four config = 4 end begin prog = mythtv button = Five config = 5 end begin prog = mythtv button = Six config = 6 end begin prog = mythtv button = Seven config = 7 end begin prog = mythtv button = Eight config = 8 end begin prog = mythtv button = Nine config = 9 end == IRblaster == To get the right codes from youre remote you can record it with irrecord. This will provide a configuration file which you can use in lirc #irrecord /tmp/remote.conf Now follow the instructions To get the raw codes #irrecord -f /tmp/remoteraw.conf You wil get this file for a topfield tf6000cok remote # Please make this file available to others # by sending it to <lirc@bartelmus.de> # # this config file was automatically generated # using lirc-0.8.6(default) on Wed Mar 24 20:58:54 2010 # # contributed by # # brand:Topfield # model no. of remote control: TP-014 # devices being controlled by this remote: Topfield TF6000COK # begin remote name topfield flags RAW_CODES|CONST_LENGTH eps 30 aeps 100 gap 107620 begin raw_codes name KEY_1 9000 4450 600 500 650 450 650 1650 600 500 600 500 650 500 600 500 600 500 650 1600 650 1600 600 1650 600 1650 600 1650 600 1650 600 1600 650 1600 600 1650 600 550 600 500 600 500 600 1650 600 550 550 550 600 500 650 500 600 1650 600 1650 600 1600 600 550 600 1650 550 1650 650 1650 550 name KEY_2 9050 4400 600 500 650 500 600 1650 600 500 600 500 650 500 600 500 600 500 650 1650 600 1600 600 1650 600 1650 600 1650 600 1650 600 1650 600 1600 600 550 600 1650 600 500 600 500 650 1600 600 550 600 500 600 550 600 1600 600 550 600 1650 550 1650 650 500 600 1650 600 1650 600 1600 600 name KEY_3 9000 4450 600 500 650 500 600 1600 650 500 600 500 600 550 600 500 600 550 600 1600 600 1650 650 1600 600 1650 600 1650 600 1650 600 1600 600 1650 600 1650 600 1650 600 500 600 550 600 1650 600 500 600 500 600 550 600 500 600 550 600 1600 650 1650 550 550 600 1650 600 1600 600 1650 600 name KEY_4 9050 4450 600 500 600 500 650 1600 600 500 650 500 600 500 650 500 600 500 600 1650 600 1650 600 1650 600 1600 650 1600 650 1600 600 1650 600 1650 600 500 600 550 600 1650 550 550 600 1650 600 500 600 500 650 500 600 1650 600 1650 600 500 600 1650 600 500 650 1600 600 1650 600 1650 600 name KEY_5 9050 4400 650 450 650 500 600 1650 600 500 650 500 600 500 600 500 650 500 600 1650 600 1600 650 1650 600 1600 600 1650 600 1650 600 1650 600 1650 600 1650 600 500 600 1650 600 500 600 1650 600 500 650 500 600 500 600 550 600 1650 600 500 600 1650 600 500 600 1650 600 1650 600 1650 600 name KEY_6 9050 4400 650 500 600 500 600 1650 600 500 650 500 600 500 600 500 650 500 600 1650 600 1650 600 1600 600 1650 600 1650 600 1650 600 1650 600 1650 600 500 600 1650 600 1650 600 500 600 1650 600 550 550 550 600 500 600 1650 600 500 600 550 600 1650 600 500 600 1650 600 1650 600 1650 600 name KEY_7 9000 4450 600 500 600 500 650 1600 650 450 650 500 600 500 650 500 600 500 600 1650 600 1650 600 1650 600 1650 600 1600 650 1600 600 1650 600 1650 600 1650 600 1650 550 1650 650 500 600 1650 600 500 600 550 600 500 600 500 600 550 600 500 600 1650 600 500 650 1600 600 1650 600 1650 600 name KEY_8 9050 4400 650 450 650 500 600 1650 600 500 650 500 600 500 600 500 650 500 600 1650 600 1600 650 1650 550 1650 600 1650 600 1650 600 1650 600 1600 650 500 600 550 550 550 600 1650 600 1650 550 550 600 500 650 500 600 1600 650 1650 550 1650 600 550 600 500 600 1650 600 1650 600 1650 600 name KEY_9 9050 4400 650 500 600 500 600 1650 600 500 650 500 600 500 600 500 650 500 600 1650 600 1650 600 1600 600 1650 650 1600 600 1650 600 1650 600 1650 600 1600 600 550 600 500 600 1650 600 1650 600 550 550 550 600 500 600 550 600 1600 600 1650 600 550 600 500 600 1650 600 1650 600 1650 600 name KEY_0 9000 4450 600 500 650 450 650 1600 650 500 600 500 600 500 650 500 600 550 600 1600 600 1650 600 1650 600 1650 600 1650 600 1650 600 1600 600 1650 600 550 600 500 600 500 650 500 600 1650 600 500 600 550 600 500 600 1650 600 1650 600 1600 650 1650 550 550 600 1650 600 1600 600 1650 600 name KEY_CHANNELUP 9050 4400 650 500 600 500 650 1600 650 500 600 500 600 500 650 500 600 500 650 1600 600 1650 600 1650 600 1650 600 1600 600 1650 650 1600 600 1650 600 1650 600 500 600 1650 600 500 600 1650 650 500 600 1600 650 500 600 550 550 1650 600 550 600 1650 550 550 600 1650 600 500 600 1650 600 name KEY_CHANNELDOWN 9050 4400 650 500 600 500 650 1600 600 500 650 500 600 550 600 500 600 500 600 1650 600 1650 600 1650 600 1600 650 1650 600 1600 600 1650 600 1650 600 500 650 1600 600 1650 600 550 600 1600 600 550 600 1650 550 550 600 1650 600 500 600 550 600 1650 550 550 600 1650 600 500 600 1650 600 name KEY_VOLUMEUP 9050 4400 650 500 600 500 600 1650 600 500 650 500 600 500 600 500 650 500 600 1650 600 1650 600 1600 600 1650 650 1600 600 1650 600 1650 600 1650 600 1600 600 1650 650 1600 600 500 650 1650 550 550 600 1650 600 500 600 500 600 550 600 500 650 1600 600 500 650 1650 550 550 600 1650 600 name KEY_VOLUMEDOWN 9050 4400 650 500 600 550 600 1600 650 500 600 500 600 500 650 500 600 500 650 1600 600 1650 600 1650 600 1650 600 1650 600 1600 650 1600 600 1650 600 550 600 500 600 500 600 1650 600 1650 600 500 650 1600 600 550 600 1650 600 1600 600 1650 600 550 550 550 600 1650 600 500 600 1650 600 end raw_codes end remote Now save this file in /etc/lirc and edit /etc/lirc/lircd.conf include "/etc/lirc/remote.conf" Now we can test irblaster #irsend SEND_ONCE remote KEY_1 The channel on the topfield DVB must jump to channel 1 == Metadata == Make sure you have set the filepaths right. Go to Mythtv setup - 6. Storage Directories Choose (create Fanart group) and choose the right directory Now go to the mythfrontend and choose to watch a video. Select the video and press W. Based on the filename [http://www.mythtv.org/wiki/MythVideo_File_Parsing] the right data will be searched. To configure the metadata yourself you can select the video and press I. Now configure the metadata. ca2dce878408a3c95f100a15d36b3407aeb2bcef 2509 2504 2010-03-28T18:13:24Z 82.161.20.132 0 /* Metadata */ wikitext text/x-wiki == lirc == LIRC CVS is hosted at SourceForge. You can get a copy of the current CVS tree using anonymous CVS login. First log in to the cvs server (press <enter> for password): cvs -d:pserver:anonymous@lirc.cvs.sourceforge.net:/cvsroot/lirc login Get the sources: cvs -z8 -d:pserver:anonymous@lirc.cvs.sourceforge.net:/cvsroot/lirc co lirc After initial checkout, you can change into this directory and execute cvs commands without the -d option. For example: cvs update Compile: cd lirc ./autogen.sh ./setup.sh make /etc/lirc/hardware.conf # /etc/lirc/hardware.conf # # Arguments which will be used when launching lircd LIRCD_ARGS="" #Don't start lircmd even if there seems to be a good config file START_LIRCMD=false #Try to load appropriate kernel modules LOAD_MODULES=true # Run "lircd --driver=help" for a list of supported drivers. #DRIVER="pinsys" # If DEVICE is set to /dev/lirc and devfs is in use /dev/lirc/0 will be # automatically used instead DEVICE="/dev/lirc0" MODULES="lirc_mceusb" TRANSMITTER_DEVICE="/dev/lirc0" # Default configuration files for your hardware if any LIRCD_CONF="" LIRCMD_CONF="" /etc/lirc/lircd.conf ################################################################################ # lircd.conf file for the new Microsoft Media Center remote using a new # Microsoft Media Center receiver. ################################################################################ begin remote name mceusb bits 16 flags RC6|CONST_LENGTH eps 30 aeps 100 header 2667 889 one 444 444 zero 444 444 pre_data_bits 21 pre_data 0x37FF0 gap 105000 toggle_bit 22 rc6_mask 0x100000000 begin codes # starts at A1 BLUE 0x00007BA1 YELLOW 0x00007BA2 GREEN 0x00007BA3 RED 0x00007BA4 TELETEXT 0x00007BA5 RADIO 0x00007BAF PRINT 0x00007BB1 VIDEO 0x00007BB5 # VIDEOS button IMAGE 0x00007BB6 # PICTURES button PVR 0x00007BB7 # RECORDED TV button AUDIO 0x00007BB8 # MUSIC button TV 0x00007BB9 # no BA - D8 Guide 0x00007BD9 TV 0x00007BDA # LIVE TV button Dvd 0x00007BDB Back 0x00007BDC OK 0x00007BDD Right 0x00007BDE Left 0x00007BDF Down 0x00007BE0 Up 0x00007BE1 STAR 0x00007BE2 Hash 0x00007BE3 PREVIOUS 0x00007BE4 # REPLAY button Next 0x00007BE5 # SKIP button Stop 0x00007BE6 Pause 0x00007BE7 Record 0x00007BE8 Play 0x00007BE9 Rewind 0x00007BEA Forward 0x00007BEB CHANNELDOWN 0x00007BEC CHANNELUP 0x00007BED Volumedown 0x00007BEE Volumeup 0x00007BEF INFO 0x00007BF0 # MORE (i) button Mute 0x00007BF1 MENU 0x00007BF2 # START (Windows) button POWER 0x00007BF3 ENTER 0x00007BF4 CLEAR 0x00007BF5 9 0x00007BF6 8 0x00007BF7 7 0x00007BF8 6 0x00007BF9 5 0x00007BFA 4 0x00007BFB 3 0x00007BFC 2 0x00007BFD 1 0x00007BFE 0 0x00007BFF end codes end remote ~/.lircrc begin prog = mythtv button = Two config = 2 end begin prog = mythtv button = Three config = 3 end begin prog = mythtv button = Four config = 4 end begin prog = mythtv button = Five config = 5 end begin prog = mythtv button = Six config = 6 end begin prog = mythtv button = Seven config = 7 end begin prog = mythtv button = Eight config = 8 end begin prog = mythtv button = Nine config = 9 end == IRblaster == To get the right codes from youre remote you can record it with irrecord. This will provide a configuration file which you can use in lirc #irrecord /tmp/remote.conf Now follow the instructions To get the raw codes #irrecord -f /tmp/remoteraw.conf You wil get this file for a topfield tf6000cok remote # Please make this file available to others # by sending it to <lirc@bartelmus.de> # # this config file was automatically generated # using lirc-0.8.6(default) on Wed Mar 24 20:58:54 2010 # # contributed by # # brand:Topfield # model no. of remote control: TP-014 # devices being controlled by this remote: Topfield TF6000COK # begin remote name topfield flags RAW_CODES|CONST_LENGTH eps 30 aeps 100 gap 107620 begin raw_codes name KEY_1 9000 4450 600 500 650 450 650 1650 600 500 600 500 650 500 600 500 600 500 650 1600 650 1600 600 1650 600 1650 600 1650 600 1650 600 1600 650 1600 600 1650 600 550 600 500 600 500 600 1650 600 550 550 550 600 500 650 500 600 1650 600 1650 600 1600 600 550 600 1650 550 1650 650 1650 550 name KEY_2 9050 4400 600 500 650 500 600 1650 600 500 600 500 650 500 600 500 600 500 650 1650 600 1600 600 1650 600 1650 600 1650 600 1650 600 1650 600 1600 600 550 600 1650 600 500 600 500 650 1600 600 550 600 500 600 550 600 1600 600 550 600 1650 550 1650 650 500 600 1650 600 1650 600 1600 600 name KEY_3 9000 4450 600 500 650 500 600 1600 650 500 600 500 600 550 600 500 600 550 600 1600 600 1650 650 1600 600 1650 600 1650 600 1650 600 1600 600 1650 600 1650 600 1650 600 500 600 550 600 1650 600 500 600 500 600 550 600 500 600 550 600 1600 650 1650 550 550 600 1650 600 1600 600 1650 600 name KEY_4 9050 4450 600 500 600 500 650 1600 600 500 650 500 600 500 650 500 600 500 600 1650 600 1650 600 1650 600 1600 650 1600 650 1600 600 1650 600 1650 600 500 600 550 600 1650 550 550 600 1650 600 500 600 500 650 500 600 1650 600 1650 600 500 600 1650 600 500 650 1600 600 1650 600 1650 600 name KEY_5 9050 4400 650 450 650 500 600 1650 600 500 650 500 600 500 600 500 650 500 600 1650 600 1600 650 1650 600 1600 600 1650 600 1650 600 1650 600 1650 600 1650 600 500 600 1650 600 500 600 1650 600 500 650 500 600 500 600 550 600 1650 600 500 600 1650 600 500 600 1650 600 1650 600 1650 600 name KEY_6 9050 4400 650 500 600 500 600 1650 600 500 650 500 600 500 600 500 650 500 600 1650 600 1650 600 1600 600 1650 600 1650 600 1650 600 1650 600 1650 600 500 600 1650 600 1650 600 500 600 1650 600 550 550 550 600 500 600 1650 600 500 600 550 600 1650 600 500 600 1650 600 1650 600 1650 600 name KEY_7 9000 4450 600 500 600 500 650 1600 650 450 650 500 600 500 650 500 600 500 600 1650 600 1650 600 1650 600 1650 600 1600 650 1600 600 1650 600 1650 600 1650 600 1650 550 1650 650 500 600 1650 600 500 600 550 600 500 600 500 600 550 600 500 600 1650 600 500 650 1600 600 1650 600 1650 600 name KEY_8 9050 4400 650 450 650 500 600 1650 600 500 650 500 600 500 600 500 650 500 600 1650 600 1600 650 1650 550 1650 600 1650 600 1650 600 1650 600 1600 650 500 600 550 550 550 600 1650 600 1650 550 550 600 500 650 500 600 1600 650 1650 550 1650 600 550 600 500 600 1650 600 1650 600 1650 600 name KEY_9 9050 4400 650 500 600 500 600 1650 600 500 650 500 600 500 600 500 650 500 600 1650 600 1650 600 1600 600 1650 650 1600 600 1650 600 1650 600 1650 600 1600 600 550 600 500 600 1650 600 1650 600 550 550 550 600 500 600 550 600 1600 600 1650 600 550 600 500 600 1650 600 1650 600 1650 600 name KEY_0 9000 4450 600 500 650 450 650 1600 650 500 600 500 600 500 650 500 600 550 600 1600 600 1650 600 1650 600 1650 600 1650 600 1650 600 1600 600 1650 600 550 600 500 600 500 650 500 600 1650 600 500 600 550 600 500 600 1650 600 1650 600 1600 650 1650 550 550 600 1650 600 1600 600 1650 600 name KEY_CHANNELUP 9050 4400 650 500 600 500 650 1600 650 500 600 500 600 500 650 500 600 500 650 1600 600 1650 600 1650 600 1650 600 1600 600 1650 650 1600 600 1650 600 1650 600 500 600 1650 600 500 600 1650 650 500 600 1600 650 500 600 550 550 1650 600 550 600 1650 550 550 600 1650 600 500 600 1650 600 name KEY_CHANNELDOWN 9050 4400 650 500 600 500 650 1600 600 500 650 500 600 550 600 500 600 500 600 1650 600 1650 600 1650 600 1600 650 1650 600 1600 600 1650 600 1650 600 500 650 1600 600 1650 600 550 600 1600 600 550 600 1650 550 550 600 1650 600 500 600 550 600 1650 550 550 600 1650 600 500 600 1650 600 name KEY_VOLUMEUP 9050 4400 650 500 600 500 600 1650 600 500 650 500 600 500 600 500 650 500 600 1650 600 1650 600 1600 600 1650 650 1600 600 1650 600 1650 600 1650 600 1600 600 1650 650 1600 600 500 650 1650 550 550 600 1650 600 500 600 500 600 550 600 500 650 1600 600 500 650 1650 550 550 600 1650 600 name KEY_VOLUMEDOWN 9050 4400 650 500 600 550 600 1600 650 500 600 500 600 500 650 500 600 500 650 1600 600 1650 600 1650 600 1650 600 1650 600 1600 650 1600 600 1650 600 550 600 500 600 500 600 1650 600 1650 600 500 650 1600 600 550 600 1650 600 1600 600 1650 600 550 550 550 600 1650 600 500 600 1650 600 end raw_codes end remote Now save this file in /etc/lirc and edit /etc/lirc/lircd.conf include "/etc/lirc/remote.conf" Now we can test irblaster #irsend SEND_ONCE remote KEY_1 The channel on the topfield DVB must jump to channel 1 == EPG == To use the epg we want to grad the data from a source. In this case we use tv_grab_nl_py. This script will grab all data from www.tvgids.nl XMLTV-configuratiebestand aanmaken * Start MythTV Setup * Choose for Video Sources. * Choose for existing or a new video source * Listings grabber: The Netherlands (tv_grab_nl_py...) * Klick Finish On the prompt # tv_grab_nl_py --configure This will create a config file in /homedir/.xmltv/tv_grab_nl_py.conf Edit this config file and clear out all channels you don want (or edit them out) To see is something is happening #mythfilldatabase -v all --refresh-today To see what's in the database *mysql -u mythtv -p mythconverg -e "select chanid, callsign, name, xmltvid from channel;" == Metadata == Make sure you have set the filepaths right. Go to Mythtv setup - 6. Storage Directories Choose (create Fanart group) and choose the right directory Now go to the mythfrontend and choose to watch a video. Select the video and press W. Based on the filename [http://www.mythtv.org/wiki/MythVideo_File_Parsing] the right data will be searched. To configure the metadata yourself you can select the video and press I. Now configure the metadata. 132ed5f269f62d7628f012799f89fe9d6c7715b1 2531 2509 2010-04-05T20:18:41Z Insomnia 3 /* lirc */ wikitext text/x-wiki == lirc == LIRC CVS is hosted at SourceForge. You can get a copy of the current CVS tree using anonymous CVS login. First log in to the cvs server (press <enter> for password): cvs -d:pserver:anonymous@lirc.cvs.sourceforge.net:/cvsroot/lirc login Get the sources: cvs -z8 -d:pserver:anonymous@lirc.cvs.sourceforge.net:/cvsroot/lirc co lirc After initial checkout, you can change into this directory and execute cvs commands without the -d option. For example: cvs update Compile: cd lirc ./autogen.sh ./setup.sh make Lirc will initiate the hardware with the below config file. In this case a mce usb receiver with a ir blaster and also a volume knob (Antec fusion) # /etc/lirc/hardware.conf # #Chosen Remote Control REMOTE="Windows Media Center Transceivers/Remotes (all)" REMOTE_MODULES="lirc_dev lirc_mceusb2" REMOTE_DRIVER="" REMOTE_DEVICE="/dev/lirc1" REMOTE_LIRCD_CONF="mceusb/lircd.conf.mceusb" REMOTE_LIRCD_ARGS="" #Chosen Remote Control REMOTE="Windows Media Center Transceivers/Remotes (all)" REMOTE_MODULES="lirc_dev lirc_imon" REMOTE_DRIVER="" REMOTE_DEVICE="/dev/lirc0" REMOTE_LIRCD_CONF="" REMOTE_LIRCD_ARGS="" #Chosen IR Transmitter TRANSMITTER="Microsoft Windows Media Center V2 (usb) : Direct TV Receiver" TRANSMITTER_MODULES="lirc_dev lirc_mceusb2" TRANSMITTER_DRIVER="" TRANSMITTER_DEVICE="/dev/lirc1" TRANSMITTER_SOCKET="" TRANSMITTER_LIRCD_CONF="" TRANSMITTER_LIRCD_ARGS="" #Enable lircd START_LIRCD="true" #Don't start lircmd even if there seems to be a good config file #START_LIRCMD="false" #Try to load appropriate kernel modules LOAD_MODULES="true" # Default configuration files for your hardware if any LIRCMD_CONF="" FORCE_NONINTERACTIVE_RECONFIGURATION="false" START_LIRCMD="" REMOTE_SOCKET="" /etc/lirc/lircd.conf ################################################################################ # lircd.conf file for the new Microsoft Media Center remote using a new # Microsoft Media Center receiver. ################################################################################ begin remote name mceusb bits 16 flags RC6|CONST_LENGTH eps 30 aeps 100 header 2667 889 one 444 444 zero 444 444 pre_data_bits 21 pre_data 0x37FF0 gap 105000 toggle_bit 22 rc6_mask 0x100000000 begin codes # starts at A1 BLUE 0x00007BA1 YELLOW 0x00007BA2 GREEN 0x00007BA3 RED 0x00007BA4 TELETEXT 0x00007BA5 RADIO 0x00007BAF PRINT 0x00007BB1 VIDEO 0x00007BB5 # VIDEOS button IMAGE 0x00007BB6 # PICTURES button PVR 0x00007BB7 # RECORDED TV button AUDIO 0x00007BB8 # MUSIC button TV 0x00007BB9 # no BA - D8 Guide 0x00007BD9 TV 0x00007BDA # LIVE TV button Dvd 0x00007BDB Back 0x00007BDC OK 0x00007BDD Right 0x00007BDE Left 0x00007BDF Down 0x00007BE0 Up 0x00007BE1 STAR 0x00007BE2 Hash 0x00007BE3 PREVIOUS 0x00007BE4 # REPLAY button Next 0x00007BE5 # SKIP button Stop 0x00007BE6 Pause 0x00007BE7 Record 0x00007BE8 Play 0x00007BE9 Rewind 0x00007BEA Forward 0x00007BEB CHANNELDOWN 0x00007BEC CHANNELUP 0x00007BED Volumedown 0x00007BEE Volumeup 0x00007BEF INFO 0x00007BF0 # MORE (i) button Mute 0x00007BF1 MENU 0x00007BF2 # START (Windows) button POWER 0x00007BF3 ENTER 0x00007BF4 CLEAR 0x00007BF5 9 0x00007BF6 8 0x00007BF7 7 0x00007BF8 6 0x00007BF9 5 0x00007BFA 4 0x00007BFB 3 0x00007BFC 2 0x00007BFD 1 0x00007BFE 0 0x00007BFF end codes end remote Whit this config file lirc will listen on the devices and will translate the input. It will give a hardware name for the device and the button pressed. irw wil give you a xample on the commandline #irw Now press some buttons To feed the command to the appropiate program (if this program supports lirc) make a config in the home dir of the user. ~/.lircrc begin prog = mythtv button = Two config = 2 end begin prog = mythtv button = Three config = 3 end begin prog = mythtv button = Four config = 4 end begin prog = mythtv button = Five config = 5 end begin prog = mythtv button = Six config = 6 end begin prog = mythtv button = Seven config = 7 end begin prog = mythtv button = Eight config = 8 end begin prog = mythtv button = Nine config = 9 end == IRblaster == To get the right codes from youre remote you can record it with irrecord. This will provide a configuration file which you can use in lirc #irrecord /tmp/remote.conf Now follow the instructions To get the raw codes #irrecord -f /tmp/remoteraw.conf You wil get this file for a topfield tf6000cok remote # Please make this file available to others # by sending it to <lirc@bartelmus.de> # # this config file was automatically generated # using lirc-0.8.6(default) on Wed Mar 24 20:58:54 2010 # # contributed by # # brand:Topfield # model no. of remote control: TP-014 # devices being controlled by this remote: Topfield TF6000COK # begin remote name topfield flags RAW_CODES|CONST_LENGTH eps 30 aeps 100 gap 107620 begin raw_codes name KEY_1 9000 4450 600 500 650 450 650 1650 600 500 600 500 650 500 600 500 600 500 650 1600 650 1600 600 1650 600 1650 600 1650 600 1650 600 1600 650 1600 600 1650 600 550 600 500 600 500 600 1650 600 550 550 550 600 500 650 500 600 1650 600 1650 600 1600 600 550 600 1650 550 1650 650 1650 550 name KEY_2 9050 4400 600 500 650 500 600 1650 600 500 600 500 650 500 600 500 600 500 650 1650 600 1600 600 1650 600 1650 600 1650 600 1650 600 1650 600 1600 600 550 600 1650 600 500 600 500 650 1600 600 550 600 500 600 550 600 1600 600 550 600 1650 550 1650 650 500 600 1650 600 1650 600 1600 600 name KEY_3 9000 4450 600 500 650 500 600 1600 650 500 600 500 600 550 600 500 600 550 600 1600 600 1650 650 1600 600 1650 600 1650 600 1650 600 1600 600 1650 600 1650 600 1650 600 500 600 550 600 1650 600 500 600 500 600 550 600 500 600 550 600 1600 650 1650 550 550 600 1650 600 1600 600 1650 600 name KEY_4 9050 4450 600 500 600 500 650 1600 600 500 650 500 600 500 650 500 600 500 600 1650 600 1650 600 1650 600 1600 650 1600 650 1600 600 1650 600 1650 600 500 600 550 600 1650 550 550 600 1650 600 500 600 500 650 500 600 1650 600 1650 600 500 600 1650 600 500 650 1600 600 1650 600 1650 600 name KEY_5 9050 4400 650 450 650 500 600 1650 600 500 650 500 600 500 600 500 650 500 600 1650 600 1600 650 1650 600 1600 600 1650 600 1650 600 1650 600 1650 600 1650 600 500 600 1650 600 500 600 1650 600 500 650 500 600 500 600 550 600 1650 600 500 600 1650 600 500 600 1650 600 1650 600 1650 600 name KEY_6 9050 4400 650 500 600 500 600 1650 600 500 650 500 600 500 600 500 650 500 600 1650 600 1650 600 1600 600 1650 600 1650 600 1650 600 1650 600 1650 600 500 600 1650 600 1650 600 500 600 1650 600 550 550 550 600 500 600 1650 600 500 600 550 600 1650 600 500 600 1650 600 1650 600 1650 600 name KEY_7 9000 4450 600 500 600 500 650 1600 650 450 650 500 600 500 650 500 600 500 600 1650 600 1650 600 1650 600 1650 600 1600 650 1600 600 1650 600 1650 600 1650 600 1650 550 1650 650 500 600 1650 600 500 600 550 600 500 600 500 600 550 600 500 600 1650 600 500 650 1600 600 1650 600 1650 600 name KEY_8 9050 4400 650 450 650 500 600 1650 600 500 650 500 600 500 600 500 650 500 600 1650 600 1600 650 1650 550 1650 600 1650 600 1650 600 1650 600 1600 650 500 600 550 550 550 600 1650 600 1650 550 550 600 500 650 500 600 1600 650 1650 550 1650 600 550 600 500 600 1650 600 1650 600 1650 600 name KEY_9 9050 4400 650 500 600 500 600 1650 600 500 650 500 600 500 600 500 650 500 600 1650 600 1650 600 1600 600 1650 650 1600 600 1650 600 1650 600 1650 600 1600 600 550 600 500 600 1650 600 1650 600 550 550 550 600 500 600 550 600 1600 600 1650 600 550 600 500 600 1650 600 1650 600 1650 600 name KEY_0 9000 4450 600 500 650 450 650 1600 650 500 600 500 600 500 650 500 600 550 600 1600 600 1650 600 1650 600 1650 600 1650 600 1650 600 1600 600 1650 600 550 600 500 600 500 650 500 600 1650 600 500 600 550 600 500 600 1650 600 1650 600 1600 650 1650 550 550 600 1650 600 1600 600 1650 600 name KEY_CHANNELUP 9050 4400 650 500 600 500 650 1600 650 500 600 500 600 500 650 500 600 500 650 1600 600 1650 600 1650 600 1650 600 1600 600 1650 650 1600 600 1650 600 1650 600 500 600 1650 600 500 600 1650 650 500 600 1600 650 500 600 550 550 1650 600 550 600 1650 550 550 600 1650 600 500 600 1650 600 name KEY_CHANNELDOWN 9050 4400 650 500 600 500 650 1600 600 500 650 500 600 550 600 500 600 500 600 1650 600 1650 600 1650 600 1600 650 1650 600 1600 600 1650 600 1650 600 500 650 1600 600 1650 600 550 600 1600 600 550 600 1650 550 550 600 1650 600 500 600 550 600 1650 550 550 600 1650 600 500 600 1650 600 name KEY_VOLUMEUP 9050 4400 650 500 600 500 600 1650 600 500 650 500 600 500 600 500 650 500 600 1650 600 1650 600 1600 600 1650 650 1600 600 1650 600 1650 600 1650 600 1600 600 1650 650 1600 600 500 650 1650 550 550 600 1650 600 500 600 500 600 550 600 500 650 1600 600 500 650 1650 550 550 600 1650 600 name KEY_VOLUMEDOWN 9050 4400 650 500 600 550 600 1600 650 500 600 500 600 500 650 500 600 500 650 1600 600 1650 600 1650 600 1650 600 1650 600 1600 650 1600 600 1650 600 550 600 500 600 500 600 1650 600 1650 600 500 650 1600 600 550 600 1650 600 1600 600 1650 600 550 550 550 600 1650 600 500 600 1650 600 end raw_codes end remote Now save this file in /etc/lirc and edit /etc/lirc/lircd.conf include "/etc/lirc/remote.conf" Now we can test irblaster #irsend SEND_ONCE remote KEY_1 The channel on the topfield DVB must jump to channel 1 == EPG == To use the epg we want to grad the data from a source. In this case we use tv_grab_nl_py. This script will grab all data from www.tvgids.nl XMLTV-configuratiebestand aanmaken * Start MythTV Setup * Choose for Video Sources. * Choose for existing or a new video source * Listings grabber: The Netherlands (tv_grab_nl_py...) * Klick Finish On the prompt # tv_grab_nl_py --configure This will create a config file in /homedir/.xmltv/tv_grab_nl_py.conf Edit this config file and clear out all channels you don want (or edit them out) To see is something is happening #mythfilldatabase -v all --refresh-today To see what's in the database *mysql -u mythtv -p mythconverg -e "select chanid, callsign, name, xmltvid from channel;" == Metadata == Make sure you have set the filepaths right. Go to Mythtv setup - 6. Storage Directories Choose (create Fanart group) and choose the right directory Now go to the mythfrontend and choose to watch a video. Select the video and press W. Based on the filename [http://www.mythtv.org/wiki/MythVideo_File_Parsing] the right data will be searched. To configure the metadata yourself you can select the video and press I. Now configure the metadata. d03c16c0c9dd41ac750cd754fbe99b7b4660a581 2532 2531 2010-04-05T20:24:00Z Insomnia 3 /* lirc */ wikitext text/x-wiki == lirc == LIRC CVS is hosted at SourceForge. You can get a copy of the current CVS tree using anonymous CVS login. First log in to the cvs server (press <enter> for password): cvs -d:pserver:anonymous@lirc.cvs.sourceforge.net:/cvsroot/lirc login Get the sources: cvs -z8 -d:pserver:anonymous@lirc.cvs.sourceforge.net:/cvsroot/lirc co lirc After initial checkout, you can change into this directory and execute cvs commands without the -d option. For example: cvs update Compile: cd lirc ./autogen.sh ./setup.sh make Lirc will initiate the hardware with the below config file. In this case a mce usb receiver with a ir blaster and also a volume knob (Antec fusion) # /etc/lirc/hardware.conf # #Chosen Remote Control REMOTE="Windows Media Center Transceivers/Remotes (all)" REMOTE_MODULES="lirc_dev lirc_mceusb2" REMOTE_DRIVER="" REMOTE_DEVICE="/dev/lirc1" REMOTE_LIRCD_CONF="mceusb/lircd.conf.mceusb" REMOTE_LIRCD_ARGS="" #Chosen Remote Control REMOTE="Windows Media Center Transceivers/Remotes (all)" REMOTE_MODULES="lirc_dev lirc_imon" REMOTE_DRIVER="" REMOTE_DEVICE="/dev/lirc0" REMOTE_LIRCD_CONF="" REMOTE_LIRCD_ARGS="" #Chosen IR Transmitter TRANSMITTER="Microsoft Windows Media Center V2 (usb) : Direct TV Receiver" TRANSMITTER_MODULES="lirc_dev lirc_mceusb2" TRANSMITTER_DRIVER="" TRANSMITTER_DEVICE="/dev/lirc1" TRANSMITTER_SOCKET="" TRANSMITTER_LIRCD_CONF="" TRANSMITTER_LIRCD_ARGS="" #Enable lircd START_LIRCD="true" #Don't start lircmd even if there seems to be a good config file #START_LIRCMD="false" #Try to load appropriate kernel modules LOAD_MODULES="true" # Default configuration files for your hardware if any LIRCMD_CONF="" FORCE_NONINTERACTIVE_RECONFIGURATION="false" START_LIRCMD="" REMOTE_SOCKET="" /etc/lirc/lircd.conf ################################################################################ # lircd.conf file for the new Microsoft Media Center remote using a new # Microsoft Media Center receiver. ################################################################################ begin remote name mceusb bits 16 flags RC6|CONST_LENGTH eps 30 aeps 100 header 2667 889 one 444 444 zero 444 444 pre_data_bits 21 pre_data 0x37FF0 gap 105000 toggle_bit 22 rc6_mask 0x100000000 begin codes # starts at A1 BLUE 0x00007BA1 YELLOW 0x00007BA2 GREEN 0x00007BA3 RED 0x00007BA4 TELETEXT 0x00007BA5 RADIO 0x00007BAF PRINT 0x00007BB1 VIDEO 0x00007BB5 # VIDEOS button IMAGE 0x00007BB6 # PICTURES button PVR 0x00007BB7 # RECORDED TV button AUDIO 0x00007BB8 # MUSIC button TV 0x00007BB9 # no BA - D8 Guide 0x00007BD9 TV 0x00007BDA # LIVE TV button Dvd 0x00007BDB Back 0x00007BDC OK 0x00007BDD Right 0x00007BDE Left 0x00007BDF Down 0x00007BE0 Up 0x00007BE1 STAR 0x00007BE2 Hash 0x00007BE3 PREVIOUS 0x00007BE4 # REPLAY button Next 0x00007BE5 # SKIP button Stop 0x00007BE6 Pause 0x00007BE7 Record 0x00007BE8 Play 0x00007BE9 Rewind 0x00007BEA Forward 0x00007BEB CHANNELDOWN 0x00007BEC CHANNELUP 0x00007BED Volumedown 0x00007BEE Volumeup 0x00007BEF INFO 0x00007BF0 # MORE (i) button Mute 0x00007BF1 MENU 0x00007BF2 # START (Windows) button POWER 0x00007BF3 ENTER 0x00007BF4 CLEAR 0x00007BF5 9 0x00007BF6 8 0x00007BF7 7 0x00007BF8 6 0x00007BF9 5 0x00007BFA 4 0x00007BFB 3 0x00007BFC 2 0x00007BFD 1 0x00007BFE 0 0x00007BFF end codes end remote Whit this config file lirc will listen on the devices and will translate the input. It will give a hardware name for the device and the button pressed. irw wil give you a xample on the commandline #irw Now press some buttons To feed the command to the appropiate program (if this program supports lirc) make a config in the home dir of the user. ~/.lirc/mythtv begin remote = ClickWheel prog = mythtv button = KEY_VOLUMEUP config = ] repeat = 0 delay = 0 end begin remote = ClickWheel prog = mythtv button = KEY_VOLUMEDOWN config = [ repeat = 0 delay = 0 end == IRblaster == To get the right codes from youre remote you can record it with irrecord. This will provide a configuration file which you can use in lirc #irrecord /tmp/remote.conf Now follow the instructions To get the raw codes #irrecord -f /tmp/remoteraw.conf You wil get this file for a topfield tf6000cok remote # Please make this file available to others # by sending it to <lirc@bartelmus.de> # # this config file was automatically generated # using lirc-0.8.6(default) on Wed Mar 24 20:58:54 2010 # # contributed by # # brand:Topfield # model no. of remote control: TP-014 # devices being controlled by this remote: Topfield TF6000COK # begin remote name topfield flags RAW_CODES|CONST_LENGTH eps 30 aeps 100 gap 107620 begin raw_codes name KEY_1 9000 4450 600 500 650 450 650 1650 600 500 600 500 650 500 600 500 600 500 650 1600 650 1600 600 1650 600 1650 600 1650 600 1650 600 1600 650 1600 600 1650 600 550 600 500 600 500 600 1650 600 550 550 550 600 500 650 500 600 1650 600 1650 600 1600 600 550 600 1650 550 1650 650 1650 550 name KEY_2 9050 4400 600 500 650 500 600 1650 600 500 600 500 650 500 600 500 600 500 650 1650 600 1600 600 1650 600 1650 600 1650 600 1650 600 1650 600 1600 600 550 600 1650 600 500 600 500 650 1600 600 550 600 500 600 550 600 1600 600 550 600 1650 550 1650 650 500 600 1650 600 1650 600 1600 600 name KEY_3 9000 4450 600 500 650 500 600 1600 650 500 600 500 600 550 600 500 600 550 600 1600 600 1650 650 1600 600 1650 600 1650 600 1650 600 1600 600 1650 600 1650 600 1650 600 500 600 550 600 1650 600 500 600 500 600 550 600 500 600 550 600 1600 650 1650 550 550 600 1650 600 1600 600 1650 600 name KEY_4 9050 4450 600 500 600 500 650 1600 600 500 650 500 600 500 650 500 600 500 600 1650 600 1650 600 1650 600 1600 650 1600 650 1600 600 1650 600 1650 600 500 600 550 600 1650 550 550 600 1650 600 500 600 500 650 500 600 1650 600 1650 600 500 600 1650 600 500 650 1600 600 1650 600 1650 600 name KEY_5 9050 4400 650 450 650 500 600 1650 600 500 650 500 600 500 600 500 650 500 600 1650 600 1600 650 1650 600 1600 600 1650 600 1650 600 1650 600 1650 600 1650 600 500 600 1650 600 500 600 1650 600 500 650 500 600 500 600 550 600 1650 600 500 600 1650 600 500 600 1650 600 1650 600 1650 600 name KEY_6 9050 4400 650 500 600 500 600 1650 600 500 650 500 600 500 600 500 650 500 600 1650 600 1650 600 1600 600 1650 600 1650 600 1650 600 1650 600 1650 600 500 600 1650 600 1650 600 500 600 1650 600 550 550 550 600 500 600 1650 600 500 600 550 600 1650 600 500 600 1650 600 1650 600 1650 600 name KEY_7 9000 4450 600 500 600 500 650 1600 650 450 650 500 600 500 650 500 600 500 600 1650 600 1650 600 1650 600 1650 600 1600 650 1600 600 1650 600 1650 600 1650 600 1650 550 1650 650 500 600 1650 600 500 600 550 600 500 600 500 600 550 600 500 600 1650 600 500 650 1600 600 1650 600 1650 600 name KEY_8 9050 4400 650 450 650 500 600 1650 600 500 650 500 600 500 600 500 650 500 600 1650 600 1600 650 1650 550 1650 600 1650 600 1650 600 1650 600 1600 650 500 600 550 550 550 600 1650 600 1650 550 550 600 500 650 500 600 1600 650 1650 550 1650 600 550 600 500 600 1650 600 1650 600 1650 600 name KEY_9 9050 4400 650 500 600 500 600 1650 600 500 650 500 600 500 600 500 650 500 600 1650 600 1650 600 1600 600 1650 650 1600 600 1650 600 1650 600 1650 600 1600 600 550 600 500 600 1650 600 1650 600 550 550 550 600 500 600 550 600 1600 600 1650 600 550 600 500 600 1650 600 1650 600 1650 600 name KEY_0 9000 4450 600 500 650 450 650 1600 650 500 600 500 600 500 650 500 600 550 600 1600 600 1650 600 1650 600 1650 600 1650 600 1650 600 1600 600 1650 600 550 600 500 600 500 650 500 600 1650 600 500 600 550 600 500 600 1650 600 1650 600 1600 650 1650 550 550 600 1650 600 1600 600 1650 600 name KEY_CHANNELUP 9050 4400 650 500 600 500 650 1600 650 500 600 500 600 500 650 500 600 500 650 1600 600 1650 600 1650 600 1650 600 1600 600 1650 650 1600 600 1650 600 1650 600 500 600 1650 600 500 600 1650 650 500 600 1600 650 500 600 550 550 1650 600 550 600 1650 550 550 600 1650 600 500 600 1650 600 name KEY_CHANNELDOWN 9050 4400 650 500 600 500 650 1600 600 500 650 500 600 550 600 500 600 500 600 1650 600 1650 600 1650 600 1600 650 1650 600 1600 600 1650 600 1650 600 500 650 1600 600 1650 600 550 600 1600 600 550 600 1650 550 550 600 1650 600 500 600 550 600 1650 550 550 600 1650 600 500 600 1650 600 name KEY_VOLUMEUP 9050 4400 650 500 600 500 600 1650 600 500 650 500 600 500 600 500 650 500 600 1650 600 1650 600 1600 600 1650 650 1600 600 1650 600 1650 600 1650 600 1600 600 1650 650 1600 600 500 650 1650 550 550 600 1650 600 500 600 500 600 550 600 500 650 1600 600 500 650 1650 550 550 600 1650 600 name KEY_VOLUMEDOWN 9050 4400 650 500 600 550 600 1600 650 500 600 500 600 500 650 500 600 500 650 1600 600 1650 600 1650 600 1650 600 1650 600 1600 650 1600 600 1650 600 550 600 500 600 500 600 1650 600 1650 600 500 650 1600 600 550 600 1650 600 1600 600 1650 600 550 550 550 600 1650 600 500 600 1650 600 end raw_codes end remote Now save this file in /etc/lirc and edit /etc/lirc/lircd.conf include "/etc/lirc/remote.conf" Now we can test irblaster #irsend SEND_ONCE remote KEY_1 The channel on the topfield DVB must jump to channel 1 == EPG == To use the epg we want to grad the data from a source. In this case we use tv_grab_nl_py. This script will grab all data from www.tvgids.nl XMLTV-configuratiebestand aanmaken * Start MythTV Setup * Choose for Video Sources. * Choose for existing or a new video source * Listings grabber: The Netherlands (tv_grab_nl_py...) * Klick Finish On the prompt # tv_grab_nl_py --configure This will create a config file in /homedir/.xmltv/tv_grab_nl_py.conf Edit this config file and clear out all channels you don want (or edit them out) To see is something is happening #mythfilldatabase -v all --refresh-today To see what's in the database *mysql -u mythtv -p mythconverg -e "select chanid, callsign, name, xmltvid from channel;" == Metadata == Make sure you have set the filepaths right. Go to Mythtv setup - 6. Storage Directories Choose (create Fanart group) and choose the right directory Now go to the mythfrontend and choose to watch a video. Select the video and press W. Based on the filename [http://www.mythtv.org/wiki/MythVideo_File_Parsing] the right data will be searched. To configure the metadata yourself you can select the video and press I. Now configure the metadata. 99f86a45726330fd5018a7bc9cbbfcc14328d193 2533 2532 2010-04-05T20:29:25Z Insomnia 3 /* lirc */ lirc init wikitext text/x-wiki == lirc == LIRC CVS is hosted at SourceForge. You can get a copy of the current CVS tree using anonymous CVS login. First log in to the cvs server (press <enter> for password): cvs -d:pserver:anonymous@lirc.cvs.sourceforge.net:/cvsroot/lirc login Get the sources: cvs -z8 -d:pserver:anonymous@lirc.cvs.sourceforge.net:/cvsroot/lirc co lirc After initial checkout, you can change into this directory and execute cvs commands without the -d option. For example: cvs update Compile: cd lirc ./autogen.sh ./setup.sh make Lirc will initiate the hardware with the below config file. In this case a mce usb receiver with a ir blaster and also a volume knob (Antec fusion) # /etc/lirc/hardware.conf # #Chosen Remote Control REMOTE="Windows Media Center Transceivers/Remotes (all)" REMOTE_MODULES="lirc_dev lirc_mceusb2" REMOTE_DRIVER="" REMOTE_DEVICE="/dev/lirc1" REMOTE_LIRCD_CONF="mceusb/lircd.conf.mceusb" REMOTE_LIRCD_ARGS="" #Chosen Remote Control REMOTE="Windows Media Center Transceivers/Remotes (all)" REMOTE_MODULES="lirc_dev lirc_imon" REMOTE_DRIVER="" REMOTE_DEVICE="/dev/lirc0" REMOTE_LIRCD_CONF="" REMOTE_LIRCD_ARGS="" #Chosen IR Transmitter TRANSMITTER="Microsoft Windows Media Center V2 (usb) : Direct TV Receiver" TRANSMITTER_MODULES="lirc_dev lirc_mceusb2" TRANSMITTER_DRIVER="" TRANSMITTER_DEVICE="/dev/lirc1" TRANSMITTER_SOCKET="" TRANSMITTER_LIRCD_CONF="" TRANSMITTER_LIRCD_ARGS="" #Enable lircd START_LIRCD="true" #Don't start lircmd even if there seems to be a good config file #START_LIRCMD="false" #Try to load appropriate kernel modules LOAD_MODULES="true" # Default configuration files for your hardware if any LIRCMD_CONF="" FORCE_NONINTERACTIVE_RECONFIGURATION="false" START_LIRCMD="" REMOTE_SOCKET="" /etc/lirc/lircd.conf ################################################################################ # lircd.conf file for the new Microsoft Media Center remote using a new # Microsoft Media Center receiver. ################################################################################ begin remote name mceusb bits 16 flags RC6|CONST_LENGTH eps 30 aeps 100 header 2667 889 one 444 444 zero 444 444 pre_data_bits 21 pre_data 0x37FF0 gap 105000 toggle_bit 22 rc6_mask 0x100000000 begin codes # starts at A1 BLUE 0x00007BA1 YELLOW 0x00007BA2 GREEN 0x00007BA3 RED 0x00007BA4 TELETEXT 0x00007BA5 RADIO 0x00007BAF PRINT 0x00007BB1 VIDEO 0x00007BB5 # VIDEOS button IMAGE 0x00007BB6 # PICTURES button PVR 0x00007BB7 # RECORDED TV button AUDIO 0x00007BB8 # MUSIC button TV 0x00007BB9 # no BA - D8 Guide 0x00007BD9 TV 0x00007BDA # LIVE TV button Dvd 0x00007BDB Back 0x00007BDC OK 0x00007BDD Right 0x00007BDE Left 0x00007BDF Down 0x00007BE0 Up 0x00007BE1 STAR 0x00007BE2 Hash 0x00007BE3 PREVIOUS 0x00007BE4 # REPLAY button Next 0x00007BE5 # SKIP button Stop 0x00007BE6 Pause 0x00007BE7 Record 0x00007BE8 Play 0x00007BE9 Rewind 0x00007BEA Forward 0x00007BEB CHANNELDOWN 0x00007BEC CHANNELUP 0x00007BED Volumedown 0x00007BEE Volumeup 0x00007BEF INFO 0x00007BF0 # MORE (i) button Mute 0x00007BF1 MENU 0x00007BF2 # START (Windows) button POWER 0x00007BF3 ENTER 0x00007BF4 CLEAR 0x00007BF5 9 0x00007BF6 8 0x00007BF7 7 0x00007BF8 6 0x00007BF9 5 0x00007BFA 4 0x00007BFB 3 0x00007BFC 2 0x00007BFD 1 0x00007BFE 0 0x00007BFF end codes end remote Whit this config file lirc will listen on the devices and will translate the input. It will give a hardware name for the device and the button pressed. irw wil give you a xample on the commandline #irw Now press some buttons To feed the command to the appropiate program (if this program supports lirc) make a config in the home dir of the user. ~/.lirc/mythtv begin remote = ClickWheel prog = mythtv button = KEY_VOLUMEUP config = ] repeat = 0 delay = 0 end begin remote = ClickWheel prog = mythtv button = KEY_VOLUMEDOWN config = [ repeat = 0 delay = 0 end And the final piece of the puzzle and this was the hardest to find but the most simple thing to do. It seems that Lirc has it all figured out for the newest version on how to run multiple devices without major manual configuration EXCEPT the Lirc init.d script. With my devices plugged in and issuing an ls -l /dev/lirc* I had all the devices I needed with manual configuration so Code: crw-rw---- 1 root root 61, 0 2010-02-21 11:44 /dev/lirc0 crw-rw---- 1 root root 61, 1 2010-02-21 11:44 /dev/lirc1 lrwxrwxrwx 1 root root 19 2010-02-21 11:44 /dev/lircd -> /var/run/lirc/lircd lrwxrwxrwx 1 root root 20 2010-02-21 11:44 /dev/lircd1 -> /var/run/lirc/lircd SEE the problem - /dev/lircd1 was pointing to /var/run/lirc/lircd so when issuing an irsend command from a script or a command line I was getting the hardware cannot send error. The actual fix I finally found in another post - THANK YOU TO cyber_source - YOU ARE A LIFE SAVER. You need to edit your /etc/init.d/lirc startup script and change a couple lines First Line 83 Needs to be changed from "${TRANSMITTER_SOCKET}1" to this - "${TRANSMITTER_SOCKET}" and then line 131 Needs to be changed from TRANSMITTER_SOCKET="/var/run/lirc/lircd" to this TRANSMITTER_SOCKET="/var/run/lirc/lircd1" save and exit the file reboot your system and run another ls -l /dev/lirc* and you should see Code: crw-rw---- 1 root root 61, 0 2010-02-21 11:44 /dev/lirc0 crw-rw---- 1 root root 61, 1 2010-02-21 11:44 /dev/lirc1 lrwxrwxrwx 1 root root 19 2010-02-21 11:44 /dev/lircd -> /var/run/lirc/lircd lrwxrwxrwx 1 root root 20 2010-02-21 11:44 /dev/lircd1 -> /var/run/lirc/lircd1 == IRblaster == To get the right codes from youre remote you can record it with irrecord. This will provide a configuration file which you can use in lirc #irrecord /tmp/remote.conf Now follow the instructions To get the raw codes #irrecord -f /tmp/remoteraw.conf You wil get this file for a topfield tf6000cok remote # Please make this file available to others # by sending it to <lirc@bartelmus.de> # # this config file was automatically generated # using lirc-0.8.6(default) on Wed Mar 24 20:58:54 2010 # # contributed by # # brand:Topfield # model no. of remote control: TP-014 # devices being controlled by this remote: Topfield TF6000COK # begin remote name topfield flags RAW_CODES|CONST_LENGTH eps 30 aeps 100 gap 107620 begin raw_codes name KEY_1 9000 4450 600 500 650 450 650 1650 600 500 600 500 650 500 600 500 600 500 650 1600 650 1600 600 1650 600 1650 600 1650 600 1650 600 1600 650 1600 600 1650 600 550 600 500 600 500 600 1650 600 550 550 550 600 500 650 500 600 1650 600 1650 600 1600 600 550 600 1650 550 1650 650 1650 550 name KEY_2 9050 4400 600 500 650 500 600 1650 600 500 600 500 650 500 600 500 600 500 650 1650 600 1600 600 1650 600 1650 600 1650 600 1650 600 1650 600 1600 600 550 600 1650 600 500 600 500 650 1600 600 550 600 500 600 550 600 1600 600 550 600 1650 550 1650 650 500 600 1650 600 1650 600 1600 600 name KEY_3 9000 4450 600 500 650 500 600 1600 650 500 600 500 600 550 600 500 600 550 600 1600 600 1650 650 1600 600 1650 600 1650 600 1650 600 1600 600 1650 600 1650 600 1650 600 500 600 550 600 1650 600 500 600 500 600 550 600 500 600 550 600 1600 650 1650 550 550 600 1650 600 1600 600 1650 600 name KEY_4 9050 4450 600 500 600 500 650 1600 600 500 650 500 600 500 650 500 600 500 600 1650 600 1650 600 1650 600 1600 650 1600 650 1600 600 1650 600 1650 600 500 600 550 600 1650 550 550 600 1650 600 500 600 500 650 500 600 1650 600 1650 600 500 600 1650 600 500 650 1600 600 1650 600 1650 600 name KEY_5 9050 4400 650 450 650 500 600 1650 600 500 650 500 600 500 600 500 650 500 600 1650 600 1600 650 1650 600 1600 600 1650 600 1650 600 1650 600 1650 600 1650 600 500 600 1650 600 500 600 1650 600 500 650 500 600 500 600 550 600 1650 600 500 600 1650 600 500 600 1650 600 1650 600 1650 600 name KEY_6 9050 4400 650 500 600 500 600 1650 600 500 650 500 600 500 600 500 650 500 600 1650 600 1650 600 1600 600 1650 600 1650 600 1650 600 1650 600 1650 600 500 600 1650 600 1650 600 500 600 1650 600 550 550 550 600 500 600 1650 600 500 600 550 600 1650 600 500 600 1650 600 1650 600 1650 600 name KEY_7 9000 4450 600 500 600 500 650 1600 650 450 650 500 600 500 650 500 600 500 600 1650 600 1650 600 1650 600 1650 600 1600 650 1600 600 1650 600 1650 600 1650 600 1650 550 1650 650 500 600 1650 600 500 600 550 600 500 600 500 600 550 600 500 600 1650 600 500 650 1600 600 1650 600 1650 600 name KEY_8 9050 4400 650 450 650 500 600 1650 600 500 650 500 600 500 600 500 650 500 600 1650 600 1600 650 1650 550 1650 600 1650 600 1650 600 1650 600 1600 650 500 600 550 550 550 600 1650 600 1650 550 550 600 500 650 500 600 1600 650 1650 550 1650 600 550 600 500 600 1650 600 1650 600 1650 600 name KEY_9 9050 4400 650 500 600 500 600 1650 600 500 650 500 600 500 600 500 650 500 600 1650 600 1650 600 1600 600 1650 650 1600 600 1650 600 1650 600 1650 600 1600 600 550 600 500 600 1650 600 1650 600 550 550 550 600 500 600 550 600 1600 600 1650 600 550 600 500 600 1650 600 1650 600 1650 600 name KEY_0 9000 4450 600 500 650 450 650 1600 650 500 600 500 600 500 650 500 600 550 600 1600 600 1650 600 1650 600 1650 600 1650 600 1650 600 1600 600 1650 600 550 600 500 600 500 650 500 600 1650 600 500 600 550 600 500 600 1650 600 1650 600 1600 650 1650 550 550 600 1650 600 1600 600 1650 600 name KEY_CHANNELUP 9050 4400 650 500 600 500 650 1600 650 500 600 500 600 500 650 500 600 500 650 1600 600 1650 600 1650 600 1650 600 1600 600 1650 650 1600 600 1650 600 1650 600 500 600 1650 600 500 600 1650 650 500 600 1600 650 500 600 550 550 1650 600 550 600 1650 550 550 600 1650 600 500 600 1650 600 name KEY_CHANNELDOWN 9050 4400 650 500 600 500 650 1600 600 500 650 500 600 550 600 500 600 500 600 1650 600 1650 600 1650 600 1600 650 1650 600 1600 600 1650 600 1650 600 500 650 1600 600 1650 600 550 600 1600 600 550 600 1650 550 550 600 1650 600 500 600 550 600 1650 550 550 600 1650 600 500 600 1650 600 name KEY_VOLUMEUP 9050 4400 650 500 600 500 600 1650 600 500 650 500 600 500 600 500 650 500 600 1650 600 1650 600 1600 600 1650 650 1600 600 1650 600 1650 600 1650 600 1600 600 1650 650 1600 600 500 650 1650 550 550 600 1650 600 500 600 500 600 550 600 500 650 1600 600 500 650 1650 550 550 600 1650 600 name KEY_VOLUMEDOWN 9050 4400 650 500 600 550 600 1600 650 500 600 500 600 500 650 500 600 500 650 1600 600 1650 600 1650 600 1650 600 1650 600 1600 650 1600 600 1650 600 550 600 500 600 500 600 1650 600 1650 600 500 650 1600 600 550 600 1650 600 1600 600 1650 600 550 550 550 600 1650 600 500 600 1650 600 end raw_codes end remote Now save this file in /etc/lirc and edit /etc/lirc/lircd.conf include "/etc/lirc/remote.conf" Now we can test irblaster #irsend SEND_ONCE remote KEY_1 The channel on the topfield DVB must jump to channel 1 == EPG == To use the epg we want to grad the data from a source. In this case we use tv_grab_nl_py. This script will grab all data from www.tvgids.nl XMLTV-configuratiebestand aanmaken * Start MythTV Setup * Choose for Video Sources. * Choose for existing or a new video source * Listings grabber: The Netherlands (tv_grab_nl_py...) * Klick Finish On the prompt # tv_grab_nl_py --configure This will create a config file in /homedir/.xmltv/tv_grab_nl_py.conf Edit this config file and clear out all channels you don want (or edit them out) To see is something is happening #mythfilldatabase -v all --refresh-today To see what's in the database *mysql -u mythtv -p mythconverg -e "select chanid, callsign, name, xmltvid from channel;" == Metadata == Make sure you have set the filepaths right. Go to Mythtv setup - 6. Storage Directories Choose (create Fanart group) and choose the right directory Now go to the mythfrontend and choose to watch a video. Select the video and press W. Based on the filename [http://www.mythtv.org/wiki/MythVideo_File_Parsing] the right data will be searched. To configure the metadata yourself you can select the video and press I. Now configure the metadata. b59682598e130c3ebf636789dd2a8aa55c70fc9c 2562 2533 2010-04-23T08:14:14Z Insomnia 3 /* Metadata */ vlc wikitext text/x-wiki == lirc == LIRC CVS is hosted at SourceForge. You can get a copy of the current CVS tree using anonymous CVS login. First log in to the cvs server (press <enter> for password): cvs -d:pserver:anonymous@lirc.cvs.sourceforge.net:/cvsroot/lirc login Get the sources: cvs -z8 -d:pserver:anonymous@lirc.cvs.sourceforge.net:/cvsroot/lirc co lirc After initial checkout, you can change into this directory and execute cvs commands without the -d option. For example: cvs update Compile: cd lirc ./autogen.sh ./setup.sh make Lirc will initiate the hardware with the below config file. In this case a mce usb receiver with a ir blaster and also a volume knob (Antec fusion) # /etc/lirc/hardware.conf # #Chosen Remote Control REMOTE="Windows Media Center Transceivers/Remotes (all)" REMOTE_MODULES="lirc_dev lirc_mceusb2" REMOTE_DRIVER="" REMOTE_DEVICE="/dev/lirc1" REMOTE_LIRCD_CONF="mceusb/lircd.conf.mceusb" REMOTE_LIRCD_ARGS="" #Chosen Remote Control REMOTE="Windows Media Center Transceivers/Remotes (all)" REMOTE_MODULES="lirc_dev lirc_imon" REMOTE_DRIVER="" REMOTE_DEVICE="/dev/lirc0" REMOTE_LIRCD_CONF="" REMOTE_LIRCD_ARGS="" #Chosen IR Transmitter TRANSMITTER="Microsoft Windows Media Center V2 (usb) : Direct TV Receiver" TRANSMITTER_MODULES="lirc_dev lirc_mceusb2" TRANSMITTER_DRIVER="" TRANSMITTER_DEVICE="/dev/lirc1" TRANSMITTER_SOCKET="" TRANSMITTER_LIRCD_CONF="" TRANSMITTER_LIRCD_ARGS="" #Enable lircd START_LIRCD="true" #Don't start lircmd even if there seems to be a good config file #START_LIRCMD="false" #Try to load appropriate kernel modules LOAD_MODULES="true" # Default configuration files for your hardware if any LIRCMD_CONF="" FORCE_NONINTERACTIVE_RECONFIGURATION="false" START_LIRCMD="" REMOTE_SOCKET="" /etc/lirc/lircd.conf ################################################################################ # lircd.conf file for the new Microsoft Media Center remote using a new # Microsoft Media Center receiver. ################################################################################ begin remote name mceusb bits 16 flags RC6|CONST_LENGTH eps 30 aeps 100 header 2667 889 one 444 444 zero 444 444 pre_data_bits 21 pre_data 0x37FF0 gap 105000 toggle_bit 22 rc6_mask 0x100000000 begin codes # starts at A1 BLUE 0x00007BA1 YELLOW 0x00007BA2 GREEN 0x00007BA3 RED 0x00007BA4 TELETEXT 0x00007BA5 RADIO 0x00007BAF PRINT 0x00007BB1 VIDEO 0x00007BB5 # VIDEOS button IMAGE 0x00007BB6 # PICTURES button PVR 0x00007BB7 # RECORDED TV button AUDIO 0x00007BB8 # MUSIC button TV 0x00007BB9 # no BA - D8 Guide 0x00007BD9 TV 0x00007BDA # LIVE TV button Dvd 0x00007BDB Back 0x00007BDC OK 0x00007BDD Right 0x00007BDE Left 0x00007BDF Down 0x00007BE0 Up 0x00007BE1 STAR 0x00007BE2 Hash 0x00007BE3 PREVIOUS 0x00007BE4 # REPLAY button Next 0x00007BE5 # SKIP button Stop 0x00007BE6 Pause 0x00007BE7 Record 0x00007BE8 Play 0x00007BE9 Rewind 0x00007BEA Forward 0x00007BEB CHANNELDOWN 0x00007BEC CHANNELUP 0x00007BED Volumedown 0x00007BEE Volumeup 0x00007BEF INFO 0x00007BF0 # MORE (i) button Mute 0x00007BF1 MENU 0x00007BF2 # START (Windows) button POWER 0x00007BF3 ENTER 0x00007BF4 CLEAR 0x00007BF5 9 0x00007BF6 8 0x00007BF7 7 0x00007BF8 6 0x00007BF9 5 0x00007BFA 4 0x00007BFB 3 0x00007BFC 2 0x00007BFD 1 0x00007BFE 0 0x00007BFF end codes end remote Whit this config file lirc will listen on the devices and will translate the input. It will give a hardware name for the device and the button pressed. irw wil give you a xample on the commandline #irw Now press some buttons To feed the command to the appropiate program (if this program supports lirc) make a config in the home dir of the user. ~/.lirc/mythtv begin remote = ClickWheel prog = mythtv button = KEY_VOLUMEUP config = ] repeat = 0 delay = 0 end begin remote = ClickWheel prog = mythtv button = KEY_VOLUMEDOWN config = [ repeat = 0 delay = 0 end And the final piece of the puzzle and this was the hardest to find but the most simple thing to do. It seems that Lirc has it all figured out for the newest version on how to run multiple devices without major manual configuration EXCEPT the Lirc init.d script. With my devices plugged in and issuing an ls -l /dev/lirc* I had all the devices I needed with manual configuration so Code: crw-rw---- 1 root root 61, 0 2010-02-21 11:44 /dev/lirc0 crw-rw---- 1 root root 61, 1 2010-02-21 11:44 /dev/lirc1 lrwxrwxrwx 1 root root 19 2010-02-21 11:44 /dev/lircd -> /var/run/lirc/lircd lrwxrwxrwx 1 root root 20 2010-02-21 11:44 /dev/lircd1 -> /var/run/lirc/lircd SEE the problem - /dev/lircd1 was pointing to /var/run/lirc/lircd so when issuing an irsend command from a script or a command line I was getting the hardware cannot send error. The actual fix I finally found in another post - THANK YOU TO cyber_source - YOU ARE A LIFE SAVER. You need to edit your /etc/init.d/lirc startup script and change a couple lines First Line 83 Needs to be changed from "${TRANSMITTER_SOCKET}1" to this - "${TRANSMITTER_SOCKET}" and then line 131 Needs to be changed from TRANSMITTER_SOCKET="/var/run/lirc/lircd" to this TRANSMITTER_SOCKET="/var/run/lirc/lircd1" save and exit the file reboot your system and run another ls -l /dev/lirc* and you should see Code: crw-rw---- 1 root root 61, 0 2010-02-21 11:44 /dev/lirc0 crw-rw---- 1 root root 61, 1 2010-02-21 11:44 /dev/lirc1 lrwxrwxrwx 1 root root 19 2010-02-21 11:44 /dev/lircd -> /var/run/lirc/lircd lrwxrwxrwx 1 root root 20 2010-02-21 11:44 /dev/lircd1 -> /var/run/lirc/lircd1 == IRblaster == To get the right codes from youre remote you can record it with irrecord. This will provide a configuration file which you can use in lirc #irrecord /tmp/remote.conf Now follow the instructions To get the raw codes #irrecord -f /tmp/remoteraw.conf You wil get this file for a topfield tf6000cok remote # Please make this file available to others # by sending it to <lirc@bartelmus.de> # # this config file was automatically generated # using lirc-0.8.6(default) on Wed Mar 24 20:58:54 2010 # # contributed by # # brand:Topfield # model no. of remote control: TP-014 # devices being controlled by this remote: Topfield TF6000COK # begin remote name topfield flags RAW_CODES|CONST_LENGTH eps 30 aeps 100 gap 107620 begin raw_codes name KEY_1 9000 4450 600 500 650 450 650 1650 600 500 600 500 650 500 600 500 600 500 650 1600 650 1600 600 1650 600 1650 600 1650 600 1650 600 1600 650 1600 600 1650 600 550 600 500 600 500 600 1650 600 550 550 550 600 500 650 500 600 1650 600 1650 600 1600 600 550 600 1650 550 1650 650 1650 550 name KEY_2 9050 4400 600 500 650 500 600 1650 600 500 600 500 650 500 600 500 600 500 650 1650 600 1600 600 1650 600 1650 600 1650 600 1650 600 1650 600 1600 600 550 600 1650 600 500 600 500 650 1600 600 550 600 500 600 550 600 1600 600 550 600 1650 550 1650 650 500 600 1650 600 1650 600 1600 600 name KEY_3 9000 4450 600 500 650 500 600 1600 650 500 600 500 600 550 600 500 600 550 600 1600 600 1650 650 1600 600 1650 600 1650 600 1650 600 1600 600 1650 600 1650 600 1650 600 500 600 550 600 1650 600 500 600 500 600 550 600 500 600 550 600 1600 650 1650 550 550 600 1650 600 1600 600 1650 600 name KEY_4 9050 4450 600 500 600 500 650 1600 600 500 650 500 600 500 650 500 600 500 600 1650 600 1650 600 1650 600 1600 650 1600 650 1600 600 1650 600 1650 600 500 600 550 600 1650 550 550 600 1650 600 500 600 500 650 500 600 1650 600 1650 600 500 600 1650 600 500 650 1600 600 1650 600 1650 600 name KEY_5 9050 4400 650 450 650 500 600 1650 600 500 650 500 600 500 600 500 650 500 600 1650 600 1600 650 1650 600 1600 600 1650 600 1650 600 1650 600 1650 600 1650 600 500 600 1650 600 500 600 1650 600 500 650 500 600 500 600 550 600 1650 600 500 600 1650 600 500 600 1650 600 1650 600 1650 600 name KEY_6 9050 4400 650 500 600 500 600 1650 600 500 650 500 600 500 600 500 650 500 600 1650 600 1650 600 1600 600 1650 600 1650 600 1650 600 1650 600 1650 600 500 600 1650 600 1650 600 500 600 1650 600 550 550 550 600 500 600 1650 600 500 600 550 600 1650 600 500 600 1650 600 1650 600 1650 600 name KEY_7 9000 4450 600 500 600 500 650 1600 650 450 650 500 600 500 650 500 600 500 600 1650 600 1650 600 1650 600 1650 600 1600 650 1600 600 1650 600 1650 600 1650 600 1650 550 1650 650 500 600 1650 600 500 600 550 600 500 600 500 600 550 600 500 600 1650 600 500 650 1600 600 1650 600 1650 600 name KEY_8 9050 4400 650 450 650 500 600 1650 600 500 650 500 600 500 600 500 650 500 600 1650 600 1600 650 1650 550 1650 600 1650 600 1650 600 1650 600 1600 650 500 600 550 550 550 600 1650 600 1650 550 550 600 500 650 500 600 1600 650 1650 550 1650 600 550 600 500 600 1650 600 1650 600 1650 600 name KEY_9 9050 4400 650 500 600 500 600 1650 600 500 650 500 600 500 600 500 650 500 600 1650 600 1650 600 1600 600 1650 650 1600 600 1650 600 1650 600 1650 600 1600 600 550 600 500 600 1650 600 1650 600 550 550 550 600 500 600 550 600 1600 600 1650 600 550 600 500 600 1650 600 1650 600 1650 600 name KEY_0 9000 4450 600 500 650 450 650 1600 650 500 600 500 600 500 650 500 600 550 600 1600 600 1650 600 1650 600 1650 600 1650 600 1650 600 1600 600 1650 600 550 600 500 600 500 650 500 600 1650 600 500 600 550 600 500 600 1650 600 1650 600 1600 650 1650 550 550 600 1650 600 1600 600 1650 600 name KEY_CHANNELUP 9050 4400 650 500 600 500 650 1600 650 500 600 500 600 500 650 500 600 500 650 1600 600 1650 600 1650 600 1650 600 1600 600 1650 650 1600 600 1650 600 1650 600 500 600 1650 600 500 600 1650 650 500 600 1600 650 500 600 550 550 1650 600 550 600 1650 550 550 600 1650 600 500 600 1650 600 name KEY_CHANNELDOWN 9050 4400 650 500 600 500 650 1600 600 500 650 500 600 550 600 500 600 500 600 1650 600 1650 600 1650 600 1600 650 1650 600 1600 600 1650 600 1650 600 500 650 1600 600 1650 600 550 600 1600 600 550 600 1650 550 550 600 1650 600 500 600 550 600 1650 550 550 600 1650 600 500 600 1650 600 name KEY_VOLUMEUP 9050 4400 650 500 600 500 600 1650 600 500 650 500 600 500 600 500 650 500 600 1650 600 1650 600 1600 600 1650 650 1600 600 1650 600 1650 600 1650 600 1600 600 1650 650 1600 600 500 650 1650 550 550 600 1650 600 500 600 500 600 550 600 500 650 1600 600 500 650 1650 550 550 600 1650 600 name KEY_VOLUMEDOWN 9050 4400 650 500 600 550 600 1600 650 500 600 500 600 500 650 500 600 500 650 1600 600 1650 600 1650 600 1650 600 1650 600 1600 650 1600 600 1650 600 550 600 500 600 500 600 1650 600 1650 600 500 650 1600 600 550 600 1650 600 1600 600 1650 600 550 550 550 600 1650 600 500 600 1650 600 end raw_codes end remote Now save this file in /etc/lirc and edit /etc/lirc/lircd.conf include "/etc/lirc/remote.conf" Now we can test irblaster #irsend SEND_ONCE remote KEY_1 The channel on the topfield DVB must jump to channel 1 == EPG == To use the epg we want to grad the data from a source. In this case we use tv_grab_nl_py. This script will grab all data from www.tvgids.nl XMLTV-configuratiebestand aanmaken * Start MythTV Setup * Choose for Video Sources. * Choose for existing or a new video source * Listings grabber: The Netherlands (tv_grab_nl_py...) * Klick Finish On the prompt # tv_grab_nl_py --configure This will create a config file in /homedir/.xmltv/tv_grab_nl_py.conf Edit this config file and clear out all channels you don want (or edit them out) To see is something is happening #mythfilldatabase -v all --refresh-today To see what's in the database *mysql -u mythtv -p mythconverg -e "select chanid, callsign, name, xmltvid from channel;" == Metadata == Make sure you have set the filepaths right. Go to Mythtv setup - 6. Storage Directories Choose (create Fanart group) and choose the right directory Now go to the mythfrontend and choose to watch a video. Select the video and press W. Based on the filename [http://www.mythtv.org/wiki/MythVideo_File_Parsing] the right data will be searched. To configure the metadata yourself you can select the video and press I. Now configure the metadata. == VLC == To make VLC player the default player. Goto Utilities/Setup -> SetUp -> Media Settings -> Video Settings -> Player Settings vlc file://%s vlc://quit nd change the extensions goto Utilities/Setup -> SetUp -> Media Settings -> Video Settings -> File Types 5e2c9cf824d3d4f7b79262336dc61051625db038 2563 2562 2010-04-30T19:58:44Z Insomnia 3 /* VLC */ wikitext text/x-wiki == lirc == LIRC CVS is hosted at SourceForge. You can get a copy of the current CVS tree using anonymous CVS login. First log in to the cvs server (press <enter> for password): cvs -d:pserver:anonymous@lirc.cvs.sourceforge.net:/cvsroot/lirc login Get the sources: cvs -z8 -d:pserver:anonymous@lirc.cvs.sourceforge.net:/cvsroot/lirc co lirc After initial checkout, you can change into this directory and execute cvs commands without the -d option. For example: cvs update Compile: cd lirc ./autogen.sh ./setup.sh make Lirc will initiate the hardware with the below config file. In this case a mce usb receiver with a ir blaster and also a volume knob (Antec fusion) # /etc/lirc/hardware.conf # #Chosen Remote Control REMOTE="Windows Media Center Transceivers/Remotes (all)" REMOTE_MODULES="lirc_dev lirc_mceusb2" REMOTE_DRIVER="" REMOTE_DEVICE="/dev/lirc1" REMOTE_LIRCD_CONF="mceusb/lircd.conf.mceusb" REMOTE_LIRCD_ARGS="" #Chosen Remote Control REMOTE="Windows Media Center Transceivers/Remotes (all)" REMOTE_MODULES="lirc_dev lirc_imon" REMOTE_DRIVER="" REMOTE_DEVICE="/dev/lirc0" REMOTE_LIRCD_CONF="" REMOTE_LIRCD_ARGS="" #Chosen IR Transmitter TRANSMITTER="Microsoft Windows Media Center V2 (usb) : Direct TV Receiver" TRANSMITTER_MODULES="lirc_dev lirc_mceusb2" TRANSMITTER_DRIVER="" TRANSMITTER_DEVICE="/dev/lirc1" TRANSMITTER_SOCKET="" TRANSMITTER_LIRCD_CONF="" TRANSMITTER_LIRCD_ARGS="" #Enable lircd START_LIRCD="true" #Don't start lircmd even if there seems to be a good config file #START_LIRCMD="false" #Try to load appropriate kernel modules LOAD_MODULES="true" # Default configuration files for your hardware if any LIRCMD_CONF="" FORCE_NONINTERACTIVE_RECONFIGURATION="false" START_LIRCMD="" REMOTE_SOCKET="" /etc/lirc/lircd.conf ################################################################################ # lircd.conf file for the new Microsoft Media Center remote using a new # Microsoft Media Center receiver. ################################################################################ begin remote name mceusb bits 16 flags RC6|CONST_LENGTH eps 30 aeps 100 header 2667 889 one 444 444 zero 444 444 pre_data_bits 21 pre_data 0x37FF0 gap 105000 toggle_bit 22 rc6_mask 0x100000000 begin codes # starts at A1 BLUE 0x00007BA1 YELLOW 0x00007BA2 GREEN 0x00007BA3 RED 0x00007BA4 TELETEXT 0x00007BA5 RADIO 0x00007BAF PRINT 0x00007BB1 VIDEO 0x00007BB5 # VIDEOS button IMAGE 0x00007BB6 # PICTURES button PVR 0x00007BB7 # RECORDED TV button AUDIO 0x00007BB8 # MUSIC button TV 0x00007BB9 # no BA - D8 Guide 0x00007BD9 TV 0x00007BDA # LIVE TV button Dvd 0x00007BDB Back 0x00007BDC OK 0x00007BDD Right 0x00007BDE Left 0x00007BDF Down 0x00007BE0 Up 0x00007BE1 STAR 0x00007BE2 Hash 0x00007BE3 PREVIOUS 0x00007BE4 # REPLAY button Next 0x00007BE5 # SKIP button Stop 0x00007BE6 Pause 0x00007BE7 Record 0x00007BE8 Play 0x00007BE9 Rewind 0x00007BEA Forward 0x00007BEB CHANNELDOWN 0x00007BEC CHANNELUP 0x00007BED Volumedown 0x00007BEE Volumeup 0x00007BEF INFO 0x00007BF0 # MORE (i) button Mute 0x00007BF1 MENU 0x00007BF2 # START (Windows) button POWER 0x00007BF3 ENTER 0x00007BF4 CLEAR 0x00007BF5 9 0x00007BF6 8 0x00007BF7 7 0x00007BF8 6 0x00007BF9 5 0x00007BFA 4 0x00007BFB 3 0x00007BFC 2 0x00007BFD 1 0x00007BFE 0 0x00007BFF end codes end remote Whit this config file lirc will listen on the devices and will translate the input. It will give a hardware name for the device and the button pressed. irw wil give you a xample on the commandline #irw Now press some buttons To feed the command to the appropiate program (if this program supports lirc) make a config in the home dir of the user. ~/.lirc/mythtv begin remote = ClickWheel prog = mythtv button = KEY_VOLUMEUP config = ] repeat = 0 delay = 0 end begin remote = ClickWheel prog = mythtv button = KEY_VOLUMEDOWN config = [ repeat = 0 delay = 0 end And the final piece of the puzzle and this was the hardest to find but the most simple thing to do. It seems that Lirc has it all figured out for the newest version on how to run multiple devices without major manual configuration EXCEPT the Lirc init.d script. With my devices plugged in and issuing an ls -l /dev/lirc* I had all the devices I needed with manual configuration so Code: crw-rw---- 1 root root 61, 0 2010-02-21 11:44 /dev/lirc0 crw-rw---- 1 root root 61, 1 2010-02-21 11:44 /dev/lirc1 lrwxrwxrwx 1 root root 19 2010-02-21 11:44 /dev/lircd -> /var/run/lirc/lircd lrwxrwxrwx 1 root root 20 2010-02-21 11:44 /dev/lircd1 -> /var/run/lirc/lircd SEE the problem - /dev/lircd1 was pointing to /var/run/lirc/lircd so when issuing an irsend command from a script or a command line I was getting the hardware cannot send error. The actual fix I finally found in another post - THANK YOU TO cyber_source - YOU ARE A LIFE SAVER. You need to edit your /etc/init.d/lirc startup script and change a couple lines First Line 83 Needs to be changed from "${TRANSMITTER_SOCKET}1" to this - "${TRANSMITTER_SOCKET}" and then line 131 Needs to be changed from TRANSMITTER_SOCKET="/var/run/lirc/lircd" to this TRANSMITTER_SOCKET="/var/run/lirc/lircd1" save and exit the file reboot your system and run another ls -l /dev/lirc* and you should see Code: crw-rw---- 1 root root 61, 0 2010-02-21 11:44 /dev/lirc0 crw-rw---- 1 root root 61, 1 2010-02-21 11:44 /dev/lirc1 lrwxrwxrwx 1 root root 19 2010-02-21 11:44 /dev/lircd -> /var/run/lirc/lircd lrwxrwxrwx 1 root root 20 2010-02-21 11:44 /dev/lircd1 -> /var/run/lirc/lircd1 == IRblaster == To get the right codes from youre remote you can record it with irrecord. This will provide a configuration file which you can use in lirc #irrecord /tmp/remote.conf Now follow the instructions To get the raw codes #irrecord -f /tmp/remoteraw.conf You wil get this file for a topfield tf6000cok remote # Please make this file available to others # by sending it to <lirc@bartelmus.de> # # this config file was automatically generated # using lirc-0.8.6(default) on Wed Mar 24 20:58:54 2010 # # contributed by # # brand:Topfield # model no. of remote control: TP-014 # devices being controlled by this remote: Topfield TF6000COK # begin remote name topfield flags RAW_CODES|CONST_LENGTH eps 30 aeps 100 gap 107620 begin raw_codes name KEY_1 9000 4450 600 500 650 450 650 1650 600 500 600 500 650 500 600 500 600 500 650 1600 650 1600 600 1650 600 1650 600 1650 600 1650 600 1600 650 1600 600 1650 600 550 600 500 600 500 600 1650 600 550 550 550 600 500 650 500 600 1650 600 1650 600 1600 600 550 600 1650 550 1650 650 1650 550 name KEY_2 9050 4400 600 500 650 500 600 1650 600 500 600 500 650 500 600 500 600 500 650 1650 600 1600 600 1650 600 1650 600 1650 600 1650 600 1650 600 1600 600 550 600 1650 600 500 600 500 650 1600 600 550 600 500 600 550 600 1600 600 550 600 1650 550 1650 650 500 600 1650 600 1650 600 1600 600 name KEY_3 9000 4450 600 500 650 500 600 1600 650 500 600 500 600 550 600 500 600 550 600 1600 600 1650 650 1600 600 1650 600 1650 600 1650 600 1600 600 1650 600 1650 600 1650 600 500 600 550 600 1650 600 500 600 500 600 550 600 500 600 550 600 1600 650 1650 550 550 600 1650 600 1600 600 1650 600 name KEY_4 9050 4450 600 500 600 500 650 1600 600 500 650 500 600 500 650 500 600 500 600 1650 600 1650 600 1650 600 1600 650 1600 650 1600 600 1650 600 1650 600 500 600 550 600 1650 550 550 600 1650 600 500 600 500 650 500 600 1650 600 1650 600 500 600 1650 600 500 650 1600 600 1650 600 1650 600 name KEY_5 9050 4400 650 450 650 500 600 1650 600 500 650 500 600 500 600 500 650 500 600 1650 600 1600 650 1650 600 1600 600 1650 600 1650 600 1650 600 1650 600 1650 600 500 600 1650 600 500 600 1650 600 500 650 500 600 500 600 550 600 1650 600 500 600 1650 600 500 600 1650 600 1650 600 1650 600 name KEY_6 9050 4400 650 500 600 500 600 1650 600 500 650 500 600 500 600 500 650 500 600 1650 600 1650 600 1600 600 1650 600 1650 600 1650 600 1650 600 1650 600 500 600 1650 600 1650 600 500 600 1650 600 550 550 550 600 500 600 1650 600 500 600 550 600 1650 600 500 600 1650 600 1650 600 1650 600 name KEY_7 9000 4450 600 500 600 500 650 1600 650 450 650 500 600 500 650 500 600 500 600 1650 600 1650 600 1650 600 1650 600 1600 650 1600 600 1650 600 1650 600 1650 600 1650 550 1650 650 500 600 1650 600 500 600 550 600 500 600 500 600 550 600 500 600 1650 600 500 650 1600 600 1650 600 1650 600 name KEY_8 9050 4400 650 450 650 500 600 1650 600 500 650 500 600 500 600 500 650 500 600 1650 600 1600 650 1650 550 1650 600 1650 600 1650 600 1650 600 1600 650 500 600 550 550 550 600 1650 600 1650 550 550 600 500 650 500 600 1600 650 1650 550 1650 600 550 600 500 600 1650 600 1650 600 1650 600 name KEY_9 9050 4400 650 500 600 500 600 1650 600 500 650 500 600 500 600 500 650 500 600 1650 600 1650 600 1600 600 1650 650 1600 600 1650 600 1650 600 1650 600 1600 600 550 600 500 600 1650 600 1650 600 550 550 550 600 500 600 550 600 1600 600 1650 600 550 600 500 600 1650 600 1650 600 1650 600 name KEY_0 9000 4450 600 500 650 450 650 1600 650 500 600 500 600 500 650 500 600 550 600 1600 600 1650 600 1650 600 1650 600 1650 600 1650 600 1600 600 1650 600 550 600 500 600 500 650 500 600 1650 600 500 600 550 600 500 600 1650 600 1650 600 1600 650 1650 550 550 600 1650 600 1600 600 1650 600 name KEY_CHANNELUP 9050 4400 650 500 600 500 650 1600 650 500 600 500 600 500 650 500 600 500 650 1600 600 1650 600 1650 600 1650 600 1600 600 1650 650 1600 600 1650 600 1650 600 500 600 1650 600 500 600 1650 650 500 600 1600 650 500 600 550 550 1650 600 550 600 1650 550 550 600 1650 600 500 600 1650 600 name KEY_CHANNELDOWN 9050 4400 650 500 600 500 650 1600 600 500 650 500 600 550 600 500 600 500 600 1650 600 1650 600 1650 600 1600 650 1650 600 1600 600 1650 600 1650 600 500 650 1600 600 1650 600 550 600 1600 600 550 600 1650 550 550 600 1650 600 500 600 550 600 1650 550 550 600 1650 600 500 600 1650 600 name KEY_VOLUMEUP 9050 4400 650 500 600 500 600 1650 600 500 650 500 600 500 600 500 650 500 600 1650 600 1650 600 1600 600 1650 650 1600 600 1650 600 1650 600 1650 600 1600 600 1650 650 1600 600 500 650 1650 550 550 600 1650 600 500 600 500 600 550 600 500 650 1600 600 500 650 1650 550 550 600 1650 600 name KEY_VOLUMEDOWN 9050 4400 650 500 600 550 600 1600 650 500 600 500 600 500 650 500 600 500 650 1600 600 1650 600 1650 600 1650 600 1650 600 1600 650 1600 600 1650 600 550 600 500 600 500 600 1650 600 1650 600 500 650 1600 600 550 600 1650 600 1600 600 1650 600 550 550 550 600 1650 600 500 600 1650 600 end raw_codes end remote Now save this file in /etc/lirc and edit /etc/lirc/lircd.conf include "/etc/lirc/remote.conf" Now we can test irblaster #irsend SEND_ONCE remote KEY_1 The channel on the topfield DVB must jump to channel 1 == EPG == To use the epg we want to grad the data from a source. In this case we use tv_grab_nl_py. This script will grab all data from www.tvgids.nl XMLTV-configuratiebestand aanmaken * Start MythTV Setup * Choose for Video Sources. * Choose for existing or a new video source * Listings grabber: The Netherlands (tv_grab_nl_py...) * Klick Finish On the prompt # tv_grab_nl_py --configure This will create a config file in /homedir/.xmltv/tv_grab_nl_py.conf Edit this config file and clear out all channels you don want (or edit them out) To see is something is happening #mythfilldatabase -v all --refresh-today To see what's in the database *mysql -u mythtv -p mythconverg -e "select chanid, callsign, name, xmltvid from channel;" == Metadata == Make sure you have set the filepaths right. Go to Mythtv setup - 6. Storage Directories Choose (create Fanart group) and choose the right directory Now go to the mythfrontend and choose to watch a video. Select the video and press W. Based on the filename [http://www.mythtv.org/wiki/MythVideo_File_Parsing] the right data will be searched. To configure the metadata yourself you can select the video and press I. Now configure the metadata. == VLC == To make VLC player the default player. Goto Utilities/Setup -> SetUp -> Media Settings -> Video Settings -> Player Settings vlc file://%s vlc://quit nd change the extensions goto Utilities/Setup -> SetUp -> Media Settings -> Video Settings -> File Types == TV card == * See if the card is working in a MS windows pc with technotrends own software * Try installing w_scan to do a channel scan the use the configuration file created by importing it into mythtv. * Recompile the drivers with new source files * http://mythportal.be/TTBudgetS1500 321f403cea8e12cb1ea65442df4bf715c6430fe1 0 1482 2483 2463 2010-02-07T23:35:01Z 82.161.20.132 0 /* Make DVD */ wikitext text/x-wiki == NDISwrapper == NDISwrapper is a free software driver wrapper that enables the use of Microsoft Windows drivers for wireless network devices. Download the windows driver wich contains the .inf file<br> Install with ndiswrapper -i drivername.inf<br> check the device id with lsusb or lspci -n<br> Now execute with ndiswrapper -a deviceid driver ndiswrapper -a 0bda:8197 net8187b check the installed drivers ndiswrapper -l Write the configuration for modprobe ndiswrapper -m And use the module modprobe ndiswrapper == Compiz == To enable compiz install the Nvidia drivers and install CompizConfig Settings Manager sudo apt-get install simple-ccsm Now navigate to system > preferences > Appereance And go to the Visual effects tab. Choose custum there On Kubuntu change the default windows manager System Settings -> Default Applications -> Windows manager {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Desktop Effects !style="background:#ffdead;"|Keyboard Shortcuts |- |Rotate Cube Manually |Ctrl + Alt + Left Mouse Button |- |Expo |Super + E (toggle) |- |Rotate Cube |Mousewheel on Desktop |- |Film Effect |Ctrl + Alt + Down Arrow |- |Scale Windows |Alt + Shift + Up Arrow |- |Ring Switcher |Super + Tab - overrides Shift Switcher |} Super key is the windows key :-) == Mount Network Share == First install smbfs apt-get install smbfs Then create a folder inside of the /media directory to mount the share on or choose you're own directory sudo mkdir /media/Storage Create a credentials file in /root so that you can save your password and have it protected by the root account: sudo gedit /root/.cifscredentials Add this to the file username=Guest password= sudo vi /etc/fstab Add the following line //192.168.0.10/SHARENAME /media/Storage cifs auto,iocharset=utf8,uid=USER,gid=users,credentials=/root/.cifscredentials,file_mode=0775,dir_mode=0775 0 0 To check if the file works sudo mount -a And you should see you're drives on the desktop Ik you get error when you shut down the pc ''CIFS VFS: server not responding'' then you have to unmount first. Do this with the following ln -s /etc/init.d/umountnfs.sh /etc/rc0.d/K15umountnfs.sh ln -s /etc/init.d/umountnfs.sh /etc/rc6.d/K15umountnfs.sh == Citrix Ica client == Download the Linux citrix ica client from Citrix http://citrix.com/English/SS/downloads/details.asp?downloadID=3323&productID=-1 Install the 32bits libraries if youŕe working on a 64bits platform apt-get install ia32-libs Install the Open-motif libraries apt-get install libmotif3 citrix 11 requires openmotif 2.3.1 Download the rpm package for openmotif 2.3.1, I used: ftp://ftp.ics.com/openmotif/2.3/2.3.1/openmotif-2.3.1-1.RHEL3.0.i386.rpm To convert a rpm package to a debian package. Use alien to convert the rpm to a deb package alien -d openmotif-2.3.1-1.RHEL3.0.i386.rpm Then install the package in the usual way. Note, before installing the alien'ed package it is best to uninstall the previous version of motif, as this will not update the existing motif package. dpkg -i openmotif_2.3.1-2_i386.deb Unpack the package and execute the installation script ./setupwfc Find the plugin directory of firefox. Probably is /usr/lib/firefox/plugins/ otherwise use find / -name plugins | grep -i "netscape\|firefox\|mozilla" Create a symlink to the citrix ica library ln –s /usr/lib/ICAClient/npica.so npica.so If you open a connection to your citrix server. The browser will ask you if you want to open or save the session. Browse to the ica client /usr/lib/ICAClient/wfica and tell it to use it for all applications. When you get a ssl error "you have not chosen to thrust....." Then copy the certificate in this location. /usr/lib/ICAClient/keystore/cacerts/ For 64Bits OS Install Needed 32-bit Open Motif libraries to /usr/lib32 Setup a temporary environment mkdir -p ~/tmp/Citrix cd ~/tmp/Citrix Download a recent i386 libmotif3 .deb package to the above folder wget http://mirrors.kernel.org/ubuntu/pool/multiverse/o/openmotif/libmotif3_2.2.3-1.4_i386.deb Use dpkg to extract the package dpkg -x libmotif3*i386.deb libmotif Copy the libraries to /usr/lib32 sudo cp libmotif/usr/lib/*.so.* /usr/lib32/ sudo cp -r libmotif/usr/lib/X11/bindings /usr/lib32/X11/ == Make DVD == To make a video DVD you can burn you're image on the dvd. If you just have the VIDEO_TS files then the easiest way is to convert these into a iso. mkisofs -dvd-video -o ~/moviename.iso /path/to/the/VIDEO_TS /path/to/the/VIDEO_TS path is for example /moviename not /moviename/VIDEO_TS == FFMPEG == Is a video converter tool #>/usr/bin/ffmpeg -i "00059.MTS" -vcodec flv -f flv -r 25 -s 356x200 -aspect 16:9 -b 2000k -g 160 -cmp 2 -subcmp 2 -mbd 2 -flags +aic+cbp+mv0+mv4 -trellis 2 -acodec libmp3lame -ac 2 -ar 44100 -ab 256k "stacaravan1.flv" 624ffbff961dc8fc750484459f42f3ecadb00aed 0 1532 2484 2375 2010-03-16T11:42:41Z 187.4.128.12 0 /* Mediawiki Extension: Group Permissions Manager */ wikitext text/x-wiki FCX1bu <a href="http://nvvcqflwbycb.com/">nvvcqflwbycb</a>, [url=http://irqfsozbmvfe.com/]irqfsozbmvfe[/url], [link=http://xqvdviebyrar.com/]xqvdviebyrar[/link], http://tjmbjtiuxzxh.com/ ==Adding the extension== First, download the latest snapshot of the GroupPermissionsManager extension from here: [http://www.mediawiki.org/wiki/Extension:GroupPermissionsManager Mediawiki Extension:Group Permissions Manager]. It's a single archive with a name that looks like ''GroupPermissionsManager-trunk-r45886.tar.gz''. You can extract it straight into the Debian mediawiki extensions directory ''/usr/share/mediawiki-extensions'', that already exists if you've installed the ''[[Mediawiki-extensions_under_Debian|mediawiki-extensions]]'' package; out comes a little directory structure like this: GroupPermissionsManager |-- plugins | |-- disabled | `-- messages `-- scripts You'll have to make sure all files and directories are owned by ''root'', and that the PHP files cannot be edited by anyone else than ''root''. This will most likely not be the case: as ''root'' run: cd /usr/share/mediawiki-extensions/GroupPermissionsManager chown -R root:root * chmod -R 644 * Now, to make the extension work with Debian, we ''must'' move all files and folders under ''GroupPermissionsManager'' to ''/usr/share/mediawiki-extensions'': cd /usr/share/mediawiki-extensions/GroupPermissionsManager mv scripts .. mv plugins .. mv * .. cd .. rmdir GroupPermissionsManager Next, we have to make a small alteration to ''/usr/share/mediawiki/includes/GlobalFunctions.php'' because there's a bug or shortcoming in MediaWiki 1.12, and that's the version that Lenny uses. The alteration is described in [http://www.mediawiki.org/wiki/Extension:GroupPermissionsManager#Patch a patch prescription on the MediaWiki site], but in essence we add a line after line number 422: the line beginning with "wfRunHooks": <source lang="php"> function wfMsgGetKey( $key, $useDB, $forContent = false, $transform = true ) { global $wgParser, $wgContLang, $wgMessageCache, $wgLang; wfRunHooks( 'NormalizeMessageKey', array( &$key, &$useDB, &$langCode, &$transform ) ); </source> Next, we create a directory where Group Permissions Manager will keep the configuration files. In the Debian style, we need something under ''/etc''. We would ordinarily suggest something under ''/etc/mediawiki-extensions'', but the configuration that the extension manipulates is used by MediaWiki itself. Thus we suggest creating ''/etc/mediawiki/config''. After that, grant the permission to write in this directory to the web server daemon, for Apache2 ''www-data''.<br> Finally, create a symlink to this config directory in the place where GroupPermissionsManager actually ''expects'' it, namely in the directory where the PHP-script itself resides (here: ''/usr/share/mediawiki-extensions/''). All of this can be achieved by following these steps: cd /etc/mediawiki mkdir config chown www-data:www-data config cd /usr/share/mediawiki-extensions ln -s /etc/mediawiki/config Now we can mark the extension ''GroupPermissionsManager.php'' available to MediaWiki: cd /etc/mediawiki-extensions/extensions-available ln -s /usr/share/mediawiki-extensions/GroupPermissionsManager.php Then, enable the extension mwenext GroupPermissionsManager.php This by default adds some extra capabilities to the Mediawiki administrator group "bureaucrat", of which WikiAdmin is a member - and presumably you too. The capabilities are to use a ''Special'' page to create, manage, and remove Wiki groups and their permissions. ==Using the extension== To manage group permissions, you need the following: * your MediaWiki user account needs to be in a MediaWiki group that has been granted the right to use Group Permissions Manager, e.g. ''bureaucrat'' as depicted above; * you must be logged in with that MediaWiki account; * you need to know the name of the group whose permissions you want to manage (or create or delete). In the left navigation area, click on ''Special pages''; scroll down to the section ''Restricted special pages'', you should see an entry ''Manage Group Permissions''. Click it to enter the Manage Group Permissions special page. Here, you'll find just an empty box and a "Go" button. Fill in the name of the group you want to create/manage/delete, and click "Go". You'll find yourself in a long page with group permissions, each of which can be "true", "false" or "inherit". Setting a permission to "true" or "false" enables or disables the permission for this group, while leaving it on "inherit" means the group gets the default permission that MediaWiki assigns every group - just think of the default rights of the default group "users" Furthermore: * If the group pre-exists, you'll find above the list a comment box and a "Delete group" button, where you can remove the group, while leaving the comment in the ''GroupPermissionsLog.log'' log file. * Furthermore, if the group pre-exists, the permissions list ends with a comment box and a "Change group permissions" button. Clicking that button will change the group permissions to the set designated in the permissions list. The changes, along with all other group permissions, can be found in the ''/etc/mediawiki/config'' directory in file ''GroupPermissons.php''. Clicking the button will also have resulted in a backup of the ''GroupPermissons.php'' file in that same directory, but named ''GroupPermissons.<timestamp>.php'', e.g. ''GroupPermissions.21012009171713.php''. * If the group name is "new", no "Delete group" button is shown, but the permissions list ends with a comment box and an "Add group" button, which will create the group with the designated name, while leaving the comment in the ''GroupPermissionsLog.log'' log file. Again, the comment is logged, and a backup of the ''GroupPermissons.php'' file is made. 986444f7966eda37a217ace65d908403e3fe1532 2494 2484 2010-03-22T16:03:07Z 24.5.241.25 0 /* Adding the extension */ wikitext text/x-wiki FCX1bu <a href="http://nvvcqflwbycb.com/">nvvcqflwbycb</a>, [url=http://irqfsozbmvfe.com/]irqfsozbmvfe[/url], [link=http://xqvdviebyrar.com/]xqvdviebyrar[/link], http://tjmbjtiuxzxh.com/ Fjapje <a href="http://qyqfydostlsb.com/">qyqfydostlsb</a>, [url=http://jlataoajnjwp.com/]jlataoajnjwp[/url], [link=http://fyikzchdwrrf.com/]fyikzchdwrrf[/link], http://cpuojmnkglxj.com/ ==Using the extension== To manage group permissions, you need the following: * your MediaWiki user account needs to be in a MediaWiki group that has been granted the right to use Group Permissions Manager, e.g. ''bureaucrat'' as depicted above; * you must be logged in with that MediaWiki account; * you need to know the name of the group whose permissions you want to manage (or create or delete). In the left navigation area, click on ''Special pages''; scroll down to the section ''Restricted special pages'', you should see an entry ''Manage Group Permissions''. Click it to enter the Manage Group Permissions special page. Here, you'll find just an empty box and a "Go" button. Fill in the name of the group you want to create/manage/delete, and click "Go". You'll find yourself in a long page with group permissions, each of which can be "true", "false" or "inherit". Setting a permission to "true" or "false" enables or disables the permission for this group, while leaving it on "inherit" means the group gets the default permission that MediaWiki assigns every group - just think of the default rights of the default group "users" Furthermore: * If the group pre-exists, you'll find above the list a comment box and a "Delete group" button, where you can remove the group, while leaving the comment in the ''GroupPermissionsLog.log'' log file. * Furthermore, if the group pre-exists, the permissions list ends with a comment box and a "Change group permissions" button. Clicking that button will change the group permissions to the set designated in the permissions list. The changes, along with all other group permissions, can be found in the ''/etc/mediawiki/config'' directory in file ''GroupPermissons.php''. Clicking the button will also have resulted in a backup of the ''GroupPermissons.php'' file in that same directory, but named ''GroupPermissons.<timestamp>.php'', e.g. ''GroupPermissions.21012009171713.php''. * If the group name is "new", no "Delete group" button is shown, but the permissions list ends with a comment box and an "Add group" button, which will create the group with the designated name, while leaving the comment in the ''GroupPermissionsLog.log'' log file. Again, the comment is logged, and a backup of the ''GroupPermissons.php'' file is made. 5663c8dc6315c8b62c3a7d74f54b9ffbe64f2f46 2514 2494 2010-03-29T10:07:15Z Saruman! 2 removed spam wikitext text/x-wiki ==Mediawiki Extension: Group Permissions Manager== Sometimes you as a Mediawiki administrator might feel the need to add or remove a group, or edit a groups rights. Unfortunately, there is no such function in the MediaWiki software itself, you'd have to edit the ''LocalSettings.php'' file somehow: [http://www.imdb.com/title/tt0096928/ bogus!] But fortunately, there now exists an extension that adds this functionality. [http://www.imdb.com/title/tt0096928/ Most excellent!] Note: if you want to install the older version 2.00 of this plugin (which is much simpler, both in installation and in functionality), then go to the [[MediaWikiExtension GroupPermissionsManager2.00| Group Permissions Manager 2.00]] page. The instructions on this page are for the 3.2.6 version (build r45886). ==Adding the extension== First, download the latest snapshot of the GroupPermissionsManager extension from here: [http://www.mediawiki.org/wiki/Extension:GroupPermissionsManager Mediawiki Extension:Group Permissions Manager]. It's a single archive with a name that looks like ''GroupPermissionsManager-trunk-r45886.tar.gz''. You can extract it straight into the Debian mediawiki extensions directory ''/usr/share/mediawiki-extensions'', that already exists if you've installed the ''[[Mediawiki-extensions_under_Debian|mediawiki-extensions]]'' package; out comes a little directory structure like this: GroupPermissionsManager |-- plugins | |-- disabled | `-- messages `-- scripts You'll have to make sure all files and directories are owned by ''root'', and that the PHP files cannot be edited by anyone else than ''root''. This will most likely not be the case: as ''root'' run: cd /usr/share/mediawiki-extensions/GroupPermissionsManager chown -R root:root * chmod -R 644 * Now, to make the extension work with Debian, we ''must'' move all files and folders under ''GroupPermissionsManager'' to ''/usr/share/mediawiki-extensions'': cd /usr/share/mediawiki-extensions/GroupPermissionsManager mv scripts .. mv plugins .. mv * .. cd .. rmdir GroupPermissionsManager Next, we have to make a small alteration to ''/usr/share/mediawiki/includes/GlobalFunctions.php'' because there's a bug or shortcoming in MediaWiki 1.12, and that's the version that Lenny uses. The alteration is described in [http://www.mediawiki.org/wiki/Extension:GroupPermissionsManager#Patch a patch prescription on the MediaWiki site], but in essence we add a line after line number 422: the line beginning with "wfRunHooks": <source lang="php"> function wfMsgGetKey( $key, $useDB, $forContent = false, $transform = true ) { global $wgParser, $wgContLang, $wgMessageCache, $wgLang; wfRunHooks( 'NormalizeMessageKey', array( &$key, &$useDB, &$langCode, &$transform ) ); </source> Next, we create a directory where Group Permissions Manager will keep the configuration files. In the Debian style, we need something under ''/etc''. We would ordinarily suggest something under ''/etc/mediawiki-extensions'', but the configuration that the extension manipulates is used by MediaWiki itself. Thus we suggest creating ''/etc/mediawiki/config''. After that, grant the permission to write in this directory to the web server daemon, for Apache2 ''www-data''.<br> Finally, create a symlink to this config directory in the place where GroupPermissionsManager actually ''expects'' it, namely in the directory where the PHP-script itself resides (here: ''/usr/share/mediawiki-extensions/''). All of this can be achieved by following these steps: cd /etc/mediawiki mkdir config chown www-data:www-data config cd /usr/share/mediawiki-extensions ln -s /etc/mediawiki/config Now we can mark the extension ''GroupPermissionsManager.php'' available to MediaWiki: cd /etc/mediawiki-extensions/extensions-available ln -s /usr/share/mediawiki-extensions/GroupPermissionsManager.php Then, enable the extension mwenext GroupPermissionsManager.php This by default adds some extra capabilities to the Mediawiki administrator group "bureaucrat", of which WikiAdmin is a member - and presumably you too. The capabilities are to use a ''Special'' page to create, manage, and remove Wiki groups and their permissions. ==Using the extension== To manage group permissions, you need the following: * your MediaWiki user account needs to be in a MediaWiki group that has been granted the right to use Group Permissions Manager, e.g. ''bureaucrat'' as depicted above; * you must be logged in with that MediaWiki account; * you need to know the name of the group whose permissions you want to manage (or create or delete). In the left navigation area, click on ''Special pages''; scroll down to the section ''Restricted special pages'', you should see an entry ''Manage Group Permissions''. Click it to enter the Manage Group Permissions special page. Here, you'll find just an empty box and a "Go" button. Fill in the name of the group you want to create/manage/delete, and click "Go". You'll find yourself in a long page with group permissions, each of which can be "true", "false" or "inherit". Setting a permission to "true" or "false" enables or disables the permission for this group, while leaving it on "inherit" means the group gets the default permission that MediaWiki assigns every group - just think of the default rights of the default group "users" Furthermore: * If the group pre-exists, you'll find above the list a comment box and a "Delete group" button, where you can remove the group, while leaving the comment in the ''GroupPermissionsLog.log'' log file. * Furthermore, if the group pre-exists, the permissions list ends with a comment box and a "Change group permissions" button. Clicking that button will change the group permissions to the set designated in the permissions list. The changes, along with all other group permissions, can be found in the ''/etc/mediawiki/config'' directory in file ''GroupPermissons.php''. Clicking the button will also have resulted in a backup of the ''GroupPermissons.php'' file in that same directory, but named ''GroupPermissons.<timestamp>.php'', e.g. ''GroupPermissions.21012009171713.php''. * If the group name is "new", no "Delete group" button is shown, but the permissions list ends with a comment box and an "Add group" button, which will create the group with the designated name, while leaving the comment in the ''GroupPermissionsLog.log'' log file. Again, the comment is logged, and a backup of the ''GroupPermissons.php'' file is made. 466e41eb69e3c47b6abc80a1582349e787a3ce31 2526 2514 2010-04-05T06:51:01Z 58.68.82.165 0 Lujxyc <a href="http://bfuoknhjxtrd.com/">bfuoknhjxtrd</a>, [url=http://hzcmcovfmoml.com/]hzcmcovfmoml[/url], [link=http://sazyixyhitjj.com/]sazyixyhitjj[/link], http://gzbziauundpm.com/ wikitext text/x-wiki Lujxyc <a href="http://bfuoknhjxtrd.com/">bfuoknhjxtrd</a>, [url=http://hzcmcovfmoml.com/]hzcmcovfmoml[/url], [link=http://sazyixyhitjj.com/]sazyixyhitjj[/link], http://gzbziauundpm.com/ ==Adding the extension== First, download the latest snapshot of the GroupPermissionsManager extension from here: [http://www.mediawiki.org/wiki/Extension:GroupPermissionsManager Mediawiki Extension:Group Permissions Manager]. It's a single archive with a name that looks like ''GroupPermissionsManager-trunk-r45886.tar.gz''. You can extract it straight into the Debian mediawiki extensions directory ''/usr/share/mediawiki-extensions'', that already exists if you've installed the ''[[Mediawiki-extensions_under_Debian|mediawiki-extensions]]'' package; out comes a little directory structure like this: GroupPermissionsManager |-- plugins | |-- disabled | `-- messages `-- scripts You'll have to make sure all files and directories are owned by ''root'', and that the PHP files cannot be edited by anyone else than ''root''. This will most likely not be the case: as ''root'' run: cd /usr/share/mediawiki-extensions/GroupPermissionsManager chown -R root:root * chmod -R 644 * Now, to make the extension work with Debian, we ''must'' move all files and folders under ''GroupPermissionsManager'' to ''/usr/share/mediawiki-extensions'': cd /usr/share/mediawiki-extensions/GroupPermissionsManager mv scripts .. mv plugins .. mv * .. cd .. rmdir GroupPermissionsManager Next, we have to make a small alteration to ''/usr/share/mediawiki/includes/GlobalFunctions.php'' because there's a bug or shortcoming in MediaWiki 1.12, and that's the version that Lenny uses. The alteration is described in [http://www.mediawiki.org/wiki/Extension:GroupPermissionsManager#Patch a patch prescription on the MediaWiki site], but in essence we add a line after line number 422: the line beginning with "wfRunHooks": <source lang="php"> function wfMsgGetKey( $key, $useDB, $forContent = false, $transform = true ) { global $wgParser, $wgContLang, $wgMessageCache, $wgLang; wfRunHooks( 'NormalizeMessageKey', array( &$key, &$useDB, &$langCode, &$transform ) ); </source> Next, we create a directory where Group Permissions Manager will keep the configuration files. In the Debian style, we need something under ''/etc''. We would ordinarily suggest something under ''/etc/mediawiki-extensions'', but the configuration that the extension manipulates is used by MediaWiki itself. Thus we suggest creating ''/etc/mediawiki/config''. After that, grant the permission to write in this directory to the web server daemon, for Apache2 ''www-data''.<br> Finally, create a symlink to this config directory in the place where GroupPermissionsManager actually ''expects'' it, namely in the directory where the PHP-script itself resides (here: ''/usr/share/mediawiki-extensions/''). All of this can be achieved by following these steps: cd /etc/mediawiki mkdir config chown www-data:www-data config cd /usr/share/mediawiki-extensions ln -s /etc/mediawiki/config Now we can mark the extension ''GroupPermissionsManager.php'' available to MediaWiki: cd /etc/mediawiki-extensions/extensions-available ln -s /usr/share/mediawiki-extensions/GroupPermissionsManager.php Then, enable the extension mwenext GroupPermissionsManager.php This by default adds some extra capabilities to the Mediawiki administrator group "bureaucrat", of which WikiAdmin is a member - and presumably you too. The capabilities are to use a ''Special'' page to create, manage, and remove Wiki groups and their permissions. ==Using the extension== To manage group permissions, you need the following: * your MediaWiki user account needs to be in a MediaWiki group that has been granted the right to use Group Permissions Manager, e.g. ''bureaucrat'' as depicted above; * you must be logged in with that MediaWiki account; * you need to know the name of the group whose permissions you want to manage (or create or delete). In the left navigation area, click on ''Special pages''; scroll down to the section ''Restricted special pages'', you should see an entry ''Manage Group Permissions''. Click it to enter the Manage Group Permissions special page. Here, you'll find just an empty box and a "Go" button. Fill in the name of the group you want to create/manage/delete, and click "Go". You'll find yourself in a long page with group permissions, each of which can be "true", "false" or "inherit". Setting a permission to "true" or "false" enables or disables the permission for this group, while leaving it on "inherit" means the group gets the default permission that MediaWiki assigns every group - just think of the default rights of the default group "users" Furthermore: * If the group pre-exists, you'll find above the list a comment box and a "Delete group" button, where you can remove the group, while leaving the comment in the ''GroupPermissionsLog.log'' log file. * Furthermore, if the group pre-exists, the permissions list ends with a comment box and a "Change group permissions" button. Clicking that button will change the group permissions to the set designated in the permissions list. The changes, along with all other group permissions, can be found in the ''/etc/mediawiki/config'' directory in file ''GroupPermissons.php''. Clicking the button will also have resulted in a backup of the ''GroupPermissons.php'' file in that same directory, but named ''GroupPermissons.<timestamp>.php'', e.g. ''GroupPermissions.21012009171713.php''. * If the group name is "new", no "Delete group" button is shown, but the permissions list ends with a comment box and an "Add group" button, which will create the group with the designated name, while leaving the comment in the ''GroupPermissionsLog.log'' log file. Again, the comment is logged, and a backup of the ''GroupPermissons.php'' file is made. f246971f998d3c9e6835a6be7edd095ca28154e8 2560 2526 2010-04-06T18:50:10Z Saruman! 2 Undo spamming wikitext text/x-wiki ==Mediawiki Extension: Group Permissions Manager== Sometimes you as a Mediawiki administrator might feel the need to add or remove a group, or edit a groups rights. Unfortunately, there is no such function in the MediaWiki software itself, you'd have to edit the ''LocalSettings.php'' file somehow: [http://www.imdb.com/title/tt0096928/ bogus!] But fortunately, there now exists an extension that adds this functionality. [http://www.imdb.com/title/tt0096928/ Most excellent!] Note: if you want to install the older version 2.00 of this plugin (which is much simpler, both in installation and in functionality), then go to the [[MediaWikiExtension GroupPermissionsManager2.00| Group Permissions Manager 2.00]] page. The instructions on this page are for the 3.2.6 version (build r45886). ==Adding the extension== First, download the latest snapshot of the GroupPermissionsManager extension from here: [http://www.mediawiki.org/wiki/Extension:GroupPermissionsManager Mediawiki Extension:Group Permissions Manager]. It's a single archive with a name that looks like ''GroupPermissionsManager-trunk-r45886.tar.gz''. You can extract it straight into the Debian mediawiki extensions directory ''/usr/share/mediawiki-extensions'', that already exists if you've installed the ''[[Mediawiki-extensions_under_Debian|mediawiki-extensions]]'' package; out comes a little directory structure like this: GroupPermissionsManager |-- plugins | |-- disabled | `-- messages `-- scripts You'll have to make sure all files and directories are owned by ''root'', and that the PHP files cannot be edited by anyone else than ''root''. This will most likely not be the case: as ''root'' run: cd /usr/share/mediawiki-extensions/GroupPermissionsManager chown -R root:root * chmod -R 644 * Now, to make the extension work with Debian, we ''must'' move all files and folders under ''GroupPermissionsManager'' to ''/usr/share/mediawiki-extensions'': cd /usr/share/mediawiki-extensions/GroupPermissionsManager mv scripts .. mv plugins .. mv * .. cd .. rmdir GroupPermissionsManager Next, we have to make a small alteration to ''/usr/share/mediawiki/includes/GlobalFunctions.php'' because there's a bug or shortcoming in MediaWiki 1.12, and that's the version that Lenny uses. The alteration is described in [http://www.mediawiki.org/wiki/Extension:GroupPermissionsManager#Patch a patch prescription on the MediaWiki site], but in essence we add a line after line number 422: the line beginning with "wfRunHooks": <source lang="php"> function wfMsgGetKey( $key, $useDB, $forContent = false, $transform = true ) { global $wgParser, $wgContLang, $wgMessageCache, $wgLang; wfRunHooks( 'NormalizeMessageKey', array( &$key, &$useDB, &$langCode, &$transform ) ); </source> Next, we create a directory where Group Permissions Manager will keep the configuration files. In the Debian style, we need something under ''/etc''. We would ordinarily suggest something under ''/etc/mediawiki-extensions'', but the configuration that the extension manipulates is used by MediaWiki itself. Thus we suggest creating ''/etc/mediawiki/config''. After that, grant the permission to write in this directory to the web server daemon, for Apache2 ''www-data''.<br> Finally, create a symlink to this config directory in the place where GroupPermissionsManager actually ''expects'' it, namely in the directory where the PHP-script itself resides (here: ''/usr/share/mediawiki-extensions/''). All of this can be achieved by following these steps: cd /etc/mediawiki mkdir config chown www-data:www-data config cd /usr/share/mediawiki-extensions ln -s /etc/mediawiki/config Now we can mark the extension ''GroupPermissionsManager.php'' available to MediaWiki: cd /etc/mediawiki-extensions/extensions-available ln -s /usr/share/mediawiki-extensions/GroupPermissionsManager.php Then, enable the extension mwenext GroupPermissionsManager.php This by default adds some extra capabilities to the Mediawiki administrator group "bureaucrat", of which WikiAdmin is a member - and presumably you too. The capabilities are to use a ''Special'' page to create, manage, and remove Wiki groups and their permissions. ==Using the extension== To manage group permissions, you need the following: * your MediaWiki user account needs to be in a MediaWiki group that has been granted the right to use Group Permissions Manager, e.g. ''bureaucrat'' as depicted above; * you must be logged in with that MediaWiki account; * you need to know the name of the group whose permissions you want to manage (or create or delete). In the left navigation area, click on ''Special pages''; scroll down to the section ''Restricted special pages'', you should see an entry ''Manage Group Permissions''. Click it to enter the Manage Group Permissions special page. Here, you'll find just an empty box and a "Go" button. Fill in the name of the group you want to create/manage/delete, and click "Go". You'll find yourself in a long page with group permissions, each of which can be "true", "false" or "inherit". Setting a permission to "true" or "false" enables or disables the permission for this group, while leaving it on "inherit" means the group gets the default permission that MediaWiki assigns every group - just think of the default rights of the default group "users" Furthermore: * If the group pre-exists, you'll find above the list a comment box and a "Delete group" button, where you can remove the group, while leaving the comment in the ''GroupPermissionsLog.log'' log file. * Furthermore, if the group pre-exists, the permissions list ends with a comment box and a "Change group permissions" button. Clicking that button will change the group permissions to the set designated in the permissions list. The changes, along with all other group permissions, can be found in the ''/etc/mediawiki/config'' directory in file ''GroupPermissons.php''. Clicking the button will also have resulted in a backup of the ''GroupPermissons.php'' file in that same directory, but named ''GroupPermissons.<timestamp>.php'', e.g. ''GroupPermissions.21012009171713.php''. * If the group name is "new", no "Delete group" button is shown, but the permissions list ends with a comment box and an "Add group" button, which will create the group with the designated name, while leaving the comment in the ''GroupPermissionsLog.log'' log file. Again, the comment is logged, and a backup of the ''GroupPermissons.php'' file is made. 466e41eb69e3c47b6abc80a1582349e787a3ce31 0 1441 2498 2373 2010-03-23T16:04:00Z Kimberly 15 /* Routes under Debian */ wikitext text/x-wiki ==Routes under Debian== When you need to add a networking route, there generally are two ways to do it: # manually adding a route at the command prompt: this means that the machine will "understand" the route for as long as it is running. However, when you reboot the machine, it will have "forgotten" the route. This is called a non-persistent route. # adding a route to the networking configuration files, so that it will be in place regardless of reboots or network restarts. This is called a persistent route. [http://www.bestessays.com buy papers] ===Manipulating non-persistent routes=== From the days of yore, the venerable ''route'' command enables us to view, add, change and delete routes. Its most known use is for printing the current routing table: #route -n Kernel IP routing table Destination Gateway Genmask Flags Metric Ref Use Iface 192.168.70.0 212.214.172.50 255.255.255.0 UG 0 0 0 eth1 192.168.67.0 * 255.255.255.0 U 0 0 0 eth0 212.214.172.0 * 255.255.255.0 U 0 0 0 eth1 default 212.214.172.1 0.0.0.0 UG 0 0 0 eth1 The addition of -n makes sure the ''route'' command does not try to substitute DNS names for IP addresses it knows. The second most used incarnation of ''route'' lies in the addition of a route, as has happened in the previous example. The route was added to the routing table using something like this: #route add -net 192.168.70.0 netmask 255.255.255.0 gw 212.214.172.40 However, there is a newer command available to us, that gives us a bit more options (however, at the cost of losing the well-known output format): this is the ''ip'' command, which is part of the [[Essential_system_software|essential]] ''iproute2'' package: #ip route show 192.168.70.0/24 via 212.214.172.50 dev eth1 src 192.168.67.10 192.168.67.0/24 dev eth0 proto kernel scope link src 192.168.67.10 212.214.172.0/24 dev eth1 proto kernel scope link src 212.214.172.50 default via 212.214.172.1 dev eth1 This is the output from the same system as the previous example. However, we see something interesting here: "ip" is capable of adding extra information to the route, like the first line shows (it's using "via"). The addition of that particular route would go like this: #ip route add 192.168.70.0/24 via 212.214.172.50 src 192.168.67.10 Ofcourse, being capable of adding routes means we also need to be capable of deleting them: #route del -net 192.168.70.0 netmask 255.255.255.0 #ip route del 192.168.70.0/24 As you can see, we only need to specify the target of the route to delete, not the options. ===Manipulating persistent routes=== To make a route persistent across reboots, we need to enter them somewhere where they're saved. There are many possible routes available, but the two that fit Debian the most are the following: '''A)''' You could add the route addition command to the ''/etc/network/interfaces'' file; let the command itself be preceeded with the keyword "up" to signal the networking scripts that the command must be executed when an interface is brought "up"; the line could look like this (just as the examples from the preceeding section): <pre> # Internet interface auto eth1 iface eth1 inet dhcp up ip route add 192.168.70.0/24 via 212.214.172.50 src 192.168.67.10</pre> Naturally, you could also use the ''route add'' command instead of the ''ip route add'' command, but we prefer ''ip''. Note: it matters --where-- in the ''interfaces'' file you put this line: it should be put in the same stanza as the interface it operates on. In this example, the external interface of the server is 212.214.172.50, which belongs with interface ''eth1''. Therefore, the "up" line appears in the stanza for ''eth1''. '''B)''' You could create a script that sets the route(s), and put it in the directory ''/etc/network/if-up.d''. Since all scripts that reside there get called when any interface goes "up", your route setting script would be called when ''any'' interface comes up, including ''lo''. This in turn means that a script for setting a route that belongs with a particular interface, should check on invocation which is the interface that goes up. At this moment in time, we don't employ any such script, so no example here, but if you look at the existing scripts in ''/etc/network/if-up.d'' you'll see how other programmers have done this. ==DNS resolution under Debian== One headache you might encounter when configuring a Debian server is how to let every program know how to resolve DNS names. Before a program can connect to an external network resource (say, for example, a web server), it must have a means of converting DNS names (e.g. www.saruman.biz) into the corresponding IP addresses (e.g. 192.168.67.10). This process is called "name resolution". The need for name resolution means that every program needs to know about the available means by which to do this name resolution. From the good old days comes the configuration file ''resolv.conf'', normally found in ''/etc''. It contains information about the nameservers to be used by the system, be they actual servers or lookup files. However, more and more programs have the need to dynamically modify the ''resolv.conf'' configuration file. This means that frequently they step on each other, and the ''resolv.conf'' file can become out-of-sync. The ''resolvconf'' program addresses this problem. It acts as an intermediary between programs that supply nameserver information (e.g. DHCP clients) and programs that use nameserver information (e.g. resolver). When ''resolvconf'' is properly installed, the file ''/etc/resolv.conf'' is replaced by a symbolic link to ''/etc/resolvconf/run/resolv.conf'', and any resolver thus uses the dynamically generated resolver configuration file at ''/etc/resolvconf/run/resolv.conf''. The ''resolvconf'' program is only necessary when a system has multiple programs that need to dynamically modify the nameserver information. In a simple system where the nameservers do not change often or are only changed by one program, the standard ''/etc/resolv.conf'' configuration file is adequate. == VLANs under Debian == Debian can support network traffic over VLANs (ethernet 802.1q) - and we don't mean the normal "untagged" network ports (hey, VLANs are transparent that way, anybody and anything can use untagged network ports). No, we mean that Debian can accept network traffic in from, and send traffic out to, a VLAN tagged switchport. Suppose you have a layer 2 switch with support for 802.1q VLANs, and want to route traffic from one VLAN to another. For this you can use a Debian router with a single network interface, using VLAN support (this is called "router on a stick" because the routing takes place over only one cable). First, as root, run apt-get install vlan modprobe 8021q The first line is to install the vlan package, which contains all necessary tools to create and manipulate VLAN-enabled network ports. The second line loads the module that enables VLAN tagging for your ethernet network cards. Note: if you don't have the stock Debian kernel, but compiled your own, then you might have chosen not to compile the 8021q module. In that case, compile the module. Also note, that if you've compiled the 8021q code into the kernel itself, then you don't need to load the module and that second line is unnecessary for you. You'll find this kernel compile option (depending on your kernel version) under Networking -> Networking Options -> "802.1Q VLAN Support". This option has been in the Linux kernel since version 2.4.14. ifconfig eth0 down vconfig add eth0 2 vconfig add eth0 3 The first command brings down your network on eth0 (not the thing to do if you're working remote, then :-). The next two commands create two virtual interfaces ''eth0.2'' and ''eth0.3'', which have VLAN tags 2 and 3 (don't use VLAN tag 1 if you can help it; on many devices VLAN1 is a special hardware management VLAN). The virtual interfaces run on top of your ''eth0'' interface.<br> Now because your VLAN interfaces run on top of ''eth0'', you've got to bring ''eth0'' itself up, even if you don't want to run network traffic over it. Furthermore, you've got to configure the two virtual interfaces you've created. Let's suppose you want to run IP subnet 192.168.1.0/24 on VLAN2, and 192.168.2.0/24 on VLAN3. You can do so with ifconfig eth0 0.0.0.0 up ifconfig eth0.2 192.168.1.1 broadcast 192.168.1.255 netmask 255.255.255.0 up ifconfig eth0.3 192.168.2.1 broadcast 192.168.2.255 netmask 255.255.255.0 up Now that you've this done, you must still configure one of your switch ports to belong to VLAN 2 and 3 at the same time (tagged port), and connect ''eth0'' from your linux box to that port. This enables your box to run network traffic on both VLANs. To round things up: if you haven't yet enabled forwarding, you can do so now. Furthermore, you might wish to augment your route table so that the routing engine in your server knows how to handle packets that it needs to forward from one VLAN to the other: echo 1 > /proc/sys/net/ipv4/ip_forward route add -net 10.1.1.0 netmask 255.255.255.0 gw eth0.2 route add -net 10.1.2.0 netmask 255.255.255.0 gw eth0.3 This is it; nothing to it, right? =Tunneling under Debian= Being a Linux distribution, Debian gives you all the networking power of that platform. One of the powerful features of Linux networking is the ease with which you can create network tunnels. Many possibilities exist; in this wiki we've documented the following: * [[IPsec site-to-site tunnel]] with which you can connect two networks, so that machines in both networks can reach machines in the other network 89913c3e72b987dd12c7c042b9e02c56b3e2ceb0 2511 2498 2010-03-29T10:03:46Z Saruman! 2 Undo spamming wikitext text/x-wiki ==Routes under Debian== When you need to add a networking route, there generally are two ways to do it: # manually adding a route at the command prompt: this means that the machine will "understand" the route for as long as it is running. However, when you reboot the machine, it will have "forgotten" the route. This is called a non-persistent route. # adding a route to the networking configuration files, so that it will be in place regardless of reboots or network restarts. This is called a persistent route. ===Manipulating non-persistent routes=== From the days of yore, the venerable ''route'' command enables us to view, add, change and delete routes. Its most known use is for printing the current routing table: #route -n Kernel IP routing table Destination Gateway Genmask Flags Metric Ref Use Iface 192.168.70.0 212.214.172.50 255.255.255.0 UG 0 0 0 eth1 192.168.67.0 * 255.255.255.0 U 0 0 0 eth0 212.214.172.0 * 255.255.255.0 U 0 0 0 eth1 default 212.214.172.1 0.0.0.0 UG 0 0 0 eth1 The addition of -n makes sure the ''route'' command does not try to substitute DNS names for IP addresses it knows. The second most used incarnation of ''route'' lies in the addition of a route, as has happened in the previous example. The route was added to the routing table using something like this: #route add -net 192.168.70.0 netmask 255.255.255.0 gw 212.214.172.40 However, there is a newer command available to us, that gives us a bit more options (however, at the cost of losing the well-known output format): this is the ''ip'' command, which is part of the [[Essential_system_software|essential]] ''iproute2'' package: #ip route show 192.168.70.0/24 via 212.214.172.50 dev eth1 src 192.168.67.10 192.168.67.0/24 dev eth0 proto kernel scope link src 192.168.67.10 212.214.172.0/24 dev eth1 proto kernel scope link src 212.214.172.50 default via 212.214.172.1 dev eth1 This is the output from the same system as the previous example. However, we see something interesting here: "ip" is capable of adding extra information to the route, like the first line shows (it's using "via"). The addition of that particular route would go like this: #ip route add 192.168.70.0/24 via 212.214.172.50 src 192.168.67.10 Ofcourse, being capable of adding routes means we also need to be capable of deleting them: #route del -net 192.168.70.0 netmask 255.255.255.0 #ip route del 192.168.70.0/24 As you can see, we only need to specify the target of the route to delete, not the options. ===Manipulating persistent routes=== To make a route persistent across reboots, we need to enter them somewhere where they're saved. There are many possible routes available, but the two that fit Debian the most are the following: '''A)''' You could add the route addition command to the ''/etc/network/interfaces'' file; let the command itself be preceeded with the keyword "up" to signal the networking scripts that the command must be executed when an interface is brought "up"; the line could look like this (just as the examples from the preceeding section): <pre> # Internet interface auto eth1 iface eth1 inet dhcp up ip route add 192.168.70.0/24 via 212.214.172.50 src 192.168.67.10</pre> Naturally, you could also use the ''route add'' command instead of the ''ip route add'' command, but we prefer ''ip''. Note: it matters --where-- in the ''interfaces'' file you put this line: it should be put in the same stanza as the interface it operates on. In this example, the external interface of the server is 212.214.172.50, which belongs with interface ''eth1''. Therefore, the "up" line appears in the stanza for ''eth1''. '''B)''' You could create a script that sets the route(s), and put it in the directory ''/etc/network/if-up.d''. Since all scripts that reside there get called when any interface goes "up", your route setting script would be called when ''any'' interface comes up, including ''lo''. This in turn means that a script for setting a route that belongs with a particular interface, should check on invocation which is the interface that goes up. At this moment in time, we don't employ any such script, so no example here, but if you look at the existing scripts in ''/etc/network/if-up.d'' you'll see how other programmers have done this. ==DNS resolution under Debian== One headache you might encounter when configuring a Debian server is how to let every program know how to resolve DNS names. Before a program can connect to an external network resource (say, for example, a web server), it must have a means of converting DNS names (e.g. www.saruman.biz) into the corresponding IP addresses (e.g. 192.168.67.10). This process is called "name resolution". The need for name resolution means that every program needs to know about the available means by which to do this name resolution. From the good old days comes the configuration file ''resolv.conf'', normally found in ''/etc''. It contains information about the nameservers to be used by the system, be they actual servers or lookup files. However, more and more programs have the need to dynamically modify the ''resolv.conf'' configuration file. This means that frequently they step on each other, and the ''resolv.conf'' file can become out-of-sync. The ''resolvconf'' program addresses this problem. It acts as an intermediary between programs that supply nameserver information (e.g. DHCP clients) and programs that use nameserver information (e.g. resolver). When ''resolvconf'' is properly installed, the file ''/etc/resolv.conf'' is replaced by a symbolic link to ''/etc/resolvconf/run/resolv.conf'', and any resolver thus uses the dynamically generated resolver configuration file at ''/etc/resolvconf/run/resolv.conf''. The ''resolvconf'' program is only necessary when a system has multiple programs that need to dynamically modify the nameserver information. In a simple system where the nameservers do not change often or are only changed by one program, the standard ''/etc/resolv.conf'' configuration file is adequate. == VLANs under Debian == Debian can support network traffic over VLANs (ethernet 802.1q) - and we don't mean the normal "untagged" network ports (hey, VLANs are transparent that way, anybody and anything can use untagged network ports). No, we mean that Debian can accept network traffic in from, and send traffic out to, a VLAN tagged switchport. Suppose you have a layer 2 switch with support for 802.1q VLANs, and want to route traffic from one VLAN to another. For this you can use a Debian router with a single network interface, using VLAN support (this is called "router on a stick" because the routing takes place over only one cable). First, as root, run apt-get install vlan modprobe 8021q The first line is to install the vlan package, which contains all necessary tools to create and manipulate VLAN-enabled network ports. The second line loads the module that enables VLAN tagging for your ethernet network cards. Note: if you don't have the stock Debian kernel, but compiled your own, then you might have chosen not to compile the 8021q module. In that case, compile the module. Also note, that if you've compiled the 8021q code into the kernel itself, then you don't need to load the module and that second line is unnecessary for you. You'll find this kernel compile option (depending on your kernel version) under Networking -> Networking Options -> "802.1Q VLAN Support". This option has been in the Linux kernel since version 2.4.14. ifconfig eth0 down vconfig add eth0 2 vconfig add eth0 3 The first command brings down your network on eth0 (not the thing to do if you're working remote, then :-). The next two commands create two virtual interfaces ''eth0.2'' and ''eth0.3'', which have VLAN tags 2 and 3 (don't use VLAN tag 1 if you can help it; on many devices VLAN1 is a special hardware management VLAN). The virtual interfaces run on top of your ''eth0'' interface.<br> Now because your VLAN interfaces run on top of ''eth0'', you've got to bring ''eth0'' itself up, even if you don't want to run network traffic over it. Furthermore, you've got to configure the two virtual interfaces you've created. Let's suppose you want to run IP subnet 192.168.1.0/24 on VLAN2, and 192.168.2.0/24 on VLAN3. You can do so with ifconfig eth0 0.0.0.0 up ifconfig eth0.2 192.168.1.1 broadcast 192.168.1.255 netmask 255.255.255.0 up ifconfig eth0.3 192.168.2.1 broadcast 192.168.2.255 netmask 255.255.255.0 up Now that you've this done, you must still configure one of your switch ports to belong to VLAN 2 and 3 at the same time (tagged port), and connect ''eth0'' from your linux box to that port. This enables your box to run network traffic on both VLANs. To round things up: if you haven't yet enabled forwarding, you can do so now. Furthermore, you might wish to augment your route table so that the routing engine in your server knows how to handle packets that it needs to forward from one VLAN to the other: echo 1 > /proc/sys/net/ipv4/ip_forward route add -net 10.1.1.0 netmask 255.255.255.0 gw eth0.2 route add -net 10.1.2.0 netmask 255.255.255.0 gw eth0.3 This is it; nothing to it, right? =Tunneling under Debian= Being a Linux distribution, Debian gives you all the networking power of that platform. One of the powerful features of Linux networking is the ease with which you can create network tunnels. Many possibilities exist; in this wiki we've documented the following: * [[IPsec site-to-site tunnel]] with which you can connect two networks, so that machines in both networks can reach machines in the other network fbb1f6124f455aaf51277de1963ac0019da1741f 4 1599 2499 2010-03-23T16:04:32Z Kimberly 15 Created page with '[http://www.bestessays.com buy papers]' wikitext text/x-wiki [http://www.bestessays.com buy papers] 80ff26483f03dd59d21683e156f0929e8ebe5e23 2512 2499 2010-03-29T10:04:31Z Saruman! 2 removed spam wikitext text/x-wiki Currently no events are scheduled 93f7d77fecc7b0d2f5e61fbfc116631b6d9221aa 0 1 2501 2278 2010-03-24T18:49:10Z Saruman! 2 added link to dya|info wikitext text/x-wiki <big>'''Welcome to SaruWiki.'''</big> This Wiki is intended to document bits and bobs about [http://www.kernel.org/ Linux] (and some Unix) in general, and [http://www.debian.org Debian] in particular. In it, [[SaruWiki:About|we]] wish to collect the tips and tricks of both [[SaruWiki:About|our own team of Linux admins]] and those of other interested users. If you are interested in my work on [http://www.dya.info DYA|Infrastructure], please visit the [https://dya-knowledge.sogeti.nl/ SmartMart demo site]. Consult the [http://meta.wikimedia.org/wiki/Help:Contents User's Guide] for information on using this wiki's software. <big>NOTE:</big> '''you must confirm edits''' when you're not logged in with a user account. Thanks to the Mediawiki ConfirmEdit extension we've cut our wikispam considerably. Sorry to make you anonymous contributors jump through this little hoop for every edit, but there you are. ---- <big>'''Main Content'''</big> * Setting up a [[Debian Lenny base server]] is a howto on the installation of a very basic Linux box under Lenny (it's actually not even a server yet). * Using ''md'' for [[software-based RAID]] contains our ideas and observations on redundancy. * The use of [[APT and aptitude]] is crucial to the concept of a Debian machine. * [[Roll your own kernel]] discusses the pros and cons of compiling your own kernel, and how to do it. * [[Essential system software]] lists all (sets of) packages that we deem, well, essential. * [[Apache2 and PHP5]] are essential packages if you want to light your own little [[LAMP]]. * [[Pluggable Authentication Modules (PAM)]] is a great way to secure your server and arrange logins - if you get to understand them * [[Certificate fundamentals | The "certificates" section]] explains how you create your own Certificate Authority (CA) and the neat things you can do with it. * [[Database 101]] introduces you to MySQL. * [[OpenLDAP]] is a rudimentary howto about getting OpenLDAP to be your central user repository. * The [[Installing SaMBa with OpenLDAP support | SaMBa section]] explains how to install SaMBa with OpenLDAP as user backend. * [[Add an X11 server]] to your server, if you need one. * Of course we have a [[e-mail server section]], where we focus on Postfix and virtual mail domains, and add in a whiff of MySQL and OpenLDAP. * The [[Asterisk section]] is about all things re: telephony on Debian Lenny. * The [[system boot procedure]] section explains what we can customise in the standard ways Debian boots. * The [[networking section]] treats subjects like setting persistent routes. * The [[firewall section]] is where we discuss "IPtables" (netfilter) and how we use it for firewalling. * The [[native IPsec tunnel]] section describes how to configure an IPsec tunnel. * [[Hardware monitoring]] is important for your server's health and reliability. * [[Vmware_server|VMware Server basics]] gives some pointers on how to install VMware Server on a Debian server box. * Make your server a [[Microsoft PPTP server | Microsoft client compatible VPN Server ]]. * How to install [[Mediawiki Installation | Mediawiki]] on your Debian server - like what you're looking at now. If you'd like to create a new page, please log in and go ahead: <inputbox> type=create </inputbox> ---- '''Note''': the Wiki admins reserve the right to edit or remove any content they feel is not suitable for this site, not relevant, (too) inaccurate or otherwise not in line with the intentions and spirit of the admin team. ---- <websiteFrame> website=http://www.google.com/talk/service/badge/Show?tk&#61;z01q6amlqld8jocej2ca891jl9dunqqra83nhehaoqpednb5skkur0fv70jsuavce4ii9ms5e9afdr8qmpsc1d9upni4jom8g1em3p1cvq1p5eo1ugv162fosgprdv867iuememlcogfle8n3dmcf97durjld85avnh8k5lm1&amp;w=200&amp;h=60 border=0 height=60 width=200 name=GoogleChatwithSaruman! allowtransparency=true </websiteFrame> ed5530b1f72e54a2e9a0f1b771ee258e9018340a 1 1607 2559 2010-04-06T18:48:31Z Saruman! 2 recreated after spamwave wikitext text/x-wiki You are most welcome to discuss this wiki, but please keep the discussion relevant --[[User:Saruman!|Saruman!]] 10:02, 29 March 2010 (UTC) bd6c821c17e08fdda5e19137dce60556925c398f 0 1592 2564 2462 2010-05-06T21:23:07Z Insomnia 3 wikitext text/x-wiki == IMP == With Debian Lenny come standard, stable applications. The [http://www.horde.org/imp/ IMP webmail application] that is packaged for Debian is version 4.2. The quickest way to install IMP is apt-get install imp4 With both ''horde3'' and a mailserver (e.g. [[E-mail_server_section|Postfix]]) completely installed and configured, no extra packages will get installed. Before you configure IMP, you need to prepare file permissions for web configuration (this is a recurring theme for any horde3 application): touch /etc/horde/imp4/conf.bak.php chmod 777 /etc/horde/imp4/conf*.php [[Image:Horde3-imp-setup-1.PNG|thumb|300px|Horde IPM4 configuration screen 1]]Now you can log in to horde3 web interface as a user with administrative rights. In the Horde3 tree view, choose Administration -> Setup -> '' Mail (imp) H3 (4.2)''' (see picture). This results in a configuration generation screen with something like 8 tabs; you could safely go with the defaults, but for lots of interesting special features you'll have to actively make a selection. Funny enough you do NOT select your mailserver(s) in this menu; that's left to manually editing another file (see further down). Now generate your configuration. When you're done, you can change the permissions back for safety: chmod 644 /etc/horde/imp4/conf.php chmod 600 /etc/horde/imp4/conf.bak.php Note that this also prevents you from changing the configuration with the web interface in the future. When you want to do that, you'll have to reset the permissions for the ''conf*.php'' files to 777, generate a new configuration, and then set the permissions back. Note that if you DO NOT change the permissions to 644/600, then your IMP client will still run flawlessly. However, you now run a serious risk of a malicious web client altering your web mail configuration. Time to specify your mail server(s) in ''/etc/horde/imp4/servers.php'' file. Depending on your mail server setup, your settings can be something like $servers['imap'] = array( 'name' => 'IMAP Server', 'server' => 'localhost', 'hordeauth' => 'full', 'protocol' => 'imap/notls', 'port' => 143, 'maildomain' => 'saruman.biz', 'smtphost' => 'localhost', 'smtpport' => 25, 'realm' => 'sample.com', 'preferred' => '', ); When you are ready, enable IMP in the file ''/etc/horde/horde3/registry.php'' and verify if all is right. Yes, you read well, you MUST enable manually module in registry.php file after configuration! $this->applications['imp'] = array( 'fileroot' => '/usr/share/horde3/lib' . '/../imp', 'webroot' => $this->applications['horde']['webroot'] . '/imp', 'name' => _("Mail"), 'status' => 'active', 'provides' => array('mail', 'contacts/favouriteRecipients') ); Change the status from inactive to active == Ingo == #apt-get install ingo1 Register the application by editing /etc/horde/horde3/registry.php Find the ingo stanza and change inactive to active $this->applications['ingo'] = array( 'fileroot' => '/usr/share/horde3/lib' . '/../ingo', 'webroot' => $this->applications['horde']['webroot'] . '/ingo', 'name' => _("Filters"), 'status' => 'active', Creating the database table Login to the mysql database mysql> source /usr/share/doc/ingo1/examples/scripts/sql/ingo.sql change the group so apache can change the files #chmod 774 /etc/horde/ingo1 Now login as a admin user in you're horde website. Goto administration - setup and klik on "Filters (ingo)" Change the database to MYsql. Save the configuration and make you're rules 4d52956db52cc98b8d88f794321608013a5cc696 0 1480 2566 2441 2010-05-16T18:38:38Z Saruman! 2 /* DAHDI */ updated installation of driver wikitext text/x-wiki = Asterisk basic configuration principles = In this section we'll have a look at the basic configuration of an Asterisk PBX. Contrary to the TFOT-book, we'll be looking at it from the theory side, and from there go to an example configuration. For this example configuration, we'll start from a server with on the "outside" a POTS line and a SIP account with an Internet provider, and on the "inside" two analogue telephones and a SIP softphone. Our goal is to let the PBX behave as if we don't even have a PBX, but a standard home situation: for an incoming call, all phones ring; and every internal phone can make calls to the outside. = Asterisk channel configuration basics = The first thing to realise is that Asterisk sees each connected telephony device as a "channel". But what is a Channel? To Asterisk, a channel is a connection which brings in a call to the Asterisk PBX. A channel could be a connection to an ordinary telephone handset or an ordinary telephone line, or to a logical call (like an Internet phone call). Asterisk makes no distinction between "FXO" and "FXS" style channels (that is, it doesn't distinguish between telephone lines and telephones). Every call is placed or received on a distinct channel. The second thing to realise, is that every type of device attached to the Asterisk PBX have their own specific configuration files. Correctly setting up each (set of) telephony devices makes them available in our Asterisk PBX as channels. Thus, the device configuration files serve as a kind of abstraction layer, and simplify our final Asterisk configuration by putting "channel-specific" information in separate files. If you've followed the previous Asterisk sections in this Wiki, or followed the first four chapters of the TFOT-book, then you've encountered the following configuration files: * ''zaptel.conf'' - in this file, you can set up the most basic parameters for your Zap-type hardware channels, most notably Digium telephony cards. You're configuring the hardware itself, via its driver. You could think of this file as belonging to the hardware, not Asterisk. If you'd have other software on your machine besides Asterisk that could make use of your telephony hardware, then that'd be influenced as well when you change ''zaptel.conf''. * ''zapata.conf'' (and possibly ''zapata-channels.conf'' if you're on Debian) - this file handles the Asterisk-specific configuration of the hardware telephony channels. It thus "sets up the Zap channels" that Asterisk sees - for incoming and outgoing calls. All parameters that set up the channel are specified here. * ''vpb.conf'' - this file is used to configure [http://www.voicetronix.com/ Voicetronix] cards with Asterisk. If you've a Voicetronix card in use, then you've also installed the Voicetronix drivers. This makes the card(s) useable under Linux. But to have Asterisk use the card(s), you need this ''vpb.conf'' file. It thus serves the same purpose as ''zapata.conf''. * ''sip.conf'' - this file contains all information on all SIP devices that we want to connect to our Asterisk server; be it one or more SIP accounts with Internet providers, or SIP capable telephones (hardware or software). When ''sip.conf'' has been set up correctly, we can refer to a SIP device by a friendly name like [1000] or [Jane]. * ''iax.conf'' - this file is just the same as the ''sip.conf'' file, only it handles devices that talk IAX2 protocol instead of the SIP protocol. These five files define all channels that our basic Asterisk PBX might handle (well, it won't even handle the last one, since we're not connecting any other Asterisk boxes or IAX-(soft)phones to our PBX, and it won't handle the third one if you don't have a Voicetronix card). As a reference, we're going to list the contents of four example files, and explain what they do in the way of preparing channels for our simple Asterisk server.: ==zaptel.conf== # Autogenerated by ./genzaptelconf -- do not hand edit # Zaptel Configuration File # # This file is parsed by the Zaptel Configurator, ztcfg # # It must be in the module loading order # Span 1: WCTDM/0 "Wildcard TDM410P Board 1" (MASTER) fxoks=1 fxoks=2 fxsks=3 # channel 4, WCTDM, no module. # Global data loadzone = nl defaultzone = nl This is a relatively simple file, configuring three Digium modules. As you can see, the ''genzaptelconf'' command has generated it for us. It belongs with a Digium TDM410P card, which has two FXS modules in positions 1 and 2, and one FXO module in position 3. The first two non-commented lines define the protocol that the FXS modules must "talk" with the attached devices, which "naturally" is the FXO protocol (yes, FXS talks FXO, and FXO talks FXS... a bit like electric current flowing from negative to positive. It's just a matter of definitions).<br> The third line defines that the FXO module talks FXS protocol.<br> The fourth line configures a set of indications to use for the defined channels. Since we're loading "nl", we're configuring Dutch dialtones etcetera for the channels.<br> Finally, the last line tell the server that any channel that does not have a zone assigned to it, should have the specified default zone configured - Dutch as well in this example.<br> With this simple file, the driver for our example card (''wctdm24xxp'', by the way) can set up the hardware just as we want it. Now to tell Asterisk how to use it... ==zapata-channels.conf== ; Autogenerated by ./genzaptelconf -- do not hand edit ; Zaptel Channels Configurations (zapata.conf) ; ; This is not intended to be a complete zapata.conf. Rather, it is intended ; to be #include-d by /etc/zapata.conf that will include the global settings ; ; Span 1: WCTDM/0 "Wildcard TDM410P Board 1" (MASTER) ;;; line="1 WCTDM/0/0" signalling=fxo_ks callerid="Channel 1" <6001> mailbox=6001 group=5 context=from-internal channel => 1 callerid= mailbox= group= context=default ;;; line="2 WCTDM/0/1" signalling=fxo_ks callerid="Channel 2" <6002> mailbox=6002 group=5 context=from-internal channel => 2 callerid= mailbox= group= context=default ;;; line="3 WCTDM/0/2" signalling=fxs_ks callerid=asreceived group=0 context=from-pstn channel => 3 context=default This second file is also auto-generated. It sets up three channels, associated with the three Digium hardware modules that we've configured with ''zaptel.conf''. Here, we also see how the channel numbers get assigned to the physical ports. The first module gets to be Zap channel 1 ('''Zap/1'''), the second '''Zap/2''' and so on. So if we would like our FXO module to be channel 1, and our FXS modules 2 and three, we could rotate the three channel numbers in this file. Probably we'd then also want to rotate the ''callerid''`s though... Furthermore, we don't think it's a good idea to assign channels to Zap devices in a different order than the devices are found in the system - meaning "stick with the default numbering as much as possible". Note that the way ''zapata-channels.conf'' is interpreted, means that any statement like ''signalling=fxs_ks'' actually ''sets'' the ''signalling'' parameter; when the ''channel => 1'' line is reached, then all preceding parameter assignments are applied to that particular channel. This also means that if you somewhere have set a channel to belong to context "foo", and then never set a context again, then every next channel also gets assigned to "foo". So remember: if you don't see a parameter being set with a specific channel, you CANNOT assume that it then has it's default value; if a preceding channel has set that parameter to value "bar", then for your specific channel, it is "bar" also. An interesting thing to see here is how ''genzaptelconf'' deals with the above concept. After defining each channel, it resets the most important parameters (a.o. the ones that should be unique with a channel) to empty or "default". This means that if you yourself are very meticulous, you could do without that safety net, and rewrite the above configuration file as: signalling=fxo_ks callerid="Channel 1" <6001> mailbox=6001 group=5 context=from-internal channel => 1 signalling=fxo_ks callerid="Channel 2" <6002> mailbox=6002 group=5 context=from-internal channel => 2 signalling=fxs_ks callerid=asreceived group=0 context=from-pstn channel => 3 Note: we like the thoroughnes of the ''genzaptelconf'' configuration, but we like the readability of the second file more. ==zapata.conf== [trunkgroups] [channels] switchtype=national rxwink=300 ; Atlas seems to use long (250ms) winks usecallerid=yes hidecallerid=no callwaiting=yes usecallingpres=yes callwaitingcallerid=yes threewaycalling=yes transfer=yes canpark=yes cancallforward=yes callreturn=yes echocancel=yes echocancelwhenbridged=yes rxgain=0.0 txgain=0.0 callgroup=1 pickupgroup=1 immediate=no #include zapata-channels.conf Under Debian, ==sip.conf== This is a sample configuration for VOIP with XS4ALL ;;/etc/asterisk/sip.conf;; [general] context=default externip=setyoureiphere dtfmmode=inband localnet=192.168.70.0/24 port=5060 bindaddr=0.0.0.0 disallow=all allow=alaw allow=ulaw registerattempts=0 defaultexpiry=7200 register => 08787XXXXX:PASSWORD@sip.xs4all.nl/08787XXXXX [xs4all] type=friend username=08787XXXXX fromuser=08787XXXXX fromdomain=sip.xs4all.nl secret=PASSWORD host=sip.xs4all.nl insecure=invite context=fromxs4all canreinvite=no dtmfmode=inband disallow=all allow=alaw allow=ulaw ==DAHDI== From Asterisk version 1.4, the ''zaptel'' hardware driver has been renamed to ''DAHDI'' witch stands for "Digium Asterisk Hardware Device Interface". Installation is a breeze: ===PRI library installation=== If you're installing a digital card (ISDN card etc), you first need an up-to-date ''libpri'', a "primary rate ISDN specification library". Assuming you haven't installed such a library from your distribution (e.g. Debian 4.0 "Lenny" has package ''libpri1.0''), you can get the latest version of this library from [http://downloads.asterisk.org/pub/telephony/libpri/ the Digium website]. Extract it in ''/usr/src'', then do something like this: cd /usr/src/libpri-1.4.10.2 make make install If all went well, you can see the resulting libraries in /usr/lib: localhost:~# '''ls -lAF /usr/lib/libpri.*''' -rw-r--r-- 1 root root 522742 2010-05-16 19:49 /usr/lib/libpri.a lrwxrwxrwx 1 root root 13 2010-05-16 19:49 /usr/lib/libpri.so -> libpri.so.1.4* -rwxr-xr-x 1 root root 344055 2010-05-16 19:49 /usr/lib/libpri.so.1.4* localhost:~# '''_''' ===DAHDI driver installation=== The actual driver for your Digium hardware comes from the [http://downloads.asterisk.org/pub/telephony/dahdi-linux-complete/ DAHDI part] of Digium's download site. Supposing you've downloaded the file to /tmp, you could execute these commands: cd /usr/src tar zxvf /tmp/dahdi-linux-2.3.0.tar.gz cd dahdi-linux-2.3.0 make make install This gives you the DAHDI driver, but not the associated set of tools. Contrary to some documentation, you can download it [http://downloads.asterisk.org/pub/telephony/dahdi-tools/ separately] from Digium. Supposing again you've downloaded the file to /tmp, you could execute these commands: cd /usr/src tar zxvf /tmp/dahdi-tools-2.3.0.tar.gz cd dahdi-tools-2.3.0 ./configure make menuconfig make make install make config Note that the ''make menuconfig'' step is optional. With the DAHDI tools installed, we can generate a DAHDI default configuration: dahdi_genconf modules However, the driver is not started yet, so let's do that now: /etc/init.d/dahdi start The success of this action can be validated using one of the DAHDI tools: localhost:~# '''dahdi_scan''' [1] active=yes alarms=OK description=Wildcard TDM410P Board 1 name=WCTDM/0 manufacturer=Digium devicetype=Wildcard TDM410P (VPM100M) location=PCI Bus 03 Slot 08 basechan=1 totchans=4 irq=22 type=analog port=1,FXS port=2,FXS port=3,FXO port=4,none localhost:~# '''_''' ---- If you installed the dahdi-tools (highly recommended) then you can configure your hardware Conversion from zaptel /etc/zaptel.conf Becomes /etc/dahdi/system.conf /etc/asterisk/zapata.conf Becomes /etc/asterisk/chan_dahdi.conf Lets look at what we have #dahdi_tool This will give a overview of the hardware and if it is configured or not. It will all so show alarms on the hardware. Now lets configure the card. First edit /etc/dadi/genconf_parameters. This file is used with dahdi_genconf and will produce /etc/dahdi-system.conf *lc_country nl You can also set the echo cancelation here MG2 is default #dahdi_genconf #dahdi_cfg -vv DAHDI Tools Version - 2.2.0 DAHDI Version: 2.2.0.1 Echo Canceller(s): MG2 Configuration ====================== Channel map: Channel 01: FXO Kewlstart (Default) (Echo Canceler: mg2) (Slaves: 01) Channel 02: FXO Kewlstart (Default) (Echo Canceler: mg2) (Slaves: 02) 2 channels to configure. Setting echocan for channel 1 to mg2 Setting echocan for channel 2 to mg2 Check if the right module is loaded. #cat /etc/dahdi/modules You can configure the options of dahdi in /etc/asterisk/chan_dahdi.conf for example turn off the echo cancelation Also include this line #include dahdi-channels.conf in your chan_dahdi.conf (yes with the #) Otherwise you're asterisk will not see the channels. You can also check the channels in asterisk #asterisk -r #server*CLI> dahdi show channels Or set the verbose level on asterisk to see more output #server*CLI> core set verbose 10 I had some trouble with the sounds. When asterisk plays hello-world.gsm it sounded stutterd. I did a #dahdi_test This gives a readout from the timinsettings in asterisk. Mine was -133% and it should give a reading close to 100%.I did a #dahdi destroy channel 1 #dahdi destroy channel 2 #dahdi restart Now i have 2 channels and no Pseudo channel (not shure were it's for) Dahdi_test gives me 99,6% and the spound is good = Asterisk dialplans - contexts = A dial plan consists of a number of extensions. Each extensions consists of a number of priorities. Extensions are grouped in contexts. For each priority, an application is called. [context] exten => id, priority, command When Asterisk receives an incoming connection on a channel, Asterisk looks at the context defined for that channel for commands telling Asterisk what it should do. The context defines different sets of commands depending on what extension the user has dialed. For example, a context might provide one set of commands for what to do if the user dials "123", and another set of commands for what to do if the user dials "9", and another set of commands for what to do if the user dials any number beginning with "555". For some kinds of connections — such incoming calls from an outside telephone line — the user has not dialed an extension. In that case, Asterisk behaves as if the user had dialed a special extension named "s" (for Start). Asterisk will look for an extension "number" s in the definition of the context for that channel for instructions about what it should do to handle the call. Let's say, for example, that you have a channel "Zap/1" which is a connection to a telephone handset in your building. And let's say that in the configuration file for Zap channels (zapata.conf), you have defined context=john for Zap channel 1. So when you use that handset to dial a number, Asterisk looks for a context with the name "john" in extensions.conf to find out what it should do. You begin the definition of a context in extensions.conf by putting the name of the context in square brackets on a line by itself, like this: [john] == extensions.conf == [globals] [general] autofallthrough=yes [default] include => fromxs4all [fromxs4all] exten => 08787XXXXX,1,Dial(DAHDI/2) exten => 08787XXXXX,n,Hangup() [outgoing] exten => _X.,1,Dial(sip/xs4all/${EXTEN},60,r) [internal] exten => 6004,1,Dial(sip/6004) exten => 6003,1,Dial(sip/6003) exten => 6005,1,Dial(DAHDI/2) exten => 6006,1,Answer() exten => 6006,n,Playback(hello-world) exten => 6006,n,Hangup() [phones] include => internal include => fromxs4all include => outgoing 605a92010da6d6c7b9d226b25d1c62a3c32660a4 0 1608 2569 2010-05-30T16:50:24Z 82.161.20.132 0 Created page with 'There are two implimentations of NFS one runs in kernel space (nfs-kernel-server) the other in user space (nfs-user-server). The kernel space implimentation is faster and more st…' wikitext text/x-wiki There are two implimentations of NFS one runs in kernel space (nfs-kernel-server) the other in user space (nfs-user-server). The kernel space implimentation is faster and more stable but if something goes wrong it could bring your box down. In reality the kernel space NFS implimentation very rarely fails Make sure you have the kernel modules selected in you're kernel file systems -> Network File Systems -> NFS server support On the server: apt-get install nfs-kernel-server nfs-common portmap On the client: #pt-get install nfs-common portmap == Export Directories == #vi /etc/exports /data 192.168.0.0/24(rw,sync) /home 192.168.0.0/24(rw,sync) == Mount == To mount the directories on the client nd make it persistent edit /etc/fstab # vi /etc/fstab 192.168.0.1:/data /data nfs rw,sync,hard,intr 0 0 192.168.0.1:/home /home nfs rw,sync,hard,intr 0 0 b888fa9261e2b897d0d21f7655ebf47a9d50dc6d 0 1475 2572 1828 2010-06-19T18:35:00Z Saruman! 2 created DAHDI link wikitext text/x-wiki =Asterisk under Debian 5.0 "Lenny"= The pages on this Wiki all relate to running Asterisk with [http://www.digium.com/ Digium] hardware on [http://www.debian.org/releases/lenny/ Debian 5.0 "Lenny"]. The scenario we're working on here is a single server, attached to both the Internet (over ADSL) and a home network, that's being expanded to also serve as a telephone PBX. We might make a distinction between an Asterisk PBX connected to the Plain Old Telephone System (POTS) using [http://www.digium.com/en/products/analog/x100m.php an FXO module], and an Asterisk that only has VoIP functionality. Read the different subsections for more information, but remember: the basis of all the information in this wiki is [http://downloads.oreilly.com/books/9780596510480.pdf this fantastic book]. If you're interested in Asterisk, we seriously suggest you [http://oreilly.com/catalog/9780596510480/index.html buy it]. =Installing the hardware= When you need only VoIP support, and no standard phones or telephone lines need to be connected to your Asterisk PBX, you really don't need any kind of special hardware. However, if you need to receive from or send out calls to the Plain Old Telephone System (POTS), you need hardware with FXO capabilities. Furthermore, if you need to attach regular telephones to your PBX (as opposed to just using softphones, phone software on laptops and desktops), you need hardware with FXS capabilities. For our discussion on obtaining and installing telephony hardware, [[Telephony hardware explained | go here]]. =Configuring hardware support= Once you've installed your [[Telephony hardware explained | telephony hardware]], you probably want to start using it. The bad news is, this requires the Linux kernel to support that hardware with drivers, that it currently does not have. The good news is, we can explain to you how to get and install [[Installing and configuring DAHDI|DAHDI drivers]].<br><small>Note: if you're interested in the "old" method using Zaptel, [[Installing and configuring Zaptel|click here]].</small> =Installing Asterisk under Debian= When the hardware is running, you can [[install Asterisk under Debian]] - well actually you could install and configure Asterisk, and add hardware later, but we like to explain things in this particular order. We'll also do some [[install Asterisk under Debian | basic configuration and testing]] here, to test the installation of your FXO and FXS enabled hardware. When that is in working order, we continue with [[Configuring and testing SIP and IAX2 | configuring and testing SIP and IAX2]], in which we'll try to, well, configure and test both SIP (a softphone) and IAX2, which is a connection between two Asterisk PBXes. =Configuring Asterisk - the basics= Once Asterisk is up and running, we can start putting in the most [[Asterisk basic configuration | basic configuration]]. Directly after this, we hand out some [[Dialplan theory]]. This gives you the possibility to receive and place calls, but not yet much of the funky stuff that is described in the [http://downloads.oreilly.com/books/9780596510480.pdf Asterisk TFOTF book]. b4f243fedef88cadd0b9560c945436d7380f1071 0 1609 2573 2010-06-19T18:52:35Z Saruman! 2 started libpri1.4 wikitext text/x-wiki ==Installation overview== ==LIBPRI configuration/installation== Asterisk needs the ''libpri'' package; not only to handle digital telephony cards (ISDN-cards), but also for some other functions (although currently I don't know which ones :-). Before installing Asterisk, you could start by installing this package. In Debian 5.0 "Lenny", the packages is named ''libpri1.0'' and it can be installed using ''apt-get''. However, it's very easy to install the latest & greatest straight from the [http://www.asterisk.org/ Asterisk website]. ===Obtaining and preparing libpri=== ===Compiling and installing libpri=== ===Files and updating After installation, you'll find that ''/usr/lib'' contains 3 entries: # the actual module ''libpri.so.1.4''; # a symlink to this module, called ''libpri.so'' # static library file ''libpri.a'' Updating is as simple as recompiling a new version, which will overwrite these three files; if you don't need ''libpri'' any more, simply delete the three files. <small>For reference, the Debian ''libpri1.0'' package contains<br> - module ''libpri.so.1.0''<br> - a symlink to this module, called ''libpri.so.1''<br> - ''libpri-bristuffed.so.1.0''<br> - a symlink to this module, called ''libpri-bristuffed.so.1'' The Debian package ''libpri1.0'' (and by extension these files) can coexist with a vanilla ''libpri'', as long as it's not an 1.0.x ''libpri''.</small> ==DAHDI installation== ==DAHDI tools installation== ==Testing your DAHDI drivers== 7a34890998e43faa29fd8bad9161ec8f7f2f4e39 0 1609 2574 2573 2010-06-20T19:02:50Z Saruman! 2 updated libpri section wikitext text/x-wiki ==Installation overview== When installing Asterisk, the installation can broadly follow these steps: # install ''libpri'' library files # physically install telephony hardware like one or more [http://www.digium.com/en/ Digium] telephony interface devices # compile, install and configure DAHDI device drivers for this hardware # compile and install Asterisk # provide Asterisk with a default "sample" configuration Of course, then the real fun starts - but let's leave that for another section of this wiki. ==''libpri'' configuration/installation== Asterisk needs the ''libpri'' package; primarily to handle digital telephony cards (T1/E1/ISDN-cards), but also for some other functions (although currently I don't know which ones :-). However, even if you don't need the files, they do you absolutely no harm, and waste only a handful of mebibytes of storage space. Thus we'd recommend installing it even if you don't have digital telephony cards (yet). In Debian 5.0 "Lenny", the packages is named ''libpri1.0'' and it can be installed using ''apt-get''. However, it's very easy to install the latest & greatest straight from the [http://www.asterisk.org/ Asterisk website]. ===Obtaining and preparing ''libpri''=== To obtain ''libpri'', simply download the latest version from the Asterisk website. At the time of writing, the most recent version of ''libpri'' could be found at the Asterisk [http://downloads.asterisk.org/pub/telephony/libpri/ download site]; you'll want to get both the actual software ''libpri-1.4-current.tar.gz'' and the accompanying readme ''README-1.4-current''. Mind you, the website also provides these same files as fully-version-numbered files (something like ''libpri-1.4.11.2.tar.gz'' and ''README-1.4.11.2''). However, a link to these files would get stale pretty fast. Mind you: if you need an older release, or if there are newer "major" releases, you could replace the 1.4 part of ''libpri-1.4-current.tar.gz'' for the designation of that release, e.g. ''libpri-1.2-current.tar.gz'' for the latest version of the older 1.2 release. Thus we could get the software, and extract it in ''/usr/src'' using something akin to the following commands: localhost:~# '''cd /usr/src''' localhost:/usr/src# '''wget <nowiki>http://downloads.asterisk.org/pub/telephony/libpri/libpri-1.4-current.tar.gz</nowiki>''' --2010-06-20 20:32:41-- <nowiki>http://downloads.asterisk.org/pub/telephony/libpri/libpri-1.4-current.tar.gz</nowiki> Resolving downloads.asterisk.org... 76.164.171.233, 2001:470:e0d4::e9 Connecting to downloads.asterisk.org|76.164.171.233|:80... connected. HTTP request sent, awaiting response... 200 OK Length: 225009 (220K) [application/x-gzip] Saving to: `libpri-1.4-current.tar.gz' 100%[===================================================>] 225,009 250K/s in 0.9s 2010-06-20 20:32:43 (250 KB/s) - `libpri-1.4-current.tar.gz' saved [225009/225009] localhost:/usr/src# '''tar xzf libpri-1.4-current.tar.gz''' localhost:/usr/src# '''cd libpri-1.4.11.2''' localhost:/usr/src/libpri-1.4.11.2# '''_''' Now we have the ''libpri'' software, but we need to compile it for our system. ===Compiling and installing libpri=== We're now assuming you have everything needed for compiling software for your Linux server, a.o. * Linux 2.6 kernel headers; * Development libraries and headers for ncurses, zlib and openssl, and for libnewt; * GCC and standard software build tools. If all this is the case, the compilation will be as simple as running these commands: localhost:/usr/src/libpri-1.4.11.2# '''make''' gcc -Wall -Werror -Wstrict-prototypes -Wmissing-prototypes -g -fPIC -O2 -MD -MT copy_string.o -MF .copy_string.o.d -MP -c -o copy_string.o copy_string.c gcc -Wall -Werror -Wstrict-prototypes -Wmissing-prototypes -g -fPIC -O2 -MD -MT pri.o -MF .pri.o.d -MP -c -o pri.o pri.c ''(lots more cryptic messages)'' gcc -Wall -Werror -Wstrict-prototypes -Wmissing-prototypes -g -fPIC -O2 -MD -MT version.lo -MF .version.lo.d -MP -c -o version.lo version.c gcc -shared -Wl,-hlibpri.so.1.4 -o libpri.so.1.4 copy_string.lo pri.lo q921.lo prisched.lo q931.lo pri_facility.lo asn1_primitive.lo rose.lo rose_address.lo rose_etsi_aoc.lo ''(etc etc...) /sbin/ldconfig -n . ln -sf libpri.so.1.4 libpri.so localhost:/usr/src/libpri-1.4.11.2# '''make install''' mkdir -p /usr/lib mkdir -p /usr/include install -m 644 libpri.h /usr/include install -m 755 libpri.so.1.4 /usr/lib #if [ -x /usr/sbin/sestatus ] && ( /usr/sbin/sestatus | grep "SELinux status:" | grep -q "enabled"); then /sbin/restorecon -v /usr/lib/libpri.so.1.4; fi ( cd /usr/lib ; ln -sf libpri.so.1.4 libpri.so) install -m 644 libpri.a /usr/lib if test $(id -u) = 0; then /sbin/ldconfig -n /usr/lib; fi localhost:/usr/src/libpri-1.4.11.2# '''_''' That's it, your server now has a means to understand the Primary Rate ISDN specification! ===Files and updating=== After installation, you'll find that ''/usr/lib'' contains 3 entries: # the actual module ''libpri.so.1.4''; # a symlink to this module, called ''libpri.so'' # static library file ''libpri.a'' Furthermore, there's a single file in ''/usr/include'': # header file ''libpri.h'' Updating is as simple as recompiling a new version, which will overwrite these files; if you don't need ''libpri'' any more, simply delete them. <small>For reference, the Debian ''libpri1.0'' package contains<br> - module ''libpri.so.1.0''<br> - a symlink to this module, called ''libpri.so.1''<br> - ''libpri-bristuffed.so.1.0''<br> - a symlink to this module, called ''libpri-bristuffed.so.1'' The Debian package ''libpri1.0'' (and by extension these files) can coexist with a vanilla ''libpri'', as long as it's not an 1.0.x ''libpri''.</small> ==DAHDI installation== ==DAHDI tools installation== ==Testing your DAHDI drivers== 2c0585a2a75255f9a1c0eed0fa5d115cdc6cd77b 2662 2574 2011-04-05T07:49:25Z Saruman! 2 /* libpri configuration/installation */ updated wikitext text/x-wiki ==Installation overview== When installing Asterisk, the installation can broadly follow these steps: # install ''libpri'' library files # physically install telephony hardware like one or more [http://www.digium.com/en/ Digium] telephony interface devices # compile, install and configure DAHDI device drivers for this hardware # compile and install Asterisk # provide Asterisk with a default "sample" configuration Of course, then the real fun starts - but let's leave that for another section of this wiki. ==''libpri'' configuration/installation== Asterisk needs the ''libpri'' package; a "primary rate ISDN specification library". This is primarily to handle digital telephony cards (T1/E1/ISDN-cards), but also for some other functions (although currently I don't know which ones :-). However, even if you don't need the files, they do you absolutely no harm, and waste only a handful of mebibytes of storage space. Thus we'd recommend installing it even if you don't have digital telephony cards (yet). In Debian 5.0 "Lenny", the package is named ''libpri1.0'' and it can be installed using ''apt-get''. However, it's very easy to install the latest & greatest straight from the Digium website. ===Obtaining and preparing ''libpri''=== To obtain ''libpri'', simply download the latest version from the [http://downloads.asterisk.org/pub/telephony/libpri/ Digium website]. You'll want to get both the actual software ''libpri-1.4-current.tar.gz'' and the accompanying readme ''README-1.4-current''. Mind you, the website also provides these same files as fully-version-numbered files (something like ''libpri-1.4.11.5.tar.gz'' and ''README-1.4.11.5''). However, a link to these files would get stale pretty fast. Mind you: if you need an older release, or if there are newer "major" releases, you could replace the 1.4 part of ''libpri-1.4-current.tar.gz'' for the designation of that release, e.g. ''libpri-1.2-current.tar.gz'' for the latest version of the older 1.2 release. Thus we could get the software, and extract it in ''/usr/src'' using something akin to the following commands: localhost:~# '''cd /usr/src''' localhost:/usr/src# '''wget <nowiki>http://downloads.asterisk.org/pub/telephony/libpri/libpri-1.4-current.tar.gz</nowiki>''' --2010-06-20 20:32:41-- <nowiki>http://downloads.asterisk.org/pub/telephony/libpri/libpri-1.4-current.tar.gz</nowiki> Resolving downloads.asterisk.org... 76.164.171.233, 2001:470:e0d4::e9 Connecting to downloads.asterisk.org|76.164.171.233|:80... connected. HTTP request sent, awaiting response... 200 OK Length: 225009 (220K) [application/x-gzip] Saving to: `libpri-1.4-current.tar.gz' 100%[===================================================>] 225,009 250K/s in 0.9s 2010-06-20 20:32:43 (250 KB/s) - `libpri-1.4-current.tar.gz' saved [225009/225009] localhost:/usr/src# '''tar xzf libpri-1.4-current.tar.gz''' localhost:/usr/src# '''cd libpri-1.4.11.2''' localhost:/usr/src/libpri-1.4.11.2# '''_''' Now we have the ''libpri'' software, but we need to compile it for our system. ===Compiling and installing libpri=== We're now assuming you have everything needed for compiling software for your Linux server, a.o. * Linux 2.6 kernel headers; * Development libraries and headers for ncurses, zlib and openssl, and for libnewt; * GCC and standard software build tools. If all this is the case, the compilation will be as simple as running these commands: localhost:/usr/src/libpri-1.4.11.2# '''make''' gcc -Wall -Werror -Wstrict-prototypes -Wmissing-prototypes -g -fPIC -O2 -MD -MT copy_string.o -MF .copy_string.o.d -MP -c -o copy_string.o copy_string.c gcc -Wall -Werror -Wstrict-prototypes -Wmissing-prototypes -g -fPIC -O2 -MD -MT pri.o -MF .pri.o.d -MP -c -o pri.o pri.c ''(lots more cryptic messages)'' gcc -Wall -Werror -Wstrict-prototypes -Wmissing-prototypes -g -fPIC -O2 -MD -MT version.lo -MF .version.lo.d -MP -c -o version.lo version.c gcc -shared -Wl,-hlibpri.so.1.4 -o libpri.so.1.4 copy_string.lo pri.lo q921.lo prisched.lo q931.lo pri_facility.lo asn1_primitive.lo rose.lo rose_address.lo rose_etsi_aoc.lo ''(etc etc...) /sbin/ldconfig -n . ln -sf libpri.so.1.4 libpri.so localhost:/usr/src/libpri-1.4.11.2# '''make install''' mkdir -p /usr/lib mkdir -p /usr/include install -m 644 libpri.h /usr/include install -m 755 libpri.so.1.4 /usr/lib #if [ -x /usr/sbin/sestatus ] && ( /usr/sbin/sestatus | grep "SELinux status:" | grep -q "enabled"); then /sbin/restorecon -v /usr/lib/libpri.so.1.4; fi ( cd /usr/lib ; ln -sf libpri.so.1.4 libpri.so) install -m 644 libpri.a /usr/lib if test $(id -u) = 0; then /sbin/ldconfig -n /usr/lib; fi localhost:/usr/src/libpri-1.4.11.2# '''_''' That's it, your server now has a means to understand the Primary Rate ISDN specification! ===Files and updating=== After installation, you'll find that ''/usr/lib'' contains 3 entries: # the actual module ''libpri.so.1.4''; # a symlink to this module, called ''libpri.so'' # static library file ''libpri.a'' Furthermore, there's a single file in ''/usr/include'': # header file ''libpri.h'' Updating is as simple as recompiling a new version, which will overwrite these files; if you don't need ''libpri'' any more, simply delete them. <small>For reference, the Debian ''libpri1.0'' package contains<br> - module ''libpri.so.1.0''<br> - a symlink to this module, called ''libpri.so.1''<br> - ''libpri-bristuffed.so.1.0''<br> - a symlink to this module, called ''libpri-bristuffed.so.1'' The Debian package ''libpri1.0'' (and by extension these files) can coexist with a vanilla ''libpri'', as long as it's not an 1.0.x ''libpri''.</small> ==DAHDI installation== ==DAHDI tools installation== ==Testing your DAHDI drivers== 939058d7780190e29ee897cff91ff105dca5a5eb 2663 2662 2011-04-05T07:53:23Z Saruman! 2 extra sections moved to here wikitext text/x-wiki ==Installation overview== When installing Asterisk, the installation can broadly follow these steps: # install ''libpri'' library files # physically install telephony hardware like one or more [http://www.digium.com/en/ Digium] telephony interface devices # compile, install and configure DAHDI device drivers for this hardware # compile and install Asterisk # provide Asterisk with a default "sample" configuration Of course, then the real fun starts - but let's leave that for another section of this wiki. ==''libpri'' configuration/installation== Asterisk needs the ''libpri'' package; a "primary rate ISDN specification library". This is primarily to handle digital telephony cards (T1/E1/ISDN-cards), but also for some other functions (although currently I don't know which ones :-). However, even if you don't need the files, they do you absolutely no harm, and waste only a handful of mebibytes of storage space. Thus we'd recommend installing it even if you don't have digital telephony cards (yet). In Debian 5.0 "Lenny", the package is named ''libpri1.0'' and it can be installed using ''apt-get''. However, it's very easy to install the latest & greatest straight from the Digium website. ===Obtaining and preparing ''libpri''=== To obtain ''libpri'', simply download the latest version from the [http://downloads.asterisk.org/pub/telephony/libpri/ Digium website]. You'll want to get both the actual software ''libpri-1.4-current.tar.gz'' and the accompanying readme ''README-1.4-current''. Mind you, the website also provides these same files as fully-version-numbered files (something like ''libpri-1.4.11.5.tar.gz'' and ''README-1.4.11.5''). However, a link to these files would get stale pretty fast. Mind you: if you need an older release, or if there are newer "major" releases, you could replace the 1.4 part of ''libpri-1.4-current.tar.gz'' for the designation of that release, e.g. ''libpri-1.2-current.tar.gz'' for the latest version of the older 1.2 release. Thus we could get the software, and extract it in ''/usr/src'' using something akin to the following commands: localhost:~# '''cd /usr/src''' localhost:/usr/src# '''wget <nowiki>http://downloads.asterisk.org/pub/telephony/libpri/libpri-1.4-current.tar.gz</nowiki>''' --2010-06-20 20:32:41-- <nowiki>http://downloads.asterisk.org/pub/telephony/libpri/libpri-1.4-current.tar.gz</nowiki> Resolving downloads.asterisk.org... 76.164.171.233, 2001:470:e0d4::e9 Connecting to downloads.asterisk.org|76.164.171.233|:80... connected. HTTP request sent, awaiting response... 200 OK Length: 225009 (220K) [application/x-gzip] Saving to: `libpri-1.4-current.tar.gz' 100%[===================================================>] 225,009 250K/s in 0.9s 2010-06-20 20:32:43 (250 KB/s) - `libpri-1.4-current.tar.gz' saved [225009/225009] localhost:/usr/src# '''tar xzf libpri-1.4-current.tar.gz''' localhost:/usr/src# '''cd libpri-1.4.11.2''' localhost:/usr/src/libpri-1.4.11.2# '''_''' Now we have the ''libpri'' software, but we need to compile it for our system. ===Compiling and installing libpri=== We're now assuming you have everything needed for compiling software for your Linux server, a.o. * Linux 2.6 kernel headers; * Development libraries and headers for ncurses, zlib and openssl, and for libnewt; * GCC and standard software build tools. If all this is the case, the compilation will be as simple as running these commands: localhost:/usr/src/libpri-1.4.11.2# '''make''' gcc -Wall -Werror -Wstrict-prototypes -Wmissing-prototypes -g -fPIC -O2 -MD -MT copy_string.o -MF .copy_string.o.d -MP -c -o copy_string.o copy_string.c gcc -Wall -Werror -Wstrict-prototypes -Wmissing-prototypes -g -fPIC -O2 -MD -MT pri.o -MF .pri.o.d -MP -c -o pri.o pri.c ''(lots more cryptic messages)'' gcc -Wall -Werror -Wstrict-prototypes -Wmissing-prototypes -g -fPIC -O2 -MD -MT version.lo -MF .version.lo.d -MP -c -o version.lo version.c gcc -shared -Wl,-hlibpri.so.1.4 -o libpri.so.1.4 copy_string.lo pri.lo q921.lo prisched.lo q931.lo pri_facility.lo asn1_primitive.lo rose.lo rose_address.lo rose_etsi_aoc.lo ''(etc etc...) /sbin/ldconfig -n . ln -sf libpri.so.1.4 libpri.so localhost:/usr/src/libpri-1.4.11.2# '''make install''' mkdir -p /usr/lib mkdir -p /usr/include install -m 644 libpri.h /usr/include install -m 755 libpri.so.1.4 /usr/lib #if [ -x /usr/sbin/sestatus ] && ( /usr/sbin/sestatus | grep "SELinux status:" | grep -q "enabled"); then /sbin/restorecon -v /usr/lib/libpri.so.1.4; fi ( cd /usr/lib ; ln -sf libpri.so.1.4 libpri.so) install -m 644 libpri.a /usr/lib if test $(id -u) = 0; then /sbin/ldconfig -n /usr/lib; fi localhost:/usr/src/libpri-1.4.11.2# '''_''' That's it, your server now has a means to understand the Primary Rate ISDN specification! ===Files and updating=== After installation, you'll find that ''/usr/lib'' contains 3 entries: # the actual module ''libpri.so.1.4''; # a symlink to this module, called ''libpri.so'' # static library file ''libpri.a'' Furthermore, there's a single file in ''/usr/include'': # header file ''libpri.h'' Updating is as simple as recompiling a new version, which will overwrite these files; if you don't need ''libpri'' any more, simply delete them. <small>For reference, the Debian ''libpri1.0'' package contains<br> - module ''libpri.so.1.0''<br> - a symlink to this module, called ''libpri.so.1''<br> - ''libpri-bristuffed.so.1.0''<br> - a symlink to this module, called ''libpri-bristuffed.so.1'' The Debian package ''libpri1.0'' (and by extension these files) can coexist with a vanilla ''libpri'', as long as it's not an 1.0.x ''libpri''.</small> ==DAHDI driver installation== The actual driver for your Digium hardware comes from the [http://downloads.asterisk.org/pub/telephony/dahdi-linux-complete/ DAHDI part] of Digium's download site. Supposing you've downloaded the file to /tmp, you could execute these commands: cd /usr/src tar zxvf /tmp/dahdi-linux-2.3.0.tar.gz cd dahdi-linux-2.3.0 make make install ==DAHDI tools installation== The previous instructions gave you the DAHDI driver, but not the associated set of tools. Contrary to some documentation, you can download it [http://downloads.asterisk.org/pub/telephony/dahdi-tools/ separately] from Digium. Supposing again you've downloaded the file to /tmp, you could execute these commands: cd /usr/src tar zxvf /tmp/dahdi-tools-2.3.0.tar.gz cd dahdi-tools-2.3.0 ./configure make menuconfig make make install make config Note that the ''make menuconfig'' step is optional. With the DAHDI tools installed, we can generate a DAHDI default configuration: dahdi_genconf modules However, the driver is not started yet, so let's do that now: /etc/init.d/dahdi start ==Testing your DAHDI drivers== The success of the previous installation steps can be validated using one of the DAHDI tools (provided the "dahdi start" command has been issued): localhost:~# '''dahdi_scan''' [1] active=yes alarms=OK description=Wildcard TDM410P Board 1 name=WCTDM/0 manufacturer=Digium devicetype=Wildcard TDM410P (VPM100M) location=PCI Bus 03 Slot 08 basechan=1 totchans=4 irq=22 type=analog port=1,FXS port=2,FXS port=3,FXO port=4,none localhost:~# '''_''' ---- If you installed the dahdi-tools (highly recommended) then you can configure your hardware Conversion from zaptel /etc/zaptel.conf Becomes /etc/dahdi/system.conf /etc/asterisk/zapata.conf Becomes /etc/asterisk/chan_dahdi.conf Lets look at what we have #dahdi_tool This will give a overview of the hardware and if it is configured or not. It will all so show alarms on the hardware. Now lets configure the card. First edit /etc/dadi/genconf_parameters. This file is used with dahdi_genconf and will produce /etc/dahdi-system.conf *lc_country nl You can also set the echo cancelation here MG2 is default #dahdi_genconf #dahdi_cfg -vv DAHDI Tools Version - 2.2.0 DAHDI Version: 2.2.0.1 Echo Canceller(s): MG2 Configuration ====================== Channel map: Channel 01: FXO Kewlstart (Default) (Echo Canceler: mg2) (Slaves: 01) Channel 02: FXO Kewlstart (Default) (Echo Canceler: mg2) (Slaves: 02) 2 channels to configure. Setting echocan for channel 1 to mg2 Setting echocan for channel 2 to mg2 Check if the right module is loaded. #cat /etc/dahdi/modules You can configure the options of dahdi in /etc/asterisk/chan_dahdi.conf for example turn off the echo cancelation Also include this line #include dahdi-channels.conf in your chan_dahdi.conf (yes with the #) Otherwise you're asterisk will not see the channels. You can also check the channels in asterisk #asterisk -r #server*CLI> dahdi show channels Or set the verbose level on asterisk to see more output #server*CLI> core set verbose 10 I had some trouble with the sounds. When asterisk plays hello-world.gsm it sounded stutterd. I did a #dahdi_test This gives a readout from the timinsettings in asterisk. Mine was -133% and it should give a reading close to 100%.I did a #dahdi destroy channel 1 #dahdi destroy channel 2 #dahdi restart Now i have 2 channels and no Pseudo channel (not shure were it's for) Dahdi_test gives me 99,6% and the spound is good 4f64bcc6cb8f0e69f95896493ce822d07e7a80f0 0 1499 2575 2396 2010-06-21T07:04:04Z Saruman! 2 link to defaults wikitext text/x-wiki ==Installing Semantic MediaWiki (SMW) under Debian== Installation consists of these simple steps: 1) Use Aptitude to install package ''mediawiki-semediawiki'' (under Lenny that's version 1.2-1) 2) Adjust your namespaces - since we haven't modified the MediaWiki namespaces relative to the original Debian installation, we don't need that. 3) Edit the file ''/etc/mediawiki-extensions/extensions-available/SemanticMediaWiki.php''. All you need to do is change the string for ''enableSemantics'' from ''localhost'' to the hostname of your server: <?php include_once('extensions/SemanticMediaWiki/includes/SMW_Settings.php'); enableSemantics('dworkin.saruman.biz'); ?> Actually, the string for ''enableSemantics'' is an identifier, needed to identify any exported data. The [http://semantic-mediawiki.org/wiki/Help:Installation Semantic MediaWiki website] suggests using the server's host name for this purpose (if you have multiple hostnames, just pick any one of them). 4) Enable the SMW extension, by creating a link to it under ''/etc/mediawiki-extensions/extensions-enabled'': cd /etc/mediawiki-extensions/extensions-enabled/ ln -s ../extensions-available/SemanticMediaWiki.php By the way, this should also work with the MediaWiki extension enabler command: mwenext SemanticMediaWiki.php 5) We now run the maintenance script that creates the necessary tables in your MySQL MediaWiki database. This is a two-step affair:<br> - first set the MW_INSTALL_PATH environment variable to the root of the MediaWiki installation. This path is where ''LocalSettings.php'' and ''index.php'' are located; most likely it's ''/usr/share/mediawiki''.<br> - then go to the directory where the SMW maintenance scripts are located, and execute ''SMW_setup.php''.<br> The sequence will thus look something like this: MW_INSTALL_PATH=/usr/share/mediawiki export MW_INSTALL_PATH cd /usr/share/mediawiki-semediawiki/maintenance php SMW_setup.php The php-script should report setting up some nine tables, named ''smw_ids'', ''smw_redi2'' et cetera. These are the extra MySQL tables that SMW needs. 6) Next, log into your MediaWiki with an account with administrative rights. If you now visit your ''Special pages'', you'll find taht under the section ''Restricted special pages'' there is now an entry titled ''Admin functions for Semantic MediaWiki''. Open it, and find two sections: * '''Preparing database for Semantic MediaWiki'''<br>Here you'll have to press the button labeled ''Initialise or upgrade tables''; this will initialise the newly created tables. A dull page should appear, reporting actions for each of the nine new tables, and ending with the status message ''The storage engine was set up successfully.'' * '''Announce your wiki'''<br>Clicking this button is optional; what it will do is post the URL of your wiki on the [http://semantic-mediawiki.org/wiki/Special:SMWRegistry SMW Registry page] over on the SMW site. Note, that you might want to change some [[Semantic MediaWiki default settings]]. That's it! You can now start [http://semantic-mediawiki.org/wiki/Help:User_manual using SMW]. ab69ef610ecdcc25f8d467b3d3e048532580d24b 0 1610 2576 2010-06-21T07:10:36Z Saruman! 2 documented smw customizations wikitext text/x-wiki Out of the box, SMW has some hardcoded settings that you might want to change. What we use is ==SMW 1.5.1.1== * in ''SemanticMediaWiki/includes/SMW_RefreshTab.php'': ** line 22 change ''if ( $wgUser->isAllowed( 'delete' ) )'' to ''if ( $wgUser->isAllowed( 'purge' ) )'' **: This means that the refresh tab appears for all users that have the ''purge'' right (often given to standard users) instead of ''delete'' right (which is usually reserved for administrators and the like) * in ''SemanticMediaWiki/SMW_Settings.php'': ** line 216 change ''$smwgQMaxSize = 12;'' to ''$smwgQMaxSize = 14;'' ** line 217 change ''$smwgQMaxDepth = 4;'' to ''$smwgQMaxDepth = 5;'' **: These changes increase search depth and number of search terms, which are needed for some queries of the DIR. 2e64e1fb741886d453c1fde78afbf8b68b28b105 0 1446 2577 1622 2010-06-29T23:56:31Z 85.17.90.205 0 /* Parameter: log */ wikitext text/x-wiki <a href="http://sumerki3.net/">������� 3</a> == Context keyword: context == '''''context <chain> &lt;table&gt;'''''<br> Every IPtables rule is written to a chain in a table; with Iceditch, you don't have to specify the chain and table in every line. Just precede the lines with the ''context'' statement. Example: context POSTROUTING nat Notes: the order of chain and table does not matter; ''context nat POSTROUTING'' works just as well. Furthermore, <chain> and &lt;table&gt; have been made case-insensitive; whatever you specify as chain will be translated to uppercase, whatever you specify as table will be translated to lowercase. This gives you the possibility to write the context as you like to read it, e.g. ''context Postrouting Nat''; after processing this, Iceditch will have two variables $CHAIN="POSTROUTING" and $TABLE="nat" that it will use in every following command. For example: context "Input" "fIlTeR" accept -p tcp --dport 22 will result in the following IPtables call: iptables -A INPUT -t filter -p tcp --dport 22 --jump ACCEPT If you do NOT specify a [[Iceditch IPtables language | valid combination]] of chain and table, the execution of Iceditch will halt with a fatal error. It is allowed (but not recommended) to call ''context'' multiple times for the same combination of chain and table; the order in which the rules are added to that chain in that table, is the same in which they appear in your rulefile, top to bottom. This is not recommended, because we feel it decreases readability, and thus maintainability, of the rules file. But hey, it's going to be ''your'' rulefile anyway...<br> Note: you cannot create custom chains by the names of mangle, nat or filter, since Iceditch will always interpret these names as those of tables. == Context keyword: create_chain == '''''create_chain <chain> [&lt;table&gt;]'''''<br> This command creates a new chain named <chain>, in the specified table &lt;table&gt;. If no table is specified, then the ''filter'' table is assumed. Just as with the ''context'' command, the <chain> name you specify will be translated to all uppercase.<br> The name for your new chain must be unique, although just like the built-in chains, you can specify the same name in different tables. If you create "fun-filter" in table ''filter'', and then create a "fun-filter" in table ''nat'', then you actually have two different chains. But remember: since Iceditch translates every chain name to uppercase, you can't create "Fun-filter" AND "fun-FILTER" in the same table - they're the same chain.<br> NOTE: after you've run ''create_chain'', you still have to switch context to create rules in the new chain! example:<br> create_chain fun-filter context fun-filter filter accept -p tcp --dport 22 This will result in iptables -N FUN-FILTER -t filter iptables -A FUN-FILTER -t filter -p tcp --dport 22 --jump ACCEPT == Target keyword: accept == '''''accept [log [msg <message>]] <matches>'''''<br> If a network packet fits the <matches>, then it will be accepted (passed) through the table/chain defined in the context where you put the accept rule. Example: context Input Filter accept –p tcp --dport 22 Iceditch works this out to iptables –t filter –A INPUT –p tcp –-dport 22 –-jump ACCEPT Should you want to log the packet, you’d use context Input Filter accept log –p tcp --dport 22 Iceditch works this out to iptables –t filter –A INPUT –p tcp –-dport 22 \ –-jump LOG --log-prefix accept_INPUT_filter iptables –t filter –A INPUT –p tcp –-dport 22 –-jump ACCEPT Note: the ACCEPT target is valid in any user-manipulable table/chain combination == Target keyword: connmark == '''''connmark { set <val>[/<mask>] | save [mask <mask>] | restore [mask <mask>] } [log [msg <message>]] <matches>'''''<br> This target sets a mark on a connection when you use ''connmark set <value>''; the mark for your connection is the specified <value>, or <value> ANDed with <mask>. The resulting mark value is an integer between 0 and 4,294,967,295, so you can set plenty of matches :-). The marks you set can be matched in different rules with the "connmark match", so this is a bit like a bookmark.<br> Now sometimes you have already marked a packet with the MARK target; you can subsequently push this MARK-value through to the connection using ''conmark save'', although you can slightly alter the connection mark value using the ''mask <mask>'' option, which provides a binary "and", so that only the masked bits are set.<br> This process also works the other way around: you can "restore" the mark on the connection to an individual packet using ''restore'', if need be again logically ANDed with a <mask> value. However, this last action works '''only''' in the ''mangle'' table (naturally, since it mangles the packet).<br> As an example: two lines in Iceditch language context INPUT mangle connmark set 127/192 -p tcp --dport 22 connmark restore mask 126 -p tcp --dport 22 These two commands get translated to iptables –t mangle –A INPUT –p tcp –-dport 22 \ –-jump CONNMARK --set-mark 127/192 iptables –t mangle –A INPUT –p tcp –-dport 22 \ –-jump CONNMARK --restore-mark --mask 126 The effect of the first line is that if a packet is aimed at port 22 (SSH), then its connection gets marked with value 64 (127 AND 192). The second line looks at any SSH packet, and if it finds one, it takes the mark from the connection (if any is present), and marks the packet itself with that value, ANDed with mask 128. So if the packet belongs to the connection that the ''first'' line had marked with value 64, then the packet gets marked with 64 (64 AND 126 = 64); but if the packet had belonged to a connection marked 251, then it would've gotten marked 122 (251 AND 126). == Target keyword: classify == '''''classify <classval> [log [msg <message>]] <matches>'''''<br> If a packet travelling through the mangle table in the POSTROUTING chain matches the <matches>, then it will be classified with the <classval> specified. An example: classify 2:11 –p tcp --dport 22 The script works this out to iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump CLASSIFY --setclass 2:11 Should you want to also log the packet, you’d use classify 2:11 log msg classified_2:11 –p tcp --dport 22 The script works this out to iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump LOG \ --log-prefix classified_2:11: iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump CLASSIFY \ --setclass 2:11 Should you not give a msg, then the log-prefix becomes classify_POSTROUTING_mangle. Because of how iptables handles the CLASSIFY target, you can only use it in contexts where the chain is "POSTROUTING" and the table is "mangle". == Target keyword: dnat == '''''dnat [to] <a1[-a2][:p1[-p2]]> [log [msg <message>]] <matches>'''''<br> In the above, a1 and a2 are used to specify a (range of) IP address(es); for TCP and UDP protocols, a destination port or port range can be provided. Note that the "to" in the command is optional, and serves only readability.<br> If a packet matches the qualifiers, then it will be destination-NATted to the provided IP address or address range. For example, if you want to DNAT port 81 on your external interface eth1 to an internal webserver on 10.0.0.1, you could use context "PREROUTING" "nat" dnat to 10.0.0.1:80 –p tcp –i eth1 –-dport 81 If you give a range of IP addresses, then the DNAT logic of IPtables will randomly pick an address and DNAT the packet there. However, note that a single stream will always use the same IP address from that range, and that each stream will randomly be given an IP address that it will always be destined for, within that stream.<br> Furthermore, note that the DNAT target is only available within the PREROUTING and OUTPUT chains in the nat table, and any of the chains called upon from any of those listed chains. Note that chains containing DNAT targets may not be used from any other chains, such as the POSTROUTING chain. However, the bad news is that Iceditch currently does not know how to check for the latter case, so the dnat keyword only works from contexts "PREROUTING" "nat" and "OUTPUT" "nat". == Target keyword: drop == '''''drop [log [msg <message>]] <matches> '''''<br> In essence, this does the same as the "accept" target keyword, only it jumps to DROP instead of ACCEPT. Thus any packet matching the <matches> gets discarded; it will not get sent on to its final destination (or next hop), it will not get processed by any other firewall rule, and the sender of the packet is unaware of your treatment of his packet. Should you want to also log the packet, you’d use context "FORWARD" "filter" drop log –p tcp -s 10.0.0.0/16 The script works this out to iptables –t filter –A FORWARD –p tcp -s 10.0.0.0/16 –-jump LOG \ --log-prefix drop_FORWARD_filter: iptables –t filter –A FORWARD –p tcp -s 10.0.0.0/16 –-jump DROP However, be advised that using DROP may leave dead sockets on either the sending or receiving host. If you do not wish that, you might be better of using REJECT. On the other hand, dropping packets is a nice way of appearing like a black hole, so it's the weapon of choice against port scanners and the likes.<br> The DROP target can be used in any chain in any table. == Target keyword: ipv4optsstrip == '''''ipv4optsstrip [log [msg <message>]] <matches>'''''<br> This target takes any packet that fits the <matches>, and then strips off all IPv4 options from its header. It can only be used in the ''mangle'' table. For example, the following rule strips the IPv4 options from any packet incoming on ''eth0'': context PREROUTING mangle ipv4optsstrip -i eth0 == Target keyword: tochain == '''''tochain <customchain> [log [msg <message>]] <matches>'''''<br> If you've created a custom chain within a certain table, then you can jump to this custom chain using ''tochain'', as long as the ''tochain'' invocation appears in a context with the same table. For example: create_chain FTPtraffic filter (...) context INPUT filter (...) tochain FTPtraffic -p tcp --dport 20 In this example, any TCP packet that appears in table filter, chain INPUT and is directed at port 20, is sent on through to the previously created chain FTPTRAFFIC (keep in mind that Iceditch will always translate any chain name to all uppercase). Rule matching and packet processing will continue in that chain, until an ACCEPT or DROP is encountered, or a RETURN, or all rules in the custom chain have been exhausted. After that, the implicit return policy on your custom chain will return the packet to whence it came (context INPUT filter, the line below the ''tochain'' invocation). == Target keyword: log == ''for LOG target: '''log [(msg|message) <message>] [ip-options|ipopt] [(lvl|level) <loglevel>] [tcp-options|tcpopt] [tcp-sequence|tcpseq] <matches>'''''<br> ''for ULOG target: '''log [(msg|message) <message>] [cprange <range>] [qtreshold|qtresh <treshold>] <matches>''''' Sometimes, the standard ''log'' parameter is just not enough. This can be the case when you want to log a packet with one or more of the extra options beside ''--log-prefix''. Or maybe you want to just log a certain type or class of packets, without performing an action on those packets just yet, so that you can't use ''log'' as a parameter to one of the other Iceditch keywords.<br> For this reason, AND for flexibility and clarity, Iceditch has the dedicated target keyword ''log''.<br> Just as when you use the ''log'' '''parameter''' after another target keyword, the use of the log '''target''' will make Iceditch call upon the logging daemon specified in the Iceditch [[Iceditch file structure | config file]]. Standard this is LOG, but optionally you could specify ULOG in the config file. Note that an explicit call on target keyword ''log'' gives one the option to specify extra parameters, but also note that the choice of which parameters you can use depends on your configured choice of logging daemon. === The message to log === Now the message that gets logged is treated the same by Iceditch, no matter which logging daemon you use. Somewhere after the target keyword ''log'' (but before any of the <''matches''>) you specify ''msg <message>'' (or ''message <message>''). The ''<message>'' can be any string between 1 and some 29 characters max (letters, numbers and underscores; no spaces, not empty). If you do NOT specify a message, Iceditch will always create a default log message: ''<chain>_&lt;table&gt;_log''. This means that <pre>context INPUT filter log -p tcp --dport 22 </pre> will result in either one of the iptables lines shown below, depending on your choice of logging daemon: <pre>iptables -A INPUT -t filter -p tcp --dport 22 --jump LOG --log-prefix INPUT_filter_log --log-level 4 iptables -A INPUT -t filter -p tcp --dport 22 --jump ULOG --ulog-prefix INPUT_filter_log </pre> (note the default log level when using the ''syslog'' logging daemon). === Log parameters when using the ''syslog'' logging daemon=== Besides a log message, there are four more options that you can also specify. All five options are shown in the table below: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" ! colspan="3" style="background:#ffdead;"|LOG options |- !style="background:#ffdead;"|Iceditch option !style="background:#ffdead;"|IPtables option !style="background:#ffdead;"|Description |- |ip-options / ipopt | --log-ip-options |Makes Netfilter include the IP options in the log entry |- | lvl / level <''loglevel''> | --log-level <''loglevel''> | Makes Netfilter log with the specified <''loglevel''> |- | msg / message <''logmessage''> | --log-prefix <''logmessage''> | Makes Netfilter prepend <''logmessage''> to the log entry |- | tcp-options / tcpopt | --log-tcp-options |Makes Netfilter include the TCP options in the log entry |- | tcp-sequence / tcpseq | --log-tcp-sequence |Makes Netfilter include the TCP sequence number in the log entry |- |} On the log-level: when using the ''syslog'' daemon (IPtables target LOG), it is possible to specify a log level. The log level can be specified numerically or by name; Iceditch will translate it to its numerical value. However, if you do NOT specify a log level, Iceditch will include a default log level, being 4 (warn). For completeness, we here reproduce the list of logging levels that ''log'' understands: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Level !style="background:#ffdead;"|Description |- |0 |''emerg'' or ''panic'' |- |1 |''alert'' |- |2 |''crit'' |- |3 |''err'' |- |4 |''warn'' (default) |- |5 |''notice'' |- |6 |''info'' |- |7 |''debug'' |- |} === Log parameters when using the ''ulog'' user space logging daemon=== {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" ! colspan="3" style="background:#ffdead;"|ULOG options |- !style="background:#ffdead;"|Iceditch option !style="background:#ffdead;"|IPtables option !style="background:#ffdead;"|Description |- | cprange <''size''> | --ulog-cprange <''size''> |log the first ''size'' bytes of each packet |- | msg / message <''logmessage''> | --log-prefix <''logmessage''> | Makes Netfilter prepend <''logmessage''> to the log entry |- | qtreshold / qtresh <''value''> | --ulog-qthreshold <''value''> |Queue ''value'' packets before sending them to ''ulogd'' (default = 1, max = 50) |- |} <br> Now an example: context "INPUT" "filter" log lvl info msg SSH_incoming -p tcp --dport 22 -i $inetIF Iceditch works this out into iptables -A INPUT -t filter -p tcp --dport 22 -i $inetIF --jump ULOG --ulog-prefix "SSH_incoming" --log-level 6 == Target keyword: mark == '''''mark <markval> [log [msg <message>]] <matches>'''''<br> If a packet matches the <matches>, then it will be marked with the <markval> specified. An example from the context PREROUTING mangle: mark 2 –p tcp --dport 22 Iceditch works this out to iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump MARK --setmark 2 Should you want to also log the packet, you’d use mark 2 log –p tcp --dport 22 Iceditch works this out to iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump LOG \ --log-prefix mark_PREROUTING_mangle: iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump MARK --setmark 2 Because of how iptables handles the MARK target, you can only use it in contexts where the table is ''mangle''. == Target keyword: masquerade == '''''masquerade <iface> [to <p1[-p2]>] [log [msg <message>]] <matches>'''''<br> <iface> is the (outward facing) network interface that we want to masquerade on.<br> The MASQUERADE target is used basically the same as the SNAT target, but it does not require any ''--to-source'' option. The reason for this is that the MASQUERADE target was made to work with connections which get dynamic IP addresses when connecting to the network in question, for example dial-up connections, or DHCP connections. This means that you should only use the MASQUERADE target with dynamically assigned IP connections, which we don't know the actual IP address of in advance. If you have a static IP connection, you should instead use the SNAT target.<br> When you masquerade a connection, it means that we set the IP address used on a specific network ''interface'', instead of getting it from the ''--to-source option''. The necessary IP address is automatically grabbed from the information about the specific interface. Using the ''masquerade'' keyword also has the advantage that connections are forgotten when an interface goes down, which is extremely good if we, for example, kill a specific interface. If we would have used the SNAT target, we may have been left with a lot of old connection tracking data, which would be kept in connection tracking memory for days. forgetting about connections is, in general, the correct behavior when dealing with dial-up lines that are probably assigned a different IP every time they are brought up. In case we are assigned a different IP, the connection is lost anyways, and it is more or less idiotic to keep the entry around.<br> It is still possible to use the MASQUERADE target instead of SNAT even though you do have a static IP; however, it is not favorable since it will add extra overhead, and there may be inconsistencies in the future which will thwart your existing scripts and render them "unusable".<br> Note that the MASQUERADE target is only valid within the POSTROUTING chain in the nat table, just as the SNAT target. == Target keyword: nojump == '''''nojump [log [msg <message>]] <matches>'''''<br> ''nojump'' creates an iptables rule with an empty jump target. This means that the match is made, but no action is undertaken on the match. OK, so why do we even ''need'' a "nojump" target if it doesn't create an IPtables jump? As far as we know, two valid reasons might be:<br> === using nojump for auditing === A ''nojump'' rule can be used for '''auditing'''. Say you want to know how often you are pinged from IP 1.2.3.4 - without logging each and every ping request to the firewall logfile. You could write context INPUT filter nojump -p icmp --icmp-type 8 -s 1.2.3.4</pre> This rule could be checked in IPtables with ''iptables -n -L'' as <pre> Chain INPUT (policy DROP 1713K packets, 119M bytes) pkts bytes target prot opt in out source destination 0 0 icmp -- * * 1.2.3.4 0.0.0.0/0 icmp type 8</pre> Good to know you haven't been pinged by 1.2.3.4 yet, eh?!<br> === using nojump to apply matches without using targets === A ''nojump'' rule can be used to '''apply matches''' like ''recent'', that may just happily act on their own. Say you want to block spurious SSH login attempts; if "spurious" to you means "more than two connection attempts per minute", then you could try: context INPUT filter nojump -p tcp --dport 22 -i $inetIF -m state --state NEW -m recent --name SSHers --set drop -p tcp --dport 22 -i $inetIF -m state --state NEW -m recent --name SSHers --update --seconds 60 --hitcount 3 This causes Iceditch to add the IP of every connection attempt to your SSH port to a list named "SSHers", and consecutively, that every packet that fits this description AND has seen two more hits from the same source address in the last 60 seconds gets dropped. Essentially, this limits brute-force attackers on your SSH to trying 2 logins per minute at most. But you see that the nojump rule gets translated to iptables -A INPUT -t filter -p tcp --dport 22 -i $inetIF -m state --state NEW -m recent --name SSHers --set No ''--jump'' in that line - hence the name of the Iceditch target: ''nojump''. == Target keyword: redirect == '''''redirect [to <to-ports>] [log [msg <message>]] <matches>'''''<br> If a packet matches the <matches>, then it will be redirected to the local machine, by setting the destination IP to a fitting IP address of the local machine (i.e. 127.0.0.1, or the first-bound IP address of the interface over which it came in. Additionally, by specifying “to <to-ports>” you can have the destination ports redirected to a port or portrange. <to-ports> can either be a port number (e.g. 8080) or a port range (e.g. 6661-6669; the latter is inclusive). Example for a transparent HTTP proxy: context "OUTPUT" "nat" redirect to 8080 –p tcp --dport 80 Iceditch works this out to iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump REDIRECT –to-ports 8080 Should you want to log the packet, you could use redirect to 8080 log –p tcp --dport 80 Iceditch works this out to iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump LOG \ --log-prefix OUTPUT_REDIRECT_to_8080: iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump REDIRECT –-to-ports 8080 Because of how iptables handles the REDIRECT target, you can only use it in contexts where the table is "nat" and the chain is PREROUTING or OUTPUT. == Target keyword: reject == '''''reject [with <type>] [log [msg <message>]] <matches>'''''<br> In essence, this does the same as the "drop" target keyword, only it jumps to REJECT instead of DROP. This means the packet is discarded (just as with DROP), but the sender is notified using ICMP (by default, your machine will send an ICMP-packet of type "icmp-port-unreachable"). Because of how iptables handles the REJECT target, you can only use it in contexts where the table is "filter". Optionally, you can follow "reject" with the keyword "with", and then use one of the following rejection types: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Type !style="background:#ffdead;"|Description |- | icmp-host-prohibited | will send an ICMP-message "host prohibited" |- | icmp-host-unreachable | will send an ICMP-message "host unreachable" |- | icmp-net-prohibited | will send an ICMP-message "net prohibited" |- | icmp-net-unreachable | will send an ICMP-message "net unreachable" |- | icmp-port-unreachable | DEFAULT; will send an ICMP-message "port unreachable" |- | icmp-proto-unreachable | DEFAULT; will send an ICMP-message "protocol unreachable" |- | tcp-reset | will send a TCP reset, a packet with the RST flag set (as a response to a TCP packet only) |- | host-prohib | synonymous to icmp-host-prohibited |- | host-unreach | synonymous to icmp-host-unreachable |- | net-prohib | synonymous to icmp-net-prohibited |- | net-unreach | synonymous to icmp-net-unreachable |- | port-unreach | synonymous to icmp-port-unreachable |- | proto-unreach | synonymous to icmp-proto-unreachable |- |} If you don’t specify "with <type>", then netfilter will assume icmp-port-unreachable. Thus, should you want to reject a packet in context filter INPUT (and log it) with reason net-prohib, you’d use reject with net-prohib log –p tcp –i eth0 --dport 22 Iceditch works this out to iptables –t filter –A INPUT –p tcp –i eth0 –-dport 22 –-jump LOG \ --log-prefix INPUT_REJECT_with_net-prohib: iptables –t filter –A INPUT –p tcp –i eth0 –-dport 22 \ –-jump REJECT –-reject-with net-prohib –p tcp –i eth0 –-dport 22 Note: RFC behavior is that unbound TCP ports return resets on connections, and unbound UDP ports return ICMP port unreachable. If you want to make your firewall less obtrusive, then do that. Your filtered ports will then be (at least in that respect) indistinguishable from unfiltered, unbound ports. ==Target keyword: route== '''''route {<iface>|<ifaceindex>} [log [msg <message>]] <matches>'''''<br> The ''route'' target lets you route a received packet through an interface or towards a host, even if the regular destination of the packet is the router itself. The ROUTE target is also able to change the incoming interface of a packet. Packets are directly put on the wire and do not traverse any other table.<br> ''route'' takes one mandatory option, which may be either the interface name over which to route the packet that matches the <matches>, or the index number of that interface (based on the order in /proc/net/dev). Iceditch is pretty lazy in how to interpret that option: if it's all numerals, Iceditch treats it as the interface index number, if it contains any other character, it is considered the interface name (e.g. ''eth0''); and no sanity check is performed on the specified <iface|ifaceindex>. == Target keyword: same== '''''same [to <a1[-a2]> [to <a3[-a4]>] ] [nodest] [log [msg <message>] ] <matches>'''''<br> ''same'' only works in the nat table, in the POSTROUTING chain. It is very closely related to ''snat'' (see below), because it does virtually the same thing. Basically, the ''same'' target will try to always use the same outgoing IP address for all connections initiated by a single host on your network. For example, say you have one "internal" /24 network (192.168.1.0) and 3 "external" IP addresses (10.5.6.11-13) on your firewall/router machine. Now, if internal machine 192.168.1.20 went out through the .11 address the first time, then the firewall will try to keep that machine always going out through that same IP address. So basically ''same'' might be a better fit than ''snat'' if you have multiple external IP addresses.<br> However, there is also functionality lacking in ''same'' that ''snat'' has, namely the specification of (TCP and UDP) ports or port ranges to use for the NATting operation. See ''snat'' for its port possibilities.<br> Furthermore, ''same'' has an extra option that ''snat'' does not have: under normal action, the ''same'' target is calculating the followup connections based on both destination and source IP addresses. Using the ''nodest'' option (which corresponds with --nodst in the actual IPtables command), it uses only the source IP address to find out which outgoing IP the NAT function should use for the specific connection. Without this argument, it uses a combination of the destination and source IP address. == Target keyword: snat== '''''snat [to <a1[-a2][:p1-p2]]> [to <a3[-a4][:p3-p4]]>] ] [log [msg <message>] ] <matches>'''''<br> This keyword is only valid in the chain POSTROUTING, table nat. And ofcourse, source NATting does you little good if you haven't enabled forwarding (e.g. use this machine as a router for other machines on your network).<br> Calling snat with the right parameters will create a Source NATting rule for you, whereby a packet matching the <matches> will be source NATted using the source IP address ''a1'' (or the range ''a1-a2''). Ofcourse, ''a1[-a2]'' should be valid IP address(es) of the firewalling machine.<br> Furthermore, if a port range ''p1-p2'' is specified, then you'll limit the range of ports that ''snat'' will use outbound (only valid for TCP or UDP packets).<br> Finally, it is possible to specify ''multiple'' IP address ranges and port ranges, using multiple ''to <a1[-a2][:p1-p2]]'' declarations in succession.<br> An example would be: context "POSTROUTING" "nat" snat to $inetIP -o $inetIF ! --src $inetIP If the variable ''$inetIP'' contains your public IP (e.g. 212.238.151.72), and ''$inetIF'' your interface connected to the Internet (e.g. ''eth0''), then this rule would expand to iptables -A POSTROUTING -t nat -o eth0 ! --src 212.238.151.72 -j SNAT --to-source 212.238.151.72 This would cause Iceditch to source NAT any outbound packet that is NOT sent by your firewall itself; in effect your server is now a nice fullblown NAT router for all machines on your private network. a811589fbd5713205f0bfe705be235f30916116d 2578 2577 2010-07-06T17:42:18Z Saruman! 2 Reverted edits by [[Special:Contributions/85.17.90.205|85.17.90.205]] ([[User talk:85.17.90.205|Talk]]) to last revision by [[User:Saruman!|Saruman!]] wikitext text/x-wiki == Parameter: log == ''target '''log [(msg|message) <message>]''' <matches>''<br> After most keywords, a "log" parameter can be added (see below). If the "log" parameter is followed by "msg" (or "message"), then the parameter following "msg" is read and used as log-prefix. The parameter is not allowed to have whitespace (that limitation is Iceditch-specific, not IPtables-related), and the maximum length of the log-prefix is determined by your version of netfilter/IPtables and your choice of IPtables logging utility (syslogemu or ulog); this limit is usually some 29 characters. Note that Iceditch does not perform any sanity checks on the message. Thus a packet matching the <matches> part of the rule will be logged with the default setting of the "log" target. If the "log" parameter is ''not'' followed by "msg", then the packet will be logged with a default log message, being "&lt;table&gt;_<chain>_<target>" and all the other default setting of the "log" target. Thus, should you want to log a packet with more control over the logging parameters, then you need an extra line, beginning with the ''target keyword'' "log", instead of just following the target keyword with parameter ''log''. For more information, see the [[Iceditch_Command_Reference#Target_keyword:_log | target keyword "log"]] below. == Context keyword: context == '''''context <chain> &lt;table&gt;'''''<br> Every IPtables rule is written to a chain in a table; with Iceditch, you don't have to specify the chain and table in every line. Just precede the lines with the ''context'' statement. Example: context POSTROUTING nat Notes: the order of chain and table does not matter; ''context nat POSTROUTING'' works just as well. Furthermore, <chain> and &lt;table&gt; have been made case-insensitive; whatever you specify as chain will be translated to uppercase, whatever you specify as table will be translated to lowercase. This gives you the possibility to write the context as you like to read it, e.g. ''context Postrouting Nat''; after processing this, Iceditch will have two variables $CHAIN="POSTROUTING" and $TABLE="nat" that it will use in every following command. For example: context "Input" "fIlTeR" accept -p tcp --dport 22 will result in the following IPtables call: iptables -A INPUT -t filter -p tcp --dport 22 --jump ACCEPT If you do NOT specify a [[Iceditch IPtables language | valid combination]] of chain and table, the execution of Iceditch will halt with a fatal error. It is allowed (but not recommended) to call ''context'' multiple times for the same combination of chain and table; the order in which the rules are added to that chain in that table, is the same in which they appear in your rulefile, top to bottom. This is not recommended, because we feel it decreases readability, and thus maintainability, of the rules file. But hey, it's going to be ''your'' rulefile anyway...<br> Note: you cannot create custom chains by the names of mangle, nat or filter, since Iceditch will always interpret these names as those of tables. == Context keyword: create_chain == '''''create_chain <chain> [&lt;table&gt;]'''''<br> This command creates a new chain named <chain>, in the specified table &lt;table&gt;. If no table is specified, then the ''filter'' table is assumed. Just as with the ''context'' command, the <chain> name you specify will be translated to all uppercase.<br> The name for your new chain must be unique, although just like the built-in chains, you can specify the same name in different tables. If you create "fun-filter" in table ''filter'', and then create a "fun-filter" in table ''nat'', then you actually have two different chains. But remember: since Iceditch translates every chain name to uppercase, you can't create "Fun-filter" AND "fun-FILTER" in the same table - they're the same chain.<br> NOTE: after you've run ''create_chain'', you still have to switch context to create rules in the new chain! example:<br> create_chain fun-filter context fun-filter filter accept -p tcp --dport 22 This will result in iptables -N FUN-FILTER -t filter iptables -A FUN-FILTER -t filter -p tcp --dport 22 --jump ACCEPT == Target keyword: accept == '''''accept [log [msg <message>]] <matches>'''''<br> If a network packet fits the <matches>, then it will be accepted (passed) through the table/chain defined in the context where you put the accept rule. Example: context Input Filter accept –p tcp --dport 22 Iceditch works this out to iptables –t filter –A INPUT –p tcp –-dport 22 –-jump ACCEPT Should you want to log the packet, you’d use context Input Filter accept log –p tcp --dport 22 Iceditch works this out to iptables –t filter –A INPUT –p tcp –-dport 22 \ –-jump LOG --log-prefix accept_INPUT_filter iptables –t filter –A INPUT –p tcp –-dport 22 –-jump ACCEPT Note: the ACCEPT target is valid in any user-manipulable table/chain combination == Target keyword: connmark == '''''connmark { set <val>[/<mask>] | save [mask <mask>] | restore [mask <mask>] } [log [msg <message>]] <matches>'''''<br> This target sets a mark on a connection when you use ''connmark set <value>''; the mark for your connection is the specified <value>, or <value> ANDed with <mask>. The resulting mark value is an integer between 0 and 4,294,967,295, so you can set plenty of matches :-). The marks you set can be matched in different rules with the "connmark match", so this is a bit like a bookmark.<br> Now sometimes you have already marked a packet with the MARK target; you can subsequently push this MARK-value through to the connection using ''conmark save'', although you can slightly alter the connection mark value using the ''mask <mask>'' option, which provides a binary "and", so that only the masked bits are set.<br> This process also works the other way around: you can "restore" the mark on the connection to an individual packet using ''restore'', if need be again logically ANDed with a <mask> value. However, this last action works '''only''' in the ''mangle'' table (naturally, since it mangles the packet).<br> As an example: two lines in Iceditch language context INPUT mangle connmark set 127/192 -p tcp --dport 22 connmark restore mask 126 -p tcp --dport 22 These two commands get translated to iptables –t mangle –A INPUT –p tcp –-dport 22 \ –-jump CONNMARK --set-mark 127/192 iptables –t mangle –A INPUT –p tcp –-dport 22 \ –-jump CONNMARK --restore-mark --mask 126 The effect of the first line is that if a packet is aimed at port 22 (SSH), then its connection gets marked with value 64 (127 AND 192). The second line looks at any SSH packet, and if it finds one, it takes the mark from the connection (if any is present), and marks the packet itself with that value, ANDed with mask 128. So if the packet belongs to the connection that the ''first'' line had marked with value 64, then the packet gets marked with 64 (64 AND 126 = 64); but if the packet had belonged to a connection marked 251, then it would've gotten marked 122 (251 AND 126). == Target keyword: classify == '''''classify <classval> [log [msg <message>]] <matches>'''''<br> If a packet travelling through the mangle table in the POSTROUTING chain matches the <matches>, then it will be classified with the <classval> specified. An example: classify 2:11 –p tcp --dport 22 The script works this out to iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump CLASSIFY --setclass 2:11 Should you want to also log the packet, you’d use classify 2:11 log msg classified_2:11 –p tcp --dport 22 The script works this out to iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump LOG \ --log-prefix classified_2:11: iptables –t mangle –A POSTROUTING –p tcp –-dport 22 –-jump CLASSIFY \ --setclass 2:11 Should you not give a msg, then the log-prefix becomes classify_POSTROUTING_mangle. Because of how iptables handles the CLASSIFY target, you can only use it in contexts where the chain is "POSTROUTING" and the table is "mangle". == Target keyword: dnat == '''''dnat [to] <a1[-a2][:p1[-p2]]> [log [msg <message>]] <matches>'''''<br> In the above, a1 and a2 are used to specify a (range of) IP address(es); for TCP and UDP protocols, a destination port or port range can be provided. Note that the "to" in the command is optional, and serves only readability.<br> If a packet matches the qualifiers, then it will be destination-NATted to the provided IP address or address range. For example, if you want to DNAT port 81 on your external interface eth1 to an internal webserver on 10.0.0.1, you could use context "PREROUTING" "nat" dnat to 10.0.0.1:80 –p tcp –i eth1 –-dport 81 If you give a range of IP addresses, then the DNAT logic of IPtables will randomly pick an address and DNAT the packet there. However, note that a single stream will always use the same IP address from that range, and that each stream will randomly be given an IP address that it will always be destined for, within that stream.<br> Furthermore, note that the DNAT target is only available within the PREROUTING and OUTPUT chains in the nat table, and any of the chains called upon from any of those listed chains. Note that chains containing DNAT targets may not be used from any other chains, such as the POSTROUTING chain. However, the bad news is that Iceditch currently does not know how to check for the latter case, so the dnat keyword only works from contexts "PREROUTING" "nat" and "OUTPUT" "nat". == Target keyword: drop == '''''drop [log [msg <message>]] <matches> '''''<br> In essence, this does the same as the "accept" target keyword, only it jumps to DROP instead of ACCEPT. Thus any packet matching the <matches> gets discarded; it will not get sent on to its final destination (or next hop), it will not get processed by any other firewall rule, and the sender of the packet is unaware of your treatment of his packet. Should you want to also log the packet, you’d use context "FORWARD" "filter" drop log –p tcp -s 10.0.0.0/16 The script works this out to iptables –t filter –A FORWARD –p tcp -s 10.0.0.0/16 –-jump LOG \ --log-prefix drop_FORWARD_filter: iptables –t filter –A FORWARD –p tcp -s 10.0.0.0/16 –-jump DROP However, be advised that using DROP may leave dead sockets on either the sending or receiving host. If you do not wish that, you might be better of using REJECT. On the other hand, dropping packets is a nice way of appearing like a black hole, so it's the weapon of choice against port scanners and the likes.<br> The DROP target can be used in any chain in any table. == Target keyword: ipv4optsstrip == '''''ipv4optsstrip [log [msg <message>]] <matches>'''''<br> This target takes any packet that fits the <matches>, and then strips off all IPv4 options from its header. It can only be used in the ''mangle'' table. For example, the following rule strips the IPv4 options from any packet incoming on ''eth0'': context PREROUTING mangle ipv4optsstrip -i eth0 == Target keyword: tochain == '''''tochain <customchain> [log [msg <message>]] <matches>'''''<br> If you've created a custom chain within a certain table, then you can jump to this custom chain using ''tochain'', as long as the ''tochain'' invocation appears in a context with the same table. For example: create_chain FTPtraffic filter (...) context INPUT filter (...) tochain FTPtraffic -p tcp --dport 20 In this example, any TCP packet that appears in table filter, chain INPUT and is directed at port 20, is sent on through to the previously created chain FTPTRAFFIC (keep in mind that Iceditch will always translate any chain name to all uppercase). Rule matching and packet processing will continue in that chain, until an ACCEPT or DROP is encountered, or a RETURN, or all rules in the custom chain have been exhausted. After that, the implicit return policy on your custom chain will return the packet to whence it came (context INPUT filter, the line below the ''tochain'' invocation). == Target keyword: log == ''for LOG target: '''log [(msg|message) <message>] [ip-options|ipopt] [(lvl|level) <loglevel>] [tcp-options|tcpopt] [tcp-sequence|tcpseq] <matches>'''''<br> ''for ULOG target: '''log [(msg|message) <message>] [cprange <range>] [qtreshold|qtresh <treshold>] <matches>''''' Sometimes, the standard ''log'' parameter is just not enough. This can be the case when you want to log a packet with one or more of the extra options beside ''--log-prefix''. Or maybe you want to just log a certain type or class of packets, without performing an action on those packets just yet, so that you can't use ''log'' as a parameter to one of the other Iceditch keywords.<br> For this reason, AND for flexibility and clarity, Iceditch has the dedicated target keyword ''log''.<br> Just as when you use the ''log'' '''parameter''' after another target keyword, the use of the log '''target''' will make Iceditch call upon the logging daemon specified in the Iceditch [[Iceditch file structure | config file]]. Standard this is LOG, but optionally you could specify ULOG in the config file. Note that an explicit call on target keyword ''log'' gives one the option to specify extra parameters, but also note that the choice of which parameters you can use depends on your configured choice of logging daemon. === The message to log === Now the message that gets logged is treated the same by Iceditch, no matter which logging daemon you use. Somewhere after the target keyword ''log'' (but before any of the <''matches''>) you specify ''msg <message>'' (or ''message <message>''). The ''<message>'' can be any string between 1 and some 29 characters max (letters, numbers and underscores; no spaces, not empty). If you do NOT specify a message, Iceditch will always create a default log message: ''<chain>_&lt;table&gt;_log''. This means that <pre>context INPUT filter log -p tcp --dport 22 </pre> will result in either one of the iptables lines shown below, depending on your choice of logging daemon: <pre>iptables -A INPUT -t filter -p tcp --dport 22 --jump LOG --log-prefix INPUT_filter_log --log-level 4 iptables -A INPUT -t filter -p tcp --dport 22 --jump ULOG --ulog-prefix INPUT_filter_log </pre> (note the default log level when using the ''syslog'' logging daemon). === Log parameters when using the ''syslog'' logging daemon=== Besides a log message, there are four more options that you can also specify. All five options are shown in the table below: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" ! colspan="3" style="background:#ffdead;"|LOG options |- !style="background:#ffdead;"|Iceditch option !style="background:#ffdead;"|IPtables option !style="background:#ffdead;"|Description |- |ip-options / ipopt | --log-ip-options |Makes Netfilter include the IP options in the log entry |- | lvl / level <''loglevel''> | --log-level <''loglevel''> | Makes Netfilter log with the specified <''loglevel''> |- | msg / message <''logmessage''> | --log-prefix <''logmessage''> | Makes Netfilter prepend <''logmessage''> to the log entry |- | tcp-options / tcpopt | --log-tcp-options |Makes Netfilter include the TCP options in the log entry |- | tcp-sequence / tcpseq | --log-tcp-sequence |Makes Netfilter include the TCP sequence number in the log entry |- |} On the log-level: when using the ''syslog'' daemon (IPtables target LOG), it is possible to specify a log level. The log level can be specified numerically or by name; Iceditch will translate it to its numerical value. However, if you do NOT specify a log level, Iceditch will include a default log level, being 4 (warn). For completeness, we here reproduce the list of logging levels that ''log'' understands: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Level !style="background:#ffdead;"|Description |- |0 |''emerg'' or ''panic'' |- |1 |''alert'' |- |2 |''crit'' |- |3 |''err'' |- |4 |''warn'' (default) |- |5 |''notice'' |- |6 |''info'' |- |7 |''debug'' |- |} === Log parameters when using the ''ulog'' user space logging daemon=== {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" ! colspan="3" style="background:#ffdead;"|ULOG options |- !style="background:#ffdead;"|Iceditch option !style="background:#ffdead;"|IPtables option !style="background:#ffdead;"|Description |- | cprange <''size''> | --ulog-cprange <''size''> |log the first ''size'' bytes of each packet |- | msg / message <''logmessage''> | --log-prefix <''logmessage''> | Makes Netfilter prepend <''logmessage''> to the log entry |- | qtreshold / qtresh <''value''> | --ulog-qthreshold <''value''> |Queue ''value'' packets before sending them to ''ulogd'' (default = 1, max = 50) |- |} <br> Now an example: context "INPUT" "filter" log lvl info msg SSH_incoming -p tcp --dport 22 -i $inetIF Iceditch works this out into iptables -A INPUT -t filter -p tcp --dport 22 -i $inetIF --jump ULOG --ulog-prefix "SSH_incoming" --log-level 6 == Target keyword: mark == '''''mark <markval> [log [msg <message>]] <matches>'''''<br> If a packet matches the <matches>, then it will be marked with the <markval> specified. An example from the context PREROUTING mangle: mark 2 –p tcp --dport 22 Iceditch works this out to iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump MARK --setmark 2 Should you want to also log the packet, you’d use mark 2 log –p tcp --dport 22 Iceditch works this out to iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump LOG \ --log-prefix mark_PREROUTING_mangle: iptables –t mangle –A PREROUTING –p tcp –-dport 22 –-jump MARK --setmark 2 Because of how iptables handles the MARK target, you can only use it in contexts where the table is ''mangle''. == Target keyword: masquerade == '''''masquerade <iface> [to <p1[-p2]>] [log [msg <message>]] <matches>'''''<br> <iface> is the (outward facing) network interface that we want to masquerade on.<br> The MASQUERADE target is used basically the same as the SNAT target, but it does not require any ''--to-source'' option. The reason for this is that the MASQUERADE target was made to work with connections which get dynamic IP addresses when connecting to the network in question, for example dial-up connections, or DHCP connections. This means that you should only use the MASQUERADE target with dynamically assigned IP connections, which we don't know the actual IP address of in advance. If you have a static IP connection, you should instead use the SNAT target.<br> When you masquerade a connection, it means that we set the IP address used on a specific network ''interface'', instead of getting it from the ''--to-source option''. The necessary IP address is automatically grabbed from the information about the specific interface. Using the ''masquerade'' keyword also has the advantage that connections are forgotten when an interface goes down, which is extremely good if we, for example, kill a specific interface. If we would have used the SNAT target, we may have been left with a lot of old connection tracking data, which would be kept in connection tracking memory for days. forgetting about connections is, in general, the correct behavior when dealing with dial-up lines that are probably assigned a different IP every time they are brought up. In case we are assigned a different IP, the connection is lost anyways, and it is more or less idiotic to keep the entry around.<br> It is still possible to use the MASQUERADE target instead of SNAT even though you do have a static IP; however, it is not favorable since it will add extra overhead, and there may be inconsistencies in the future which will thwart your existing scripts and render them "unusable".<br> Note that the MASQUERADE target is only valid within the POSTROUTING chain in the nat table, just as the SNAT target. == Target keyword: nojump == '''''nojump [log [msg <message>]] <matches>'''''<br> ''nojump'' creates an iptables rule with an empty jump target. This means that the match is made, but no action is undertaken on the match. OK, so why do we even ''need'' a "nojump" target if it doesn't create an IPtables jump? As far as we know, two valid reasons might be:<br> === using nojump for auditing === A ''nojump'' rule can be used for '''auditing'''. Say you want to know how often you are pinged from IP 1.2.3.4 - without logging each and every ping request to the firewall logfile. You could write context INPUT filter nojump -p icmp --icmp-type 8 -s 1.2.3.4</pre> This rule could be checked in IPtables with ''iptables -n -L'' as <pre> Chain INPUT (policy DROP 1713K packets, 119M bytes) pkts bytes target prot opt in out source destination 0 0 icmp -- * * 1.2.3.4 0.0.0.0/0 icmp type 8</pre> Good to know you haven't been pinged by 1.2.3.4 yet, eh?!<br> === using nojump to apply matches without using targets === A ''nojump'' rule can be used to '''apply matches''' like ''recent'', that may just happily act on their own. Say you want to block spurious SSH login attempts; if "spurious" to you means "more than two connection attempts per minute", then you could try: context INPUT filter nojump -p tcp --dport 22 -i $inetIF -m state --state NEW -m recent --name SSHers --set drop -p tcp --dport 22 -i $inetIF -m state --state NEW -m recent --name SSHers --update --seconds 60 --hitcount 3 This causes Iceditch to add the IP of every connection attempt to your SSH port to a list named "SSHers", and consecutively, that every packet that fits this description AND has seen two more hits from the same source address in the last 60 seconds gets dropped. Essentially, this limits brute-force attackers on your SSH to trying 2 logins per minute at most. But you see that the nojump rule gets translated to iptables -A INPUT -t filter -p tcp --dport 22 -i $inetIF -m state --state NEW -m recent --name SSHers --set No ''--jump'' in that line - hence the name of the Iceditch target: ''nojump''. == Target keyword: redirect == '''''redirect [to <to-ports>] [log [msg <message>]] <matches>'''''<br> If a packet matches the <matches>, then it will be redirected to the local machine, by setting the destination IP to a fitting IP address of the local machine (i.e. 127.0.0.1, or the first-bound IP address of the interface over which it came in. Additionally, by specifying “to <to-ports>” you can have the destination ports redirected to a port or portrange. <to-ports> can either be a port number (e.g. 8080) or a port range (e.g. 6661-6669; the latter is inclusive). Example for a transparent HTTP proxy: context "OUTPUT" "nat" redirect to 8080 –p tcp --dport 80 Iceditch works this out to iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump REDIRECT –to-ports 8080 Should you want to log the packet, you could use redirect to 8080 log –p tcp --dport 80 Iceditch works this out to iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump LOG \ --log-prefix OUTPUT_REDIRECT_to_8080: iptables –t nat –A OUTPUT –p tcp –-dport 80 –-jump REDIRECT –-to-ports 8080 Because of how iptables handles the REDIRECT target, you can only use it in contexts where the table is "nat" and the chain is PREROUTING or OUTPUT. == Target keyword: reject == '''''reject [with <type>] [log [msg <message>]] <matches>'''''<br> In essence, this does the same as the "drop" target keyword, only it jumps to REJECT instead of DROP. This means the packet is discarded (just as with DROP), but the sender is notified using ICMP (by default, your machine will send an ICMP-packet of type "icmp-port-unreachable"). Because of how iptables handles the REJECT target, you can only use it in contexts where the table is "filter". Optionally, you can follow "reject" with the keyword "with", and then use one of the following rejection types: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Type !style="background:#ffdead;"|Description |- | icmp-host-prohibited | will send an ICMP-message "host prohibited" |- | icmp-host-unreachable | will send an ICMP-message "host unreachable" |- | icmp-net-prohibited | will send an ICMP-message "net prohibited" |- | icmp-net-unreachable | will send an ICMP-message "net unreachable" |- | icmp-port-unreachable | DEFAULT; will send an ICMP-message "port unreachable" |- | icmp-proto-unreachable | DEFAULT; will send an ICMP-message "protocol unreachable" |- | tcp-reset | will send a TCP reset, a packet with the RST flag set (as a response to a TCP packet only) |- | host-prohib | synonymous to icmp-host-prohibited |- | host-unreach | synonymous to icmp-host-unreachable |- | net-prohib | synonymous to icmp-net-prohibited |- | net-unreach | synonymous to icmp-net-unreachable |- | port-unreach | synonymous to icmp-port-unreachable |- | proto-unreach | synonymous to icmp-proto-unreachable |- |} If you don’t specify "with <type>", then netfilter will assume icmp-port-unreachable. Thus, should you want to reject a packet in context filter INPUT (and log it) with reason net-prohib, you’d use reject with net-prohib log –p tcp –i eth0 --dport 22 Iceditch works this out to iptables –t filter –A INPUT –p tcp –i eth0 –-dport 22 –-jump LOG \ --log-prefix INPUT_REJECT_with_net-prohib: iptables –t filter –A INPUT –p tcp –i eth0 –-dport 22 \ –-jump REJECT –-reject-with net-prohib –p tcp –i eth0 –-dport 22 Note: RFC behavior is that unbound TCP ports return resets on connections, and unbound UDP ports return ICMP port unreachable. If you want to make your firewall less obtrusive, then do that. Your filtered ports will then be (at least in that respect) indistinguishable from unfiltered, unbound ports. ==Target keyword: route== '''''route {<iface>|<ifaceindex>} [log [msg <message>]] <matches>'''''<br> The ''route'' target lets you route a received packet through an interface or towards a host, even if the regular destination of the packet is the router itself. The ROUTE target is also able to change the incoming interface of a packet. Packets are directly put on the wire and do not traverse any other table.<br> ''route'' takes one mandatory option, which may be either the interface name over which to route the packet that matches the <matches>, or the index number of that interface (based on the order in /proc/net/dev). Iceditch is pretty lazy in how to interpret that option: if it's all numerals, Iceditch treats it as the interface index number, if it contains any other character, it is considered the interface name (e.g. ''eth0''); and no sanity check is performed on the specified <iface|ifaceindex>. == Target keyword: same== '''''same [to <a1[-a2]> [to <a3[-a4]>] ] [nodest] [log [msg <message>] ] <matches>'''''<br> ''same'' only works in the nat table, in the POSTROUTING chain. It is very closely related to ''snat'' (see below), because it does virtually the same thing. Basically, the ''same'' target will try to always use the same outgoing IP address for all connections initiated by a single host on your network. For example, say you have one "internal" /24 network (192.168.1.0) and 3 "external" IP addresses (10.5.6.11-13) on your firewall/router machine. Now, if internal machine 192.168.1.20 went out through the .11 address the first time, then the firewall will try to keep that machine always going out through that same IP address. So basically ''same'' might be a better fit than ''snat'' if you have multiple external IP addresses.<br> However, there is also functionality lacking in ''same'' that ''snat'' has, namely the specification of (TCP and UDP) ports or port ranges to use for the NATting operation. See ''snat'' for its port possibilities.<br> Furthermore, ''same'' has an extra option that ''snat'' does not have: under normal action, the ''same'' target is calculating the followup connections based on both destination and source IP addresses. Using the ''nodest'' option (which corresponds with --nodst in the actual IPtables command), it uses only the source IP address to find out which outgoing IP the NAT function should use for the specific connection. Without this argument, it uses a combination of the destination and source IP address. == Target keyword: snat== '''''snat [to <a1[-a2][:p1-p2]]> [to <a3[-a4][:p3-p4]]>] ] [log [msg <message>] ] <matches>'''''<br> This keyword is only valid in the chain POSTROUTING, table nat. And ofcourse, source NATting does you little good if you haven't enabled forwarding (e.g. use this machine as a router for other machines on your network).<br> Calling snat with the right parameters will create a Source NATting rule for you, whereby a packet matching the <matches> will be source NATted using the source IP address ''a1'' (or the range ''a1-a2''). Ofcourse, ''a1[-a2]'' should be valid IP address(es) of the firewalling machine.<br> Furthermore, if a port range ''p1-p2'' is specified, then you'll limit the range of ports that ''snat'' will use outbound (only valid for TCP or UDP packets).<br> Finally, it is possible to specify ''multiple'' IP address ranges and port ranges, using multiple ''to <a1[-a2][:p1-p2]]'' declarations in succession.<br> An example would be: context "POSTROUTING" "nat" snat to $inetIP -o $inetIF ! --src $inetIP If the variable ''$inetIP'' contains your public IP (e.g. 212.238.151.72), and ''$inetIF'' your interface connected to the Internet (e.g. ''eth0''), then this rule would expand to iptables -A POSTROUTING -t nat -o eth0 ! --src 212.238.151.72 -j SNAT --to-source 212.238.151.72 This would cause Iceditch to source NAT any outbound packet that is NOT sent by your firewall itself; in effect your server is now a nice fullblown NAT router for all machines on your private network. 0ec4eade8485e09e1e362eef367458c065e8ed54 0 1532 2603 2560 2010-07-31T15:10:51Z 222.161.137.199 0 /* Mediawiki Extension: Group Permissions Manager */ wikitext text/x-wiki Thanks so much! :) <a href="http://www.radiooil.com/young" title="clover hentay">clover hentay</a> [url="http://www.radiooil.com/young"]clover hentay[/url] http://www.radiooil.com/young clover hentay <a href="http://crisbase.com/comics" title="innocent hentai manga">innocent hentai manga</a> [url="http://crisbase.com/comics"]innocent hentai manga[/url] http://crisbase.com/comics innocent hentai manga <a href="http://stlukessavannah.org/porn" title="web video hentai">web video hentai</a> [url="http://stlukessavannah.org/porn"]web video hentai[/url] http://stlukessavannah.org/porn web video hentai ==Adding the extension== First, download the latest snapshot of the GroupPermissionsManager extension from here: [http://www.mediawiki.org/wiki/Extension:GroupPermissionsManager Mediawiki Extension:Group Permissions Manager]. It's a single archive with a name that looks like ''GroupPermissionsManager-trunk-r45886.tar.gz''. You can extract it straight into the Debian mediawiki extensions directory ''/usr/share/mediawiki-extensions'', that already exists if you've installed the ''[[Mediawiki-extensions_under_Debian|mediawiki-extensions]]'' package; out comes a little directory structure like this: GroupPermissionsManager |-- plugins | |-- disabled | `-- messages `-- scripts You'll have to make sure all files and directories are owned by ''root'', and that the PHP files cannot be edited by anyone else than ''root''. This will most likely not be the case: as ''root'' run: cd /usr/share/mediawiki-extensions/GroupPermissionsManager chown -R root:root * chmod -R 644 * Now, to make the extension work with Debian, we ''must'' move all files and folders under ''GroupPermissionsManager'' to ''/usr/share/mediawiki-extensions'': cd /usr/share/mediawiki-extensions/GroupPermissionsManager mv scripts .. mv plugins .. mv * .. cd .. rmdir GroupPermissionsManager Next, we have to make a small alteration to ''/usr/share/mediawiki/includes/GlobalFunctions.php'' because there's a bug or shortcoming in MediaWiki 1.12, and that's the version that Lenny uses. The alteration is described in [http://www.mediawiki.org/wiki/Extension:GroupPermissionsManager#Patch a patch prescription on the MediaWiki site], but in essence we add a line after line number 422: the line beginning with "wfRunHooks": <source lang="php"> function wfMsgGetKey( $key, $useDB, $forContent = false, $transform = true ) { global $wgParser, $wgContLang, $wgMessageCache, $wgLang; wfRunHooks( 'NormalizeMessageKey', array( &$key, &$useDB, &$langCode, &$transform ) ); </source> Next, we create a directory where Group Permissions Manager will keep the configuration files. In the Debian style, we need something under ''/etc''. We would ordinarily suggest something under ''/etc/mediawiki-extensions'', but the configuration that the extension manipulates is used by MediaWiki itself. Thus we suggest creating ''/etc/mediawiki/config''. After that, grant the permission to write in this directory to the web server daemon, for Apache2 ''www-data''.<br> Finally, create a symlink to this config directory in the place where GroupPermissionsManager actually ''expects'' it, namely in the directory where the PHP-script itself resides (here: ''/usr/share/mediawiki-extensions/''). All of this can be achieved by following these steps: cd /etc/mediawiki mkdir config chown www-data:www-data config cd /usr/share/mediawiki-extensions ln -s /etc/mediawiki/config Now we can mark the extension ''GroupPermissionsManager.php'' available to MediaWiki: cd /etc/mediawiki-extensions/extensions-available ln -s /usr/share/mediawiki-extensions/GroupPermissionsManager.php Then, enable the extension mwenext GroupPermissionsManager.php This by default adds some extra capabilities to the Mediawiki administrator group "bureaucrat", of which WikiAdmin is a member - and presumably you too. The capabilities are to use a ''Special'' page to create, manage, and remove Wiki groups and their permissions. ==Using the extension== To manage group permissions, you need the following: * your MediaWiki user account needs to be in a MediaWiki group that has been granted the right to use Group Permissions Manager, e.g. ''bureaucrat'' as depicted above; * you must be logged in with that MediaWiki account; * you need to know the name of the group whose permissions you want to manage (or create or delete). In the left navigation area, click on ''Special pages''; scroll down to the section ''Restricted special pages'', you should see an entry ''Manage Group Permissions''. Click it to enter the Manage Group Permissions special page. Here, you'll find just an empty box and a "Go" button. Fill in the name of the group you want to create/manage/delete, and click "Go". You'll find yourself in a long page with group permissions, each of which can be "true", "false" or "inherit". Setting a permission to "true" or "false" enables or disables the permission for this group, while leaving it on "inherit" means the group gets the default permission that MediaWiki assigns every group - just think of the default rights of the default group "users" Furthermore: * If the group pre-exists, you'll find above the list a comment box and a "Delete group" button, where you can remove the group, while leaving the comment in the ''GroupPermissionsLog.log'' log file. * Furthermore, if the group pre-exists, the permissions list ends with a comment box and a "Change group permissions" button. Clicking that button will change the group permissions to the set designated in the permissions list. The changes, along with all other group permissions, can be found in the ''/etc/mediawiki/config'' directory in file ''GroupPermissons.php''. Clicking the button will also have resulted in a backup of the ''GroupPermissons.php'' file in that same directory, but named ''GroupPermissons.<timestamp>.php'', e.g. ''GroupPermissions.21012009171713.php''. * If the group name is "new", no "Delete group" button is shown, but the permissions list ends with a comment box and an "Add group" button, which will create the group with the designated name, while leaving the comment in the ''GroupPermissionsLog.log'' log file. Again, the comment is logged, and a backup of the ''GroupPermissons.php'' file is made. c40b38c658113536f6512c89724b11f25d28c8b5 2608 2603 2010-08-03T09:50:04Z Saruman! 2 Reverted edits by [[Special:Contributions/222.161.137.199|222.161.137.199]] ([[User talk:222.161.137.199|Talk]]) to last revision by [[User:Saruman!|Saruman!]] wikitext text/x-wiki ==Mediawiki Extension: Group Permissions Manager== Sometimes you as a Mediawiki administrator might feel the need to add or remove a group, or edit a groups rights. Unfortunately, there is no such function in the MediaWiki software itself, you'd have to edit the ''LocalSettings.php'' file somehow: [http://www.imdb.com/title/tt0096928/ bogus!] But fortunately, there now exists an extension that adds this functionality. [http://www.imdb.com/title/tt0096928/ Most excellent!] Note: if you want to install the older version 2.00 of this plugin (which is much simpler, both in installation and in functionality), then go to the [[MediaWikiExtension GroupPermissionsManager2.00| Group Permissions Manager 2.00]] page. The instructions on this page are for the 3.2.6 version (build r45886). ==Adding the extension== First, download the latest snapshot of the GroupPermissionsManager extension from here: [http://www.mediawiki.org/wiki/Extension:GroupPermissionsManager Mediawiki Extension:Group Permissions Manager]. It's a single archive with a name that looks like ''GroupPermissionsManager-trunk-r45886.tar.gz''. You can extract it straight into the Debian mediawiki extensions directory ''/usr/share/mediawiki-extensions'', that already exists if you've installed the ''[[Mediawiki-extensions_under_Debian|mediawiki-extensions]]'' package; out comes a little directory structure like this: GroupPermissionsManager |-- plugins | |-- disabled | `-- messages `-- scripts You'll have to make sure all files and directories are owned by ''root'', and that the PHP files cannot be edited by anyone else than ''root''. This will most likely not be the case: as ''root'' run: cd /usr/share/mediawiki-extensions/GroupPermissionsManager chown -R root:root * chmod -R 644 * Now, to make the extension work with Debian, we ''must'' move all files and folders under ''GroupPermissionsManager'' to ''/usr/share/mediawiki-extensions'': cd /usr/share/mediawiki-extensions/GroupPermissionsManager mv scripts .. mv plugins .. mv * .. cd .. rmdir GroupPermissionsManager Next, we have to make a small alteration to ''/usr/share/mediawiki/includes/GlobalFunctions.php'' because there's a bug or shortcoming in MediaWiki 1.12, and that's the version that Lenny uses. The alteration is described in [http://www.mediawiki.org/wiki/Extension:GroupPermissionsManager#Patch a patch prescription on the MediaWiki site], but in essence we add a line after line number 422: the line beginning with "wfRunHooks": <source lang="php"> function wfMsgGetKey( $key, $useDB, $forContent = false, $transform = true ) { global $wgParser, $wgContLang, $wgMessageCache, $wgLang; wfRunHooks( 'NormalizeMessageKey', array( &$key, &$useDB, &$langCode, &$transform ) ); </source> Next, we create a directory where Group Permissions Manager will keep the configuration files. In the Debian style, we need something under ''/etc''. We would ordinarily suggest something under ''/etc/mediawiki-extensions'', but the configuration that the extension manipulates is used by MediaWiki itself. Thus we suggest creating ''/etc/mediawiki/config''. After that, grant the permission to write in this directory to the web server daemon, for Apache2 ''www-data''.<br> Finally, create a symlink to this config directory in the place where GroupPermissionsManager actually ''expects'' it, namely in the directory where the PHP-script itself resides (here: ''/usr/share/mediawiki-extensions/''). All of this can be achieved by following these steps: cd /etc/mediawiki mkdir config chown www-data:www-data config cd /usr/share/mediawiki-extensions ln -s /etc/mediawiki/config Now we can mark the extension ''GroupPermissionsManager.php'' available to MediaWiki: cd /etc/mediawiki-extensions/extensions-available ln -s /usr/share/mediawiki-extensions/GroupPermissionsManager.php Then, enable the extension mwenext GroupPermissionsManager.php This by default adds some extra capabilities to the Mediawiki administrator group "bureaucrat", of which WikiAdmin is a member - and presumably you too. The capabilities are to use a ''Special'' page to create, manage, and remove Wiki groups and their permissions. ==Using the extension== To manage group permissions, you need the following: * your MediaWiki user account needs to be in a MediaWiki group that has been granted the right to use Group Permissions Manager, e.g. ''bureaucrat'' as depicted above; * you must be logged in with that MediaWiki account; * you need to know the name of the group whose permissions you want to manage (or create or delete). In the left navigation area, click on ''Special pages''; scroll down to the section ''Restricted special pages'', you should see an entry ''Manage Group Permissions''. Click it to enter the Manage Group Permissions special page. Here, you'll find just an empty box and a "Go" button. Fill in the name of the group you want to create/manage/delete, and click "Go". You'll find yourself in a long page with group permissions, each of which can be "true", "false" or "inherit". Setting a permission to "true" or "false" enables or disables the permission for this group, while leaving it on "inherit" means the group gets the default permission that MediaWiki assigns every group - just think of the default rights of the default group "users" Furthermore: * If the group pre-exists, you'll find above the list a comment box and a "Delete group" button, where you can remove the group, while leaving the comment in the ''GroupPermissionsLog.log'' log file. * Furthermore, if the group pre-exists, the permissions list ends with a comment box and a "Change group permissions" button. Clicking that button will change the group permissions to the set designated in the permissions list. The changes, along with all other group permissions, can be found in the ''/etc/mediawiki/config'' directory in file ''GroupPermissons.php''. Clicking the button will also have resulted in a backup of the ''GroupPermissons.php'' file in that same directory, but named ''GroupPermissons.<timestamp>.php'', e.g. ''GroupPermissions.21012009171713.php''. * If the group name is "new", no "Delete group" button is shown, but the permissions list ends with a comment box and an "Add group" button, which will create the group with the designated name, while leaving the comment in the ''GroupPermissionsLog.log'' log file. Again, the comment is logged, and a backup of the ''GroupPermissons.php'' file is made. 466e41eb69e3c47b6abc80a1582349e787a3ce31 0 1466 2622 2568 2010-09-07T11:21:46Z Saruman! 2 /* MySQL commands */ added commas wikitext text/x-wiki == MySQL installation == As with any package to be installed: use aptitude, update your APT, then make sure all your (other) software is up-to-date. Then find package ''mysql-server'' - under Debian 5.0 "Lenny" it'll be version 5.0.51a-something. Installing it will also automatically install some dependent packages, like mysql-common, mysql-client etcetera. So after downloading some 40MiB of files, MySQL is installed. The installation script under Debian Lenny asks you for a password for the MySQL root user. Think up a strong password for the MySQL root user; something like ''waYacUbaT2uW''. DON'T use this example password, [http://www.pctools.com/guides/password/ generate your own one!]. DO NOT use the password of the Linux ''root'' user. Should you consult [http://dev.mysql.com/doc/refman/5.0/en/unix-post-installation.html the official MySQL documentation], you might see mention of the ''mysql_install_db'' script - do not worry about that, since Debian has run it for you when it was setting up the database. The standard user accounts that have been created by the installation script are: * 'root'@'localhost' * 'root'@'<hostname>' * 'root'@'127.0.0.1' All three root accounts are secured with the same password, the one you specified when installing the package ''mysql-server''. ---- '''NOTE for Debian 4.0 "Etch"''' When you install MySQL under Etch, there are two root accounts with empty passwords, and two anonymous accounts. NOT safe! You'll want to rectify this in order to secure your MySQL server. Please take the following steps. Start the MySQL client from the command line: mysql -u root Then, from the mysql client prompt, set the password for the MySQL root users. They can be treated as two different accounts, but we don't recommend that. We thus give both accounts the same password: mysql> SET PASSWORD FOR 'root'@'localhost' = PASSWORD('waYacUbaT2uW'); mysql> SET PASSWORD FOR 'root'@'<hostname>' = PASSWORD('waYacUbaT2uW'); Furthermore, there are two anonymous accounts created. These also have no password, and get full permission on the ''test'' database, as well as on any database who's name begins with ''test_''. These accounts can be fitted with a password (like we did for root - just use two quotes with nothing in between them, instead of two quotes with ''root'' in between), or they can be removed - which we recommend. The (single) command for this is: <pre>mysql> DROP USER '';</pre> '''End of NOTE''' ---- To verify the installation you might want to take some of the following steps: * run ''mysqlshow -u root -p'', and see if that command outputs at least two databases (''information_schema'' and ''mysql''); * check out the settings of your MySQL server by running ''mysqladmin -u root -p variables'' (piping the output to ''less'' or a file, if necessary); * have a peek in ''/var/lib/mysql''; the database data files should be there; * check ''/var/log'' for two logfiles ''mysql.err'' and ''mysql.log''. ==Moving the MySQL databases== By default the location of your Debian MySQL databases is ''/var/lib/mysql/<database>''. However, sometimes you wish your databases to be in a different location. E.g. ''/data/mysql'', where ''/data'' is a mounted dedicated RAID array. Or perhaps even ''/data/mysql'' is its own array. Whatever the reason, to move ''all'' MySQL databases from ''/var/lib/mysql'' to another location, you can follow these steps: * Create the new directory, e.g. ''/data/mysql'' * Make this directory owned by user/group ''mysql'' cd /data mkdir mysql chown mysql:mysql mysql * Shut down the database server with one of the following commands: mysqladmin -u root -p shutdown invoke-rc.d mysql stop * Make a backup copy of ''/etc/mysql/my.cnf'', then edit this file. Find the section ''[mysqld]'' and change the line ''datadir = /var/lib/mysql'' to datadir = /data/mysql * As root, move (or better yet: copy) ''all'' of the content of ''/var/lib/mysql'' over to ''/data/mysql''. Make sure you don't accidentally change the ownership or permissions of the files and folders in the ''/var/lib/mysql'' folder. We expect each and every file and folder to be owned by ''mysql:mysql''. Copy command would be (as root): cp -p -r /var/lib/mysql/* /data/mysql * Check and doublecheck your ''my.cnf'' settings and your database file owners, attributes and size. After the next step, there ''may'' be no way back! * Start up your database server: invoke-rc.d mysql start * Check the working of your MySQL server: ** issue the following command to get status information (to see if MySQL is running after your start command): invoke-rc.d mysql status ** look under ''/var/log'' for the default MySQL log files ''mysql.log'' and ''mysql.err'' ** check your SysLog (standard: ''/var/log/syslog'') for MySQL error messages, since the default Debian configuration is to log MySQL errors there, rather than in the previously mentioned MySQL logfiles. == MySQL commands == The following are examples of the most common MySQL commands <pre><nowiki> SHOW DATABASES; USE <database>; SHOW TABLES; DESCRIBE <table>; SELECT <col1>,<col2>...<col_i> FROM <table> WHERE <column> = '<value>'; INSERT INTO <table> (<col1>,<col2>...<col_i>) VALUES ('<val1>','<val2>'...'<val_i>'); UPDATE <table> set <col1> = '<value1>' WHERE <column> = '<value>'; DELETE FROM <table> WHERE <column> = '<value>'; </nowiki></pre> Ofcourse there are more useful commands, see the MySQL website. 2ef0f5ffb990f916560b40cd94e278163dad910c 0 1434 2623 2470 2010-09-07T15:39:35Z Saruman! 2 /* Other interesting tricks */ added pw resets wikitext text/x-wiki ==Installation of MediaWiki== Here we have the [[Basic MediaWiki Installation|basic installation]] of [http://www.mediawiki.org/ MediaWiki] outlined for you. The default installation will create your wiki in subdirectory ''/mediawiki''. Should you wish to have another name, e.g. ''<nowiki>http://www.yourserver.com/wiki</nowiki>'', then you must make [[Change MediaWiki subpath|two changes]]. ==Extra configuration== After installation of MediaWiki, your Wiki is available on ''every'' Virtual Host you run - unless you follow the instructions to [[place MediaWiki inside a Virtual Host]]. An extra feature we added was support for iFrames by means of a little PHP script that we googled; the extension is called [[The websiteFrame PHP extension| websiteFrame.php]]. Furthermore, we [[wiki footer change |changed the Creative Commons picture]] in the footer from a remote one to a local one. For performance, the following tricks can be used (which we found on [http://mituzas.lt/2007/01/26/mediawiki-performance-tuning this site]): * <pre>apt-get install php-apc</pre> to install a PHP accelerator; * add ''$wgMainCacheType = CACHE_ACCEL;'' (instead of ''CACHE_NONE'') into ''LocalSettings.php'' to enable that installed APC PHP accelerator; * add ''$wgDisableCounters = true;'' into ''LocalSettings.php'' to disable the page counters. On the example site referenced, the cache reduced rendering of an (almost empty) main page from 217ms to 50ms; disabling the page view counter took off another 10ms. Should you wish to customize the look of your MediaWiki wiki, then you must [[MediaWiki skinning|edit the MediaWiki skins]]. ==Extensions== One of the nice things about using something as popular as MediaWiki is the availability of a great number of [http://www.mediawiki.org/wiki/Manual:Extensions extensions]. One of the first things to do, therefor, is to [[mediawiki-extensions under Debian| install the default Debian Mediawiki Extensions package]]. For user management, we added the extensions [[MediaWikiExtension_Password_Reset | Password Reset]] and [[MediaWiki_Extension_-_GroupPermissionsManager | Group Permissions Manager]]. A feature we needed to gain experience for another project was the [http://semantic-mediawiki.org/wiki/Semantic_MediaWiki Semantic MediaWiki (SMW)] extension; it also has a pretty [[Semantic MediaWiki under Debian | simple installation]]. ==Multiple Wiki's on a single server== Some people want to run multiple Wiki instances on one single server - especially so if that server runs multiple websites (the forementioned [[place MediaWiki inside a Virtual Host|Virtual Hosts]]). The answer to that is to [[Create a Wikifarm | create a Wikifarm]].<br> Note that we've set up a [http://www.mediawikifarm.nl/wiki/index.php/Main_Page separate site] for this problem - you're welcome there with any questions you might have on wikifarms on Debian. ==User Rights management== The MediaWiki documentation quite clearly documents [http://www.mediawiki.org/wiki/Manual:$wgGroupPermissions how to manage user rights], but here is a very quick recap: The following user rights are granted implicitly to non-logged-in users: // Implicit group for all visitors $wgGroupPermissions['*' ]['createaccount'] = true; // 1.5.0 $wgGroupPermissions['*' ]['read'] = true; // 1.5.0 $wgGroupPermissions['*' ]['edit'] = true; // 1.5.0 $wgGroupPermissions['*' ]['createpage'] = true; // 1.6.0 $wgGroupPermissions['*' ]['createtalk'] = true; // 1.6.0 So if you want to limit the rights of anonymous users, paste these lines into ''LocalSettings.php'' and change to false those rights that you want to take away. e.g. if you do not want anonymous users to edit pages, set the 'edit' permission to false. Setting 'read' to false requires users to log in before they can read your wiki (but they can still see the sidebar!) The following rights are implicitly granted to all logged-in users. // Implicit group for all logged-in accounts $wgGroupPermissions['user' ]['move'] = true; // 1.5.0 $wgGroupPermissions['user' ]['read'] = true; // 1.5.0 $wgGroupPermissions['user' ]['edit'] = true; // 1.5.0 $wgGroupPermissions['user' ]['createpage'] = true; // 1.6.0 $wgGroupPermissions['user' ]['createtalk'] = true; // 1.6.0 $wgGroupPermissions['user' ]['upload'] = true; // 1.5.0 $wgGroupPermissions['user' ]['reupload'] = true; // 1.6.0 $wgGroupPermissions['user' ]['reupload-shared'] = true; // 1.6.0 $wgGroupPermissions['user' ]['minoredit'] = true; // 1.6.0 $wgGroupPermissions['user' ]['purge'] = true; // 1.10.0 '''NOTE:''' you '''cannot''' let normal users keep a right like 'edit' and take it away for a special group that you create, like 'students'. You MUST grant the group 'user' the ''fewest'' rights that anyone should have, grant extra rights to other groups, and place the right users in these other groups. Examples: $wgGroupPermissions['student' ]['edit'] = false; // WILL NOT WORK The above will NOT "give everyone edit rights except for students". $wgGroupPermissions['*' ]['edit'] = false; // $wgGroupPermissions['user' ]['edit'] = false; // explicitly take away edit from all logged-in users $wgGroupPermissions['staff' ]['edit'] = true; // then give back edit to everyone except standard $wgGroupPermissions['visitingstaff' ]['edit'] = true; // users This WILL work: the edit right is taken away from everyone, including students, untill that right is explicitly restored. Just restore it to the necessary groups, taking care not to restore it to 'students'. So if you want to grant everyone 'edit' except for a particular account - sorry, don't know how that'd work. ==Other interesting tricks== * [[Wiki news items|Creating news items in a semantic wiki]] * fixing access to a wiki when the sysop forgot his password (method 1, CLI access needed):<br>change directory: ''cd /path/to/mediawiki/maintenance''<br>run the following maintenance script: ''php changePassword.php --user="WikiSysop" --password="TheNewPassword"'' * fixing access to a wiki when the sysop forgot his password (method 2, MySQL access needed):<br>enter the MySQL client using an account with sufficient rights to alter the database of your wiki, then run these MySQL commands on the right database:<br>''UPDATE user SET user_password = MD5(CONCAT(user_id, '-', MD5('TheNewPassword'))) WHERE user_id = 1;'' 75e38cb630d6378e000979c324d84d3439262a1b 0 1615 2630 2010-10-04T19:41:22Z Saruman! 2 Pagina aangemaakt wikitext text/x-wiki ==Request== Please add the following new comparators: “less than” and “greater than” ==Proposal== A] Redefine comparators < and > to fit their mathematical meaning: less than and greater than B] Add a new notation for the original comparators “less than or equal” and “greater than or equal”. The notation itself could either be the actual characters (Unicode 2264/Extended ASCII 243 ≤ and Unicode 2265/Extended ASCII 242 ≥ ) or their two-characterASCII approximations (<= and >=) or something else. People with knowledge of code pages and MW parsers may say something intelligent about this C] SMW might need a parameter for backward compatibility with the original < and > comparators: $smwComparatorOldBehaviour. Reason: if one already has a wiki and it uses < and >, the new style alters the behaviour of existing queries with < or >. Admins of these wikis could set $smwComparatorOldBehaviour=true. This would have the effect of disabling the new “greater than” and “less than” comparators, and the parser would treat both < and ≤ the same (“greater than or equal”), meaning the wiki could start using ≤ explicitly, eventually switching over to the “new” behaviour once all existing queries are corrected. After setting $smwComparatorOldBehaviour=false, SMW would start parsing < as “less than” and ≤ as “less than or equal”. It can also be argued that the parameter should be named $smwComparatorNewBehaviour, or $smwUseGreaterThanAndLessThanComparators, etc. I propose the $smwComparatorOldBehaviour name, so that we can use it while we need, and in the future (e.g. in the year 2099) can declare the the parameter deprecated, when we believe that no wiki on earth runs in the counter-intuitive Comparator Old Behaviour mode. D] The backward compatibility parameter should get a default value. It can be argued that the default setting for $smwComparatorOldBehaviour should be false, so that from now on every new wiki is always in new behaviour while we still can accommodate admins of existing wikis (but there's an increased risk of incorrect queries when admins of existing wikis fail to set/correct the parameter); true, so that correct querying for existing wikis is ensured (but there's a great risk of new wiki's not switching to the new behaviour) true for now, and false in a later version of SMW, to have people get used to the idea while not forcing anything. I personally vote for the first option, with a clear warning in the release notes. Background: As described in the Semantic MediaWiki online documentation, the SMW comparators are: > and <: greater than/less than or equal !: unequal ~: «like» comparison for strings (disabled by default) Ths does not readily allow for disjunct selects. Example: suppose property “Foo” is of type number. Ideally, you would like to be able to select (with “mathematical” comparators instead of SMW comparators): a) [[Foo::< 10]] (less than 10) b) [[Foo::>=10]] (10 or greater) However, since the first comparator does not exist, a strict disjunct selection under SMW looks like this c) [[Foo::< 10]][[Foo::!10]] (less than 10) d) [[Foo::>10]] (10 or greater) Technically this works, but the notation is counter-intuitive. Furthermore, the fact that > is “greater than or equal” and not simply “greater than” can lead to unpleasant situations. Consider a property “maturity” with allowed values 1, 2, 3, 4, 5, and 9. When selection all values in the range 1-5, you must use [[Maturity::<9]][[Maturity::!9]] for “everything below 9”, instead of something like [[Maturity::<8]], since 8 is (currently) not an allowed value; the notation inside a query would yield the famous yellow-exclamation-triangle. 2c4f91928d4b87b96cd77956883be79c9217c10d 2631 2630 2010-10-04T19:46:13Z Saruman! 2 layout update wikitext text/x-wiki ==Request== Please add the following new comparators: “less than” and “greater than” ==Proposal== A] Redefine comparators < and > to fit their mathematical meaning: less than and greater than<br> B] Add a new notation for the original comparators “less than or equal” and “greater than or equal”. The notation itself could either be the actual characters (Unicode 2264/Extended ASCII 243 ≤ and Unicode 2265/Extended ASCII 242 ≥ ) or their two-characterASCII approximations (<= and >=) or something else. People with knowledge of code pages and MW parsers may say something intelligent about this<br> C] SMW might need a parameter for backward compatibility with the original < and > comparators: $smwComparatorOldBehaviour. Reason: if one already has a wiki and it uses < and >, the new style alters the behaviour of existing queries with < or >. Admins of these wikis could set $smwComparatorOldBehaviour=true. This would have the effect of disabling the new “greater than” and “less than” comparators, and the parser would treat both < and ≤ the same (“greater than or equal”), meaning the wiki could start using ≤ explicitly, eventually switching over to the “new” behaviour once all existing queries are corrected. After setting $smwComparatorOldBehaviour=false, SMW would start parsing < as “less than” and ≤ as “less than or equal”. It can also be argued that the parameter should be named $smwComparatorNewBehaviour, or $smwUseGreaterThanAndLessThanComparators, etc. I propose the $smwComparatorOldBehaviour name, so that we can use it while we need, and in the future (e.g. in the year 2099) can declare the the parameter deprecated, when we believe that no wiki on earth runs in the counter-intuitive Comparator Old Behaviour mode.<br> D] The backward compatibility parameter should get a default value. It can be argued that the default setting for $smwComparatorOldBehaviour should be * false, so that from now on every new wiki is always in new behaviour while we still can accommodate admins of existing wikis (but there's an increased risk of incorrect queries when admins of existing wikis fail to set/correct the parameter); * true, so that correct querying for existing wikis is ensured (but there's a great risk of new wiki's not switching to the new behaviour) * true for now, and false in a later version of SMW, to have people get used to the idea while not forcing anything. I personally vote for the first option, with a clear warning in the release notes. Background: As described in the Semantic MediaWiki online documentation, the SMW comparators are: * > and <: greater than/less than or equal * !: unequal * ~: «like» comparison for strings (disabled by default) This does not readily allow for disjunct selects. Example: suppose property “Foo” is of type number. Ideally, you would like to be able to select (with “mathematical” comparators instead of SMW comparators):<br> a) [[Foo::< 10]] (less than 10) b) [[Foo::>=10]] (10 or greater) However, since the first comparator does not exist, a strict disjunct selection under SMW looks like this c) [[Foo::< 10]][[Foo::!10]] (less than 10) d) [[Foo::>10]] (10 or greater) Technically this works, but the notation is counter-intuitive. Furthermore, the fact that > is “greater than or equal” and not simply “greater than” can lead to unpleasant situations. Consider a property “maturity” with allowed values 1, 2, 3, 4, 5, and 9. When selection all values in the range 1-5, you must use [[Maturity::<9]][[Maturity::!9]] for “everything below 9”, instead of something like [[Maturity::<8]], since 8 is (currently) not an allowed value; the notation inside a query would yield the famous yellow-exclamation-triangle. Entered in Bugzilla under [https://bugzilla.wikimedia.org/show_bug.cgi?id=25418 ID 25418] 1a5c8ab93770ab178aa73d319e80ce2154a89eb4 2632 2631 2010-10-04T19:49:28Z Saruman! 2 more layout updates wikitext text/x-wiki ==Request== Please add the following new comparators: “less than” and “greater than” ==Proposal== '''A]''' Redefine comparators < and > to fit their mathematical meaning: less than and greater than<br> '''B]''' Add a new notation for the original comparators “less than or equal” and “greater than or equal”. The notation itself could either be the actual characters (Unicode 2264/Extended ASCII 243 ≤ and Unicode 2265/Extended ASCII 242 ≥ ) or their two-characterASCII approximations (<= and >=) or something else. People with knowledge of code pages and MW parsers may say something intelligent about this<br> '''C]''' SMW might need a parameter for backward compatibility with the original < and > comparators: $smwComparatorOldBehaviour. Reason: if one already has a wiki and it uses < and >, the new style alters the behaviour of existing queries with < or >. Admins of these wikis could set $smwComparatorOldBehaviour=true. This would have the effect of disabling the new “greater than” and “less than” comparators, and the parser would treat both < and ≤ the same (“greater than or equal”), meaning the wiki could start using ≤ explicitly, eventually switching over to the “new” behaviour once all existing queries are corrected. After setting $smwComparatorOldBehaviour=false, SMW would start parsing < as “less than” and ≤ as “less than or equal”. It can also be argued that the parameter should be named $smwComparatorNewBehaviour, or $smwUseGreaterThanAndLessThanComparators, etc. I propose the $smwComparatorOldBehaviour name, so that we can use it while we need, and in the future (e.g. in the year 2099) can declare the the parameter deprecated, when we believe that no wiki on earth runs in the counter-intuitive Comparator Old Behaviour mode.<br> '''D]''' The backward compatibility parameter should get a default value. It can be argued that the default setting for $smwComparatorOldBehaviour should be * false, so that from now on every new wiki is always in new behaviour while we still can accommodate admins of existing wikis (but there's an increased risk of incorrect queries when admins of existing wikis fail to set/correct the parameter); * true, so that correct querying for existing wikis is ensured (but there's a great risk of new wiki's not switching to the new behaviour) * true for now, and false in a later version of SMW, to have people get used to the idea while not forcing anything. I personally vote for the first option, with a clear warning in the release notes. ==Background== As described in the Semantic MediaWiki online documentation, the SMW comparators are: * > and <: greater than/less than or equal * !: unequal * ~: «like» comparison for strings (disabled by default) This does not readily allow for disjunct selects. Example: suppose property “Foo” is of type number. Ideally, you would like to be able to select (with “mathematical” comparators instead of SMW comparators):<br> '''a)''' <nowiki>[[Foo::< 10]]</nowiki> (less than 10)<br> '''b)''' <nowiki>[[Foo::>=10]]</nowiki> (10 or greater)<br> However, since the first comparator does not exist, a strict disjunct selection under SMW looks like this '''c)''' <nowiki>[[Foo::< 10]][[Foo::!10]]</nowiki> (less than 10)<br> '''d)''' <nowiki>[[Foo::>10]]</nowiki> (10 or greater)<br> Technically this works, but the notation is counter-intuitive. Furthermore, the fact that > is “greater than or equal” and not simply “greater than” can lead to unpleasant situations. Consider a property “maturity” with allowed values 1, 2, 3, 4, 5, and 9. When selection all values in the range 1-5, you must use <nowiki>[[Maturity::<9]][[Maturity::!9]]</nowiki> for “everything below 9”, instead of something like <nowiki>[[Maturity::<8]]</nowiki>, since 8 is (currently) not an allowed value; the notation inside a query would yield the famous yellow-exclamation-triangle. Entered in Bugzilla under [https://bugzilla.wikimedia.org/show_bug.cgi?id=25418 ID 25418] 5694f31fe5fdf0c6ad00adb0488d7b060d9ec5fa 2633 2632 2010-10-04T19:53:06Z Saruman! 2 yet more layout wikitext text/x-wiki ==Request== Please add the following new comparators: “less than” and “greater than” ==Proposal== '''A]''' Redefine comparators < and > to fit their mathematical meaning: less than and greater than<br> '''B]''' Add a new notation for the original comparators “less than or equal” and “greater than or equal”. The notation itself could either be the actual characters (Unicode 2264/Extended ASCII 243 ≤ and Unicode 2265/Extended ASCII 242 ≥ ) or their two-characterASCII approximations (<= and >=) or something else. People with knowledge of code pages and MW parsers may say something intelligent about this<br> '''C]''' SMW might need a parameter for backward compatibility with the original < and > comparators: ''$smwComparatorOldBehaviour''. Reason: if one already has a wiki and it uses < and >, the new style alters the behaviour of existing queries with < or >. Admins of these wikis could set ''$smwComparatorOldBehaviour=true''. This would have the effect of disabling the new “greater than” and “less than” comparators, and the parser would treat both < and ≤ the same (“greater than or equal”), meaning the wiki could start using ≤ explicitly, eventually switching over to the “new” behaviour once all existing queries are corrected. After setting ''$smwComparatorOldBehaviour=false'', SMW would start parsing < as “less than” and ≤ as “less than or equal”. It can also be argued that the parameter should be named ''$smwComparatorNewBehaviour'', or ''$smwUseGreaterThanAndLessThanComparators'', etc. I propose the ''$smwComparatorOldBehaviour'' name, so that we can use it while we need, and in the future (e.g. in the year 2099) can declare the the parameter deprecated, when we believe that no wiki on earth runs in the counter-intuitive Comparator Old Behaviour mode.<br> '''D]''' The backward compatibility parameter should get a default value. It can be argued that the default setting for ''$smwComparatorOldBehaviour'' should be * ''false'', so that from now on every new wiki is always in new behaviour while we still can accommodate admins of existing wikis (but there's an increased risk of incorrect queries when admins of existing wikis fail to set/correct the parameter); * ''true'', so that correct querying for existing wikis is ensured (but there's a great risk of new wiki's not switching to the new behaviour) * ''true'' for now, and ''false'' in a later version of SMW, to have people get used to the idea while not forcing anything. I personally vote for the first option, with a clear warning in the release notes. ==Background== As described in the Semantic MediaWiki online [http://semantic-mediawiki.org/wiki/Help:Selecting_pages#Greater_than_or_equal.2C_less_than_or_equal documentation], the SMW comparators are: * > and <: greater than/less than or equal * !: unequal * ~: «like» comparison for strings (disabled by default) This does not readily allow for disjunct selects. Example: suppose property ''Foo'' is of type number. Ideally, you would like to be able to select (with “mathematical” comparators instead of SMW comparators):<br> '''a)''' ''<nowiki>[[Foo::< 10]]</nowiki>'' (less than 10)<br> '''b)''' ''<nowiki>[[Foo::>=10]]</nowiki>'' (10 or greater)<br> However, since the first comparator does not exist, a strict disjunct selection under SMW looks like this '''c)''' ''<nowiki>[[Foo::< 10]][[Foo::!10]]</nowiki>'' (less than 10)<br> '''d)''' ''<nowiki>[[Foo::>10]]</nowiki>'' (10 or greater)<br> Technically this works, but the notation is counter-intuitive. Furthermore, the fact that > is “greater than or equal” and not simply “greater than” can lead to unpleasant situations. Consider a property ''maturity'' with allowed values 1, 2, 3, 4, 5, and 9. When selection all values in the range 1-5, you must use ''<nowiki>[[Maturity::<9]][[Maturity::!9]]</nowiki>'' for “everything below 9”, instead of something like ''<nowiki>[[Maturity::<8]]</nowiki>'', since 8 is (currently) not an allowed value; the notation inside a query would yield the famous yellow-exclamation-triangle. Entered in Bugzilla under [https://bugzilla.wikimedia.org/show_bug.cgi?id=25418 ID 25418] 534acdad7c35a7483bd8eec1a6891e85fcd90d5e 2634 2633 2010-10-04T19:56:36Z Saruman! 2 ... and yet more wikitext text/x-wiki ==Request== Please add the following new comparators: "less than" and "greater than" ==Proposal== &nbsp;&nbsp;&nbsp;'''A]''' Redefine comparators < and > to fit their mathematical meaning: "less than" and "greater than"<br> &nbsp;&nbsp;&nbsp;'''B]''' Add a new notation for the original comparators “less than or equal” and “greater than or equal”. The notation itself could either be the actual characters (Unicode 2264/Extended ASCII 243 ≤ and Unicode 2265/Extended ASCII 242 ≥ ) or their two-characterASCII approximations (<= and >=) or something else. People with knowledge of code pages and MW parsers may say something intelligent about this<br> &nbsp;&nbsp;&nbsp;'''C]''' SMW might need a parameter for backward compatibility with the original < and > comparators: ''$smwComparatorOldBehaviour''. Reason: if one already has a wiki and it uses < and >, the new style alters the behaviour of existing queries with < or >. Admins of these wikis could set ''$smwComparatorOldBehaviour=true''. This would have the effect of disabling the new “greater than” and “less than” comparators, and the parser would treat both < and ≤ the same (“greater than or equal”), meaning the wiki could start using ≤ explicitly, eventually switching over to the “new” behaviour once all existing queries are corrected. After setting ''$smwComparatorOldBehaviour=false'', SMW would start parsing < as “less than” and ≤ as “less than or equal”. It can also be argued that the parameter should be named ''$smwComparatorNewBehaviour'', or ''$smwUseGreaterThanAndLessThanComparators'', etc. I propose the ''$smwComparatorOldBehaviour'' name, so that we can use it while we need, and in the future (e.g. in the year 2099) can declare the the parameter deprecated, when we believe that no wiki on earth runs in the counter-intuitive Comparator Old Behaviour mode.<br> &nbsp;&nbsp;&nbsp;'''D]''' The backward compatibility parameter should get a default value. It can be argued that the default setting for ''$smwComparatorOldBehaviour'' should be * ''false'', so that from now on every new wiki is always in new behaviour while we still can accommodate admins of existing wikis (but there's an increased risk of incorrect queries when admins of existing wikis fail to set/correct the parameter); * ''true'', so that correct querying for existing wikis is ensured (but there's a great risk of new wiki's not switching to the new behaviour) * ''true'' for now, and ''false'' in a later version of SMW, to have people get used to the idea while not forcing anything. I personally vote for the first option, with a clear warning in the release notes. ==Background== As described in the Semantic MediaWiki online [http://semantic-mediawiki.org/wiki/Help:Selecting_pages#Greater_than_or_equal.2C_less_than_or_equal documentation], the SMW comparators are: * > and <: greater than/less than or equal * !: unequal * ~: «like» comparison for strings (disabled by default) This does not readily allow for disjunct selects. Example: suppose property ''Foo'' is of type number. Ideally, you would like to be able to select (with “mathematical” comparators instead of SMW comparators):<br> &nbsp;&nbsp;&nbsp;'''a)''' ''<nowiki>[[Foo::< 10]]</nowiki>'' (less than 10)<br> &nbsp;&nbsp;&nbsp;'''b)''' ''<nowiki>[[Foo::>=10]]</nowiki>'' (10 or greater)<br> However, since the first comparator does not exist, a strict disjunct selection under SMW looks like this<br> &nbsp;&nbsp;&nbsp;'''c)''' ''<nowiki>[[Foo::< 10]][[Foo::!10]]</nowiki>'' (less than 10)<br> &nbsp;&nbsp;&nbsp;'''d)''' ''<nowiki>[[Foo::>10]]</nowiki>'' (10 or greater)<br> Technically this works, but the notation is counter-intuitive. Furthermore, the fact that > is “greater than or equal” and not simply “greater than” can lead to unpleasant situations. Consider a property ''maturity'' with allowed values 1, 2, 3, 4, 5, and 9. When selection all values in the range 1-5, you must use ''<nowiki>[[Maturity::<9]][[Maturity::!9]]</nowiki>'' for “everything below 9”, instead of something like ''<nowiki>[[Maturity::<8]]</nowiki>'', since 8 is (currently) not an allowed value; the notation inside a query would yield the famous yellow-exclamation-triangle. Entered in Bugzilla under [https://bugzilla.wikimedia.org/show_bug.cgi?id=25418 ID 25418] 4b97f3fe56809b21aa169e5e408b50e4b1abc683 0 1507 2643 2473 2010-10-15T13:25:06Z 82.161.20.132 0 /* Configuring WebDAV and LDAP for your SSL-enabled Virtual Host */ wikitext text/x-wiki ==Apache2== ===Installation of Apache2=== Installation of Apache2 is quite simple: apt-get install apache2 This brings a slew of packages, a.o. ''apache2-mpm-worker'', ''apache2-utils'', ''libapr1'' et cetera. When you want a different worker (e.g. , you should use ''aptitude'' to select that different worker (prefork etc.). ===Configuration of Apache2=== Once Apache2 is in place, you might want to [[Enabling SSL for Apache2 | enable SSL]] for it. And if you want to keep track of any visitor to your website(s), you might want to install [[Apache2 and Visitor|Visitor]]. Furthermore, you have to realise that mail sent by your webserver, or any PHP program running under it (e.g. MediaWiki) will have the envelope sender address of www-data@<your.maildomain>. To make sure that your maildomain is actually a real mail domain (necessary for reverse lookup, which is something that real mail servers do), you have to take care to put the right mail domain in ''/etc/mailname'' (e.g. "saruman.biz"). Furthermore, at the top of your Postfix ''main.cf'' you might like to add myorigin = /etc/mailname If you now restart Postfix, outgoing mail from user ''www-data'' will have an envelope sender address of ''www-data@saruman.biz'' ==Installation of PHP5== Installing PHP5 is as easy as sudo apt-get install php5 php5-cli Note that if you had installed Apache2 module ''apache2-mpm-worker'', it will get replaced with ''apache2-mpm-prefork''. Furthermore, note that ''php5-cli'' is only needed if you want to run PHP commands at the prompt - but our guess is that you want it (e.g. to perform maintenance tasks for your [[Mediawiki_Installation|MediaWiki wikiserver]]. ==Adding WebDAV to your Apache2== ===Thoughts about WebDAV and your configuration=== Out of the box, your Debian Apache2 is prepared to start using WebDAV. All you need is to enable two modules: one for WebDAV itself, one for the authentication that you want to use. Since our server mainly uses LDAP, we'll describe WebDAV+LDAP here. Furthermore, because WebDAV allows editing files on your server, security is paramount (well, it always is, of course. What we mean is that it's even '''more''' important now). The Apache project recommends:<br> ''The use of HTTP Basic Authentication is not recommended. You should use at least HTTP Digest Authentication, which is provided by the mod_auth_digest module. Nearly all WebDAV clients support this authentication method. An alternative is Basic Authentication over an SSL enabled connection.''<br> Thus you should not using Basic Authentication (which is pretty simple to set up) unless you run it over SSL - so we do that as well. We choose the Virtual Host that defines our SSL-site, and extend it with WebDAV functionality. If this is not what you want, consider stepping your authentication up to Digest Authentication. ===Configuring WebDAV and LDAP for your SSL-enabled Virtual Host=== First, enable the WebDAV and authnz_ldap modules: a2enmod dav a2enmod dav_fs a2enmod authnz_ldap Do not restart Apache2 just yet, because we haven't configured either the WebDAV site or its authentication! Furthermore, a location for the DAV lock database must be specified in the global section of your Apache2 configuration file using the [http://httpd.apache.org/docs/2.2/mod/mod_dav_fs.html#davlockdb DavLockDB directive]. To this end, create a file under ''/etc/apache2/conf.d'' named ''webdav'' containing this single line: DavLockDB /var/run/apache2/DavLock This will act as the (global) lock database for WebDAV; we don't need to specify it in any other configuration file (like the Virtual Host configuration files). Of course, your server should have a directory ''/var/run/apache2'', and it must be writable for the user ''www-data'' under which Apache2 runs. Next, adapt the virtual host that may employ WebDAV and LDAP authentication. The virtual host file needs a section that enables WebDAV (using the directive ''Dav On''), and some directives on how to authorize users within this section. Suppose we want to enable WebDAV only for subdirectory ''webdav'' within virtual host ''<nowiki>http://www.saruman.biz/</nowiki>''. Then in the correspondig Virtual Host file (something like ''/etc/apache2/sites-available/000-saruman.biz'') we need to include the following section: <Location /webdav> Order Allow,Deny Allow from all Dav On These lines turn on WebDAV for the location ''/webdav''. This of course means that there should ''be'' a directory in your server's filesystem named ''webdav'' and located under the root of this virtual host, e.g. ''/var/www/saruman.biz/webdav'' AuthType Basic AuthBasicProvider ldap AuthzLDAPAuthoritative On This section sets up the authentication as HTTP Basic, with LDAP as the provider, and NOT allowing the authorization phase to fall back to other providers if LDAP cannot provide the required answer. If you want to use "require" statements from some other authorization provider, then you must set ''AuthzLDAPAuthoritative'' to "off". AuthName "Enter your Saruman.biz login" AuthLDAPURL "ldap://myserver.saruman.biz/ou=people,dc=saruman,dc=biz?mail" NONE AuthLDAPBindDN "cn=admin,dc=saruman,dc=biz" AuthLDAPBindPassword "mypassword" The ''AuthName'' directive "sets the name of the authorization realm". The string provided for the AuthName is what will appear in the password dialog provided by most browsers.<br> The ''AuthLDAPURL'' should point to your server, and the word behind the question mark should be the LDAP field that you want to use as login. We use ''mail'' so that we can log in with our mail address.<br> The ''AuthLDAPBindDN'' should be of a user with the right to view the passwords of the users that will be using the WebDAV server, and the ''AuthLDAPBindPassword'' should be that user's password.<br> require valid-user </Location> This last directive means that any user who has authenticated is granted access. Since only LDAP users can authenticate, this is just fine. If you want to autenticate against a ldap group "webdav" use the folowing Order deny,allow Deny from All AuthName "Enter your Saruman.biz login" AuthType Basic AuthBasicProvider ldap AuthzLDAPAuthoritative on AuthLDAPUrl ldap://myserver.saruman.biz/ou=people,dc=saruman,dc=biz?uid AuthLDAPBindDN "cn=admin,dc=saruman,dc=biz" AuthLDAPBindPassword "mypassword" AuthLDAPGroupAttribute memberUid AuthLDAPGroupAttributeIsDN off Require ldap-group cn=webdav,ou=groups,dc=saruman,dc=biz Require ldap-attribute gidNumber=420 Require ldap-attribute gidNumber=420 handles the primary users of group 420, the "webdav" group. Without this condition, primary users would be denied access. For multiple groups, add an additional directive for each. Next up, you need to create folder ''webdav'' under the root of your Virtual Host. Do not forget to make that folder owned by ''www-data:www-data'' and readable/writable only by that user: cd /data/wwwroot/yoursite mkdir webdav chown www-data:www-data webdav chmod 660 webdav Now you can restart Apache2, see if it restarts ok, and then test your new WebDAV folder. ===Testing WebDAV=== To test WebDAV, you can most easily install the ''cadaver'' WebDAV client: apt-get install cadaver After that, you can start cadaver, and have it write a file in your WebDAV environment: localhost:/data/wwwroot/yoursite/webdav# '''cadaver https://www.saruman.biz/webdav''' WARNING: Untrusted server certificate presented for `*.saruman.biz': Issued to: Internet Dept., Saruman.biz, Utrecht, NL Issued by: Saruman.biz, Utrecht, NL Certificate is valid from Tue, 28 Oct 2008 07:34:41 GMT to Mon, 02 Nov 2009 07:34:41 GMT Do you wish to accept the certificate? (y/n) y Authentication required for Enter your Saruman.biz login on server `www.saruman.biz': Username: sixpacjo Password: dav:/webdav/> _ When presented with the cadaver prompt, you can use the following commands: * ''edit <filename>'': this causes cadaver to open an existing file named ''<filename>''; or, failing that, to create a new file. Your default text editor is used. * ''lock <filename>'' or ''unlock <filename>'': set or remove a lock on a WebDAV published file. He who owns the lock can edit the file, others can only read it. * ''discover <filename>'': see the lock status of the file * ''quit'': well that one's easy... Use ''man cadaver'' for the full description. Errors that might occur if you have a problem in your WebDAV setup include: * Lock problems: if you fail to provide a webserver-writable place for the lock file, you will encounter HTTP 500 errors. In ''cadaver'': dav:/webdav/> edit test.html Locking `test.html': failed: 500 Internal Server Error dav:/webdav/> discover test.html Discovering locks on `test.html': no locks found. dav:/webdav/> c8fc5047c9e3999d3fbbe81d25b1e6d21317d594 0 1616 2654 2010-10-29T05:36:14Z Saruman! 2 recreated after spam attacks wikitext text/x-wiki ==OpenSSH Server== This package is essential when you want to be able to (safely) administer your server from another place than the console. To install: simpy use ''sudo aptitude install openssh-server''. This will install the OpenSSH server, plus the OpenSSH client. Since the SSL vulnerbility of may '08, also the ssh-blacklist package is downloaded. After installing, we need to make the following changes to the default settings in file ''/etc/ssh/sshd-config'': * line ''PermitRootLogin yes'' should be set to ''no'', so that user ''root'' CANNOT log in over SSH! ([http://www.debian-administration.org/articles/573 big security gap!]). * add a line ''AllowGroups wheel''; adding this ensures that NOBODY can log in over SSH unless you specifically assigned them to the ''wheel'' group, reducing the attack surface of your SSH user. Should you need more than one group (e.g. you want to add the group "ldapwheel"), then add the groups separated by spaces: ''AllowGroups wheel ldapwheel''. * Change your banner by editing the [[MOTD file]]. Next, make sure the ''wheel'' group exist, and add all users to it that are allowed ssh-access: groupadd -g 117 wheel usermod -a -G wheel jan In the groupadd line, the groupID is explicitly set to 117, but this really is optional. In the usermod line, be sure to use the ''-a'' so that your user gets the ssh-users group added, instead of replacing all supplementary groups with this one ssh-users. If you've added a group that exists in your LDAP server, make sure that those LDAP users are member of that group that you want to give SSH access. This is ofcourse managed from your LDAP management console (be it the commandline ''ldapmodify'' or a graphic tool like [[Filling_an_OpenLDAP_database#Adding_a_user_with_LAM | LDAP Account Manager]] When all this is changed, the service should be restarted with ''sudo /etc/init.d/ssh restart''. One of the nice things of a correctly configured SSH server, is the ability to use [[scp]] to copy files between machines. == Changing RSA keys == Occasionally you'll find the RSA key of one of your machines has changed. This may have a number of reasons, a.o. a reinstall or migration of said machine. In any case, when you try to SSH to the machine you get a message like this: localhost:~# '''ssh insomnia@easton.saruman.biz''' @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @ WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED! @ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ IT IS POSSIBLE THAT SOMEONE IS DOING SOMETHING NASTY! Someone could be eavesdropping on you right now (man-in-the-middle attack)! It is also possible that the RSA host key has just been changed. The fingerprint for the RSA key sent by the remote host is f7:1a:5a:11:ca:20:99:fa:db:1b:b8:75:8e:e5:f1:12. Please contact your system administrator. Add correct host key in /home/sixpacjo/.ssh/known_hosts to get rid of this message. Offending key in /home/sixpacjo/.ssh/known_hosts:4 RSA host key for easton.saruman.biz has changed and you have requested strict checking. Host key verification failed. localhost:~# _ When you get this message it is not possible to connect to the machine mentioned, until you've solved the problem of the RSA key. There are multiple ways to correct the key, but the simplest method seems to be to simply remove the offending key with ''ssh-keygen''. Note that Debian "Lenny" stores the RSA key in ''two'' places: one for the host name, one for the IP number. To prevent annoying messages like this: Warning: the RSA host key for 'easton.saruman.biz' differs from the key for the IP address '192.168.67.5' Offending key for IP in /home/sixpacjo/.ssh/known_hosts:4 you should remove the RSA key for the IP number as well. This you do with the following two commands: localhost:~# '''ssh-keygen -R easton.saruman.biz''' /home/sixpacjo/.ssh/known_hosts updated. Original contents retained as /home/sixpacjo/.ssh/known_hosts.old localhost:~# '''ssh-keygen -R 192.168.67.5''' /home/sixpacjo/.ssh/known_hosts updated. Original contents retained as /home/sixpacjo/.ssh/known_hosts.old localhost:~# _ After deleting the "offending RSA keys" like this, you can SSH to the box in question, and your SSH client will save the (new) RSA key for you in your ''known_hosts'' file. 28fcb503016735a91b0df0392af89a15eb2875f9 2655 2654 2010-10-29T07:04:00Z 95.65.31.161 0 /* OpenSSH Server */ wikitext text/x-wiki Ordering the soft vigora which had been brought in these tabs falling to the telephone, there were two first fellow's to the tower. http://www.audreysauretgillespie.com/viagra-alternatives.html viagra alternatives All purchase killed away. http://www.audreysauretgillespie.com/buy-viagra.html buy viagra It arrived you put presently as both levitra of he through ed. http://www.audreysauretgillespie.com/discount-viagra-europe.html discount viagra europe I will like where him is from to ascend and appraise buy like vardenafil. Through the tadalis he looked medication like the dent lips to get off both error. http://www.audreysauretgillespie.com/buy-online-viagra.html buy online viagra Black discount. == Changing RSA keys == Occasionally you'll find the RSA key of one of your machines has changed. This may have a number of reasons, a.o. a reinstall or migration of said machine. In any case, when you try to SSH to the machine you get a message like this: localhost:~# '''ssh insomnia@easton.saruman.biz''' @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @ WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED! @ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ IT IS POSSIBLE THAT SOMEONE IS DOING SOMETHING NASTY! Someone could be eavesdropping on you right now (man-in-the-middle attack)! It is also possible that the RSA host key has just been changed. The fingerprint for the RSA key sent by the remote host is f7:1a:5a:11:ca:20:99:fa:db:1b:b8:75:8e:e5:f1:12. Please contact your system administrator. Add correct host key in /home/sixpacjo/.ssh/known_hosts to get rid of this message. Offending key in /home/sixpacjo/.ssh/known_hosts:4 RSA host key for easton.saruman.biz has changed and you have requested strict checking. Host key verification failed. localhost:~# _ When you get this message it is not possible to connect to the machine mentioned, until you've solved the problem of the RSA key. There are multiple ways to correct the key, but the simplest method seems to be to simply remove the offending key with ''ssh-keygen''. Note that Debian "Lenny" stores the RSA key in ''two'' places: one for the host name, one for the IP number. To prevent annoying messages like this: Warning: the RSA host key for 'easton.saruman.biz' differs from the key for the IP address '192.168.67.5' Offending key for IP in /home/sixpacjo/.ssh/known_hosts:4 you should remove the RSA key for the IP number as well. This you do with the following two commands: localhost:~# '''ssh-keygen -R easton.saruman.biz''' /home/sixpacjo/.ssh/known_hosts updated. Original contents retained as /home/sixpacjo/.ssh/known_hosts.old localhost:~# '''ssh-keygen -R 192.168.67.5''' /home/sixpacjo/.ssh/known_hosts updated. Original contents retained as /home/sixpacjo/.ssh/known_hosts.old localhost:~# _ After deleting the "offending RSA keys" like this, you can SSH to the box in question, and your SSH client will save the (new) RSA key for you in your ''known_hosts'' file. 3e3531a5c4f82270b493baf687846b2f2766c910 2656 2655 2010-10-29T07:06:32Z Saruman! 2 Reverted edits by [[Special:Contributions/95.65.31.161|95.65.31.161]] ([[User talk:95.65.31.161|Talk]]) to last revision by [[User:Saruman!|Saruman!]] wikitext text/x-wiki ==OpenSSH Server== This package is essential when you want to be able to (safely) administer your server from another place than the console. To install: simpy use ''sudo aptitude install openssh-server''. This will install the OpenSSH server, plus the OpenSSH client. Since the SSL vulnerbility of may '08, also the ssh-blacklist package is downloaded. After installing, we need to make the following changes to the default settings in file ''/etc/ssh/sshd-config'': * line ''PermitRootLogin yes'' should be set to ''no'', so that user ''root'' CANNOT log in over SSH! ([http://www.debian-administration.org/articles/573 big security gap!]). * add a line ''AllowGroups wheel''; adding this ensures that NOBODY can log in over SSH unless you specifically assigned them to the ''wheel'' group, reducing the attack surface of your SSH user. Should you need more than one group (e.g. you want to add the group "ldapwheel"), then add the groups separated by spaces: ''AllowGroups wheel ldapwheel''. * Change your banner by editing the [[MOTD file]]. Next, make sure the ''wheel'' group exist, and add all users to it that are allowed ssh-access: groupadd -g 117 wheel usermod -a -G wheel jan In the groupadd line, the groupID is explicitly set to 117, but this really is optional. In the usermod line, be sure to use the ''-a'' so that your user gets the ssh-users group added, instead of replacing all supplementary groups with this one ssh-users. If you've added a group that exists in your LDAP server, make sure that those LDAP users are member of that group that you want to give SSH access. This is ofcourse managed from your LDAP management console (be it the commandline ''ldapmodify'' or a graphic tool like [[Filling_an_OpenLDAP_database#Adding_a_user_with_LAM | LDAP Account Manager]] When all this is changed, the service should be restarted with ''sudo /etc/init.d/ssh restart''. One of the nice things of a correctly configured SSH server, is the ability to use [[scp]] to copy files between machines. == Changing RSA keys == Occasionally you'll find the RSA key of one of your machines has changed. This may have a number of reasons, a.o. a reinstall or migration of said machine. In any case, when you try to SSH to the machine you get a message like this: localhost:~# '''ssh insomnia@easton.saruman.biz''' @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @ WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED! @ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ IT IS POSSIBLE THAT SOMEONE IS DOING SOMETHING NASTY! Someone could be eavesdropping on you right now (man-in-the-middle attack)! It is also possible that the RSA host key has just been changed. The fingerprint for the RSA key sent by the remote host is f7:1a:5a:11:ca:20:99:fa:db:1b:b8:75:8e:e5:f1:12. Please contact your system administrator. Add correct host key in /home/sixpacjo/.ssh/known_hosts to get rid of this message. Offending key in /home/sixpacjo/.ssh/known_hosts:4 RSA host key for easton.saruman.biz has changed and you have requested strict checking. Host key verification failed. localhost:~# _ When you get this message it is not possible to connect to the machine mentioned, until you've solved the problem of the RSA key. There are multiple ways to correct the key, but the simplest method seems to be to simply remove the offending key with ''ssh-keygen''. Note that Debian "Lenny" stores the RSA key in ''two'' places: one for the host name, one for the IP number. To prevent annoying messages like this: Warning: the RSA host key for 'easton.saruman.biz' differs from the key for the IP address '192.168.67.5' Offending key for IP in /home/sixpacjo/.ssh/known_hosts:4 you should remove the RSA key for the IP number as well. This you do with the following two commands: localhost:~# '''ssh-keygen -R easton.saruman.biz''' /home/sixpacjo/.ssh/known_hosts updated. Original contents retained as /home/sixpacjo/.ssh/known_hosts.old localhost:~# '''ssh-keygen -R 192.168.67.5''' /home/sixpacjo/.ssh/known_hosts updated. Original contents retained as /home/sixpacjo/.ssh/known_hosts.old localhost:~# _ After deleting the "offending RSA keys" like this, you can SSH to the box in question, and your SSH client will save the (new) RSA key for you in your ''known_hosts'' file. 28fcb503016735a91b0df0392af89a15eb2875f9 2657 2656 2010-10-30T00:15:03Z 79.142.67.109 0 comment2, http://la-condesa.jp/./node/23348 old women fucking videos, xme, http://isagalaudu.com/node/62140 girl fucked by doberman video, 803745, http://chuckanutartfarm.com/node/85493 wet pussy le wikitext text/x-wiki comment2, http://la-condesa.jp/./node/23348 old women fucking videos, xme, http://isagalaudu.com/node/62140 girl fucked by doberman video, 803745, http://chuckanutartfarm.com/node/85493 wet pussy lesbian video, 3195, http://www.bigbuild.org/node/63871 free video clip anal, 6438, http://dawnbreakersinc.com/?q=node/6578 celebrity free hardcore sex clips, dkju, http://www.danawilson.org/node/87108 miniclip boom volleyball topless password, 8], http://www.hydraulix.com.br/node/24692 nylon fetish sex video, pjllz, http://winnipegapartmentbuildings.com/node/10951 free black bbw movie, kjt, http://iraq.orgstate.net/node/246118 College couples sex videos, 611478, http://dadsanon.com/node/78394 dick movie poster, rblwhg, http://tcphotobyniki.com/node/18003 monster cock video, =-(((, http://teachforhk.org/en/node/83435 free lesbian hentai porn movies, 517116, http://www.encinitasfocus.com/node/76743 Free movies ass, %[[[, http://mytripsy.com/node/590 gay college clips, ldad, http://www.expecttolearn.com/node/31284 gay butt licking movies, >:-[[, http://thecavemanreviews.com/node/1865 Hairy natural video, :-D, http://iklangratiskaltim.info/node/139999 porn websites like porn tube, =PPP, http://www.intlsdoc.com/node/104698 Eat pussy sample movie, %OOO, http://dhruvaloka.com/node/29108 porno tube video, =-]]], http://www.sdfamilyguidanceservices.com/node/77827 Video d sex, %]], http://www.merseysidetaichi.com/node/61436 begonia tuberhybrida hairy, 8(((, http://www.hofstader.com/node/48378 free video clips hairy pussy, =-OOO, http://pelhamrealtyrentals.com/node/63245 free japanese porno movies, wstdub, http://dev.rcsu.org/node/2868 Free mature daily porn videos, 464251, http://h1442719.stratoserver.net/drupal-6.8.000000/node/144400 philippine college sex scandal video, %[, http://rhutchison.eu/node/33755 Smegma gay pics dvd, myoqs, http://mupi.org.mo/en/node/55833 Free carmen cocks video, =O, http://nevermindthenoise.net/node/7053 sexy nude girl video, khsuw, http://epidermolysisbullosaacquisita.org/node/62218 Young teens having sex videos, >:-]], == Changing RSA keys == Occasionally you'll find the RSA key of one of your machines has changed. This may have a number of reasons, a.o. a reinstall or migration of said machine. In any case, when you try to SSH to the machine you get a message like this: localhost:~# '''ssh insomnia@easton.saruman.biz''' @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @ WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED! @ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ IT IS POSSIBLE THAT SOMEONE IS DOING SOMETHING NASTY! Someone could be eavesdropping on you right now (man-in-the-middle attack)! It is also possible that the RSA host key has just been changed. The fingerprint for the RSA key sent by the remote host is f7:1a:5a:11:ca:20:99:fa:db:1b:b8:75:8e:e5:f1:12. Please contact your system administrator. Add correct host key in /home/sixpacjo/.ssh/known_hosts to get rid of this message. Offending key in /home/sixpacjo/.ssh/known_hosts:4 RSA host key for easton.saruman.biz has changed and you have requested strict checking. Host key verification failed. localhost:~# _ When you get this message it is not possible to connect to the machine mentioned, until you've solved the problem of the RSA key. There are multiple ways to correct the key, but the simplest method seems to be to simply remove the offending key with ''ssh-keygen''. Note that Debian "Lenny" stores the RSA key in ''two'' places: one for the host name, one for the IP number. To prevent annoying messages like this: Warning: the RSA host key for 'easton.saruman.biz' differs from the key for the IP address '192.168.67.5' Offending key for IP in /home/sixpacjo/.ssh/known_hosts:4 you should remove the RSA key for the IP number as well. This you do with the following two commands: localhost:~# '''ssh-keygen -R easton.saruman.biz''' /home/sixpacjo/.ssh/known_hosts updated. Original contents retained as /home/sixpacjo/.ssh/known_hosts.old localhost:~# '''ssh-keygen -R 192.168.67.5''' /home/sixpacjo/.ssh/known_hosts updated. Original contents retained as /home/sixpacjo/.ssh/known_hosts.old localhost:~# _ After deleting the "offending RSA keys" like this, you can SSH to the box in question, and your SSH client will save the (new) RSA key for you in your ''known_hosts'' file. 750475298e45568d7ed554f1fdad25c65c4255b2 2658 2657 2010-10-30T09:44:54Z Saruman! 2 Reverted edits by [[Special:Contributions/79.142.67.109|79.142.67.109]] ([[User talk:79.142.67.109|Talk]]) to last revision by [[User:Saruman!|Saruman!]] wikitext text/x-wiki ==OpenSSH Server== This package is essential when you want to be able to (safely) administer your server from another place than the console. To install: simpy use ''sudo aptitude install openssh-server''. This will install the OpenSSH server, plus the OpenSSH client. Since the SSL vulnerbility of may '08, also the ssh-blacklist package is downloaded. After installing, we need to make the following changes to the default settings in file ''/etc/ssh/sshd-config'': * line ''PermitRootLogin yes'' should be set to ''no'', so that user ''root'' CANNOT log in over SSH! ([http://www.debian-administration.org/articles/573 big security gap!]). * add a line ''AllowGroups wheel''; adding this ensures that NOBODY can log in over SSH unless you specifically assigned them to the ''wheel'' group, reducing the attack surface of your SSH user. Should you need more than one group (e.g. you want to add the group "ldapwheel"), then add the groups separated by spaces: ''AllowGroups wheel ldapwheel''. * Change your banner by editing the [[MOTD file]]. Next, make sure the ''wheel'' group exist, and add all users to it that are allowed ssh-access: groupadd -g 117 wheel usermod -a -G wheel jan In the groupadd line, the groupID is explicitly set to 117, but this really is optional. In the usermod line, be sure to use the ''-a'' so that your user gets the ssh-users group added, instead of replacing all supplementary groups with this one ssh-users. If you've added a group that exists in your LDAP server, make sure that those LDAP users are member of that group that you want to give SSH access. This is ofcourse managed from your LDAP management console (be it the commandline ''ldapmodify'' or a graphic tool like [[Filling_an_OpenLDAP_database#Adding_a_user_with_LAM | LDAP Account Manager]] When all this is changed, the service should be restarted with ''sudo /etc/init.d/ssh restart''. One of the nice things of a correctly configured SSH server, is the ability to use [[scp]] to copy files between machines. == Changing RSA keys == Occasionally you'll find the RSA key of one of your machines has changed. This may have a number of reasons, a.o. a reinstall or migration of said machine. In any case, when you try to SSH to the machine you get a message like this: localhost:~# '''ssh insomnia@easton.saruman.biz''' @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @ WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED! @ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ IT IS POSSIBLE THAT SOMEONE IS DOING SOMETHING NASTY! Someone could be eavesdropping on you right now (man-in-the-middle attack)! It is also possible that the RSA host key has just been changed. The fingerprint for the RSA key sent by the remote host is f7:1a:5a:11:ca:20:99:fa:db:1b:b8:75:8e:e5:f1:12. Please contact your system administrator. Add correct host key in /home/sixpacjo/.ssh/known_hosts to get rid of this message. Offending key in /home/sixpacjo/.ssh/known_hosts:4 RSA host key for easton.saruman.biz has changed and you have requested strict checking. Host key verification failed. localhost:~# _ When you get this message it is not possible to connect to the machine mentioned, until you've solved the problem of the RSA key. There are multiple ways to correct the key, but the simplest method seems to be to simply remove the offending key with ''ssh-keygen''. Note that Debian "Lenny" stores the RSA key in ''two'' places: one for the host name, one for the IP number. To prevent annoying messages like this: Warning: the RSA host key for 'easton.saruman.biz' differs from the key for the IP address '192.168.67.5' Offending key for IP in /home/sixpacjo/.ssh/known_hosts:4 you should remove the RSA key for the IP number as well. This you do with the following two commands: localhost:~# '''ssh-keygen -R easton.saruman.biz''' /home/sixpacjo/.ssh/known_hosts updated. Original contents retained as /home/sixpacjo/.ssh/known_hosts.old localhost:~# '''ssh-keygen -R 192.168.67.5''' /home/sixpacjo/.ssh/known_hosts updated. Original contents retained as /home/sixpacjo/.ssh/known_hosts.old localhost:~# _ After deleting the "offending RSA keys" like this, you can SSH to the box in question, and your SSH client will save the (new) RSA key for you in your ''known_hosts'' file. 28fcb503016735a91b0df0392af89a15eb2875f9 2659 2658 2010-11-03T17:04:42Z 94.142.134.56 0 http://trig.com/derlasod/biography#97070 buy ambien without a prescription - buy ambien online no prescription http://trig.com/helaonse/biography#59658 buy cialis - buy generic cialis http://trig.com/ wikitext text/x-wiki http://trig.com/derlasod/biography#97070 buy ambien without a prescription - buy ambien online no prescription http://trig.com/helaonse/biography#59658 buy cialis - buy generic cialis http://trig.com/jelopade/biography#72131 cialis - cialis http://trig.com/kolepares/biography#20263 buy cialis online in usa - buy cialis http://trig.com/lisanero/biography#30537 buy phentermine online - buy phentermine no prescription http://trig.com/veronices/biography#18054 buy tramadol online without a prescription - buy tramadol overnight http://trig.com/olgademos/biography#39680 buy tramadol online - buy tramadol no prescription http://trig.com/liloshera/biography#86099 valium - buy valium overnight http://trig.com/belamones/biography#32506 viagra - buy viagra http://trig.com/valesina/biography#23850 buy xanax online - buy xanax overnight delivery == Changing RSA keys == Occasionally you'll find the RSA key of one of your machines has changed. This may have a number of reasons, a.o. a reinstall or migration of said machine. In any case, when you try to SSH to the machine you get a message like this: localhost:~# '''ssh insomnia@easton.saruman.biz''' @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @ WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED! @ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ IT IS POSSIBLE THAT SOMEONE IS DOING SOMETHING NASTY! Someone could be eavesdropping on you right now (man-in-the-middle attack)! It is also possible that the RSA host key has just been changed. The fingerprint for the RSA key sent by the remote host is f7:1a:5a:11:ca:20:99:fa:db:1b:b8:75:8e:e5:f1:12. Please contact your system administrator. Add correct host key in /home/sixpacjo/.ssh/known_hosts to get rid of this message. Offending key in /home/sixpacjo/.ssh/known_hosts:4 RSA host key for easton.saruman.biz has changed and you have requested strict checking. Host key verification failed. localhost:~# _ When you get this message it is not possible to connect to the machine mentioned, until you've solved the problem of the RSA key. There are multiple ways to correct the key, but the simplest method seems to be to simply remove the offending key with ''ssh-keygen''. Note that Debian "Lenny" stores the RSA key in ''two'' places: one for the host name, one for the IP number. To prevent annoying messages like this: Warning: the RSA host key for 'easton.saruman.biz' differs from the key for the IP address '192.168.67.5' Offending key for IP in /home/sixpacjo/.ssh/known_hosts:4 you should remove the RSA key for the IP number as well. This you do with the following two commands: localhost:~# '''ssh-keygen -R easton.saruman.biz''' /home/sixpacjo/.ssh/known_hosts updated. Original contents retained as /home/sixpacjo/.ssh/known_hosts.old localhost:~# '''ssh-keygen -R 192.168.67.5''' /home/sixpacjo/.ssh/known_hosts updated. Original contents retained as /home/sixpacjo/.ssh/known_hosts.old localhost:~# _ After deleting the "offending RSA keys" like this, you can SSH to the box in question, and your SSH client will save the (new) RSA key for you in your ''known_hosts'' file. 2c69ad23dee1649444c58a6907a87c0ac4a9a3e5 2660 2659 2010-11-03T18:00:36Z 94.142.134.56 0 http://trig.com/derlasod/biography#97070 buy ambien no prescription - buy ambien online without prescription http://trig.com/helaonse/biography#59658 buy cialis online without a prescription - buy cia wikitext text/x-wiki http://trig.com/derlasod/biography#97070 buy ambien without a prescription - buy ambien online no prescription http://trig.com/helaonse/biography#59658 buy cialis - buy generic cialis http://trig.com/jelopade/biography#72131 cialis - cialis http://trig.com/kolepares/biography#20263 buy cialis online in usa - buy cialis http://trig.com/lisanero/biography#30537 buy phentermine online - buy phentermine no prescription http://trig.com/veronices/biography#18054 buy tramadol online without a prescription - buy tramadol overnight http://trig.com/olgademos/biography#39680 buy tramadol online - buy tramadol no prescription http://trig.com/liloshera/biography#86099 valium - buy valium overnight http://trig.com/belamones/biography#32506 viagra - buy viagra http://trig.com/valesina/biography#23850 buy xanax online - buy xanax overnight delivery http://trig.com/derlasod/biography#97070 buy ambien no prescription - buy ambien online without prescription http://trig.com/helaonse/biography#59658 buy cialis online without a prescription - buy cialis professional http://trig.com/jelopade/biography#72131 buy cialis professional - buy generic cialis http://trig.com/kolepares/biography#20263 buy cialis professional - buy cialis 20mg http://trig.com/lisanero/biography#30537 buy phentermine - buy phentermine without prescription http://trig.com/veronices/biography#18054 tramadol - tramadol http://trig.com/olgademos/biography#39680 buy tramadol online overnight - buy tramadol overnight http://trig.com/liloshera/biography#86099 buy valium online no prescription - buy valium overnight http://trig.com/belamones/biography#32506 buy viagra online - buy viagra online cheap http://trig.com/valesina/biography#23850 buy xanax - cheap xanax 3b6800bf524db65589ece14deb46ed455ff94e72 2661 2660 2010-11-03T20:54:52Z Saruman! 2 Reverted edits by [[Special:Contributions/94.142.134.56|94.142.134.56]] ([[User talk:94.142.134.56|Talk]]) to last revision by [[User:Saruman!|Saruman!]] wikitext text/x-wiki ==OpenSSH Server== This package is essential when you want to be able to (safely) administer your server from another place than the console. To install: simpy use ''sudo aptitude install openssh-server''. This will install the OpenSSH server, plus the OpenSSH client. Since the SSL vulnerbility of may '08, also the ssh-blacklist package is downloaded. After installing, we need to make the following changes to the default settings in file ''/etc/ssh/sshd-config'': * line ''PermitRootLogin yes'' should be set to ''no'', so that user ''root'' CANNOT log in over SSH! ([http://www.debian-administration.org/articles/573 big security gap!]). * add a line ''AllowGroups wheel''; adding this ensures that NOBODY can log in over SSH unless you specifically assigned them to the ''wheel'' group, reducing the attack surface of your SSH user. Should you need more than one group (e.g. you want to add the group "ldapwheel"), then add the groups separated by spaces: ''AllowGroups wheel ldapwheel''. * Change your banner by editing the [[MOTD file]]. Next, make sure the ''wheel'' group exist, and add all users to it that are allowed ssh-access: groupadd -g 117 wheel usermod -a -G wheel jan In the groupadd line, the groupID is explicitly set to 117, but this really is optional. In the usermod line, be sure to use the ''-a'' so that your user gets the ssh-users group added, instead of replacing all supplementary groups with this one ssh-users. If you've added a group that exists in your LDAP server, make sure that those LDAP users are member of that group that you want to give SSH access. This is ofcourse managed from your LDAP management console (be it the commandline ''ldapmodify'' or a graphic tool like [[Filling_an_OpenLDAP_database#Adding_a_user_with_LAM | LDAP Account Manager]] When all this is changed, the service should be restarted with ''sudo /etc/init.d/ssh restart''. One of the nice things of a correctly configured SSH server, is the ability to use [[scp]] to copy files between machines. == Changing RSA keys == Occasionally you'll find the RSA key of one of your machines has changed. This may have a number of reasons, a.o. a reinstall or migration of said machine. In any case, when you try to SSH to the machine you get a message like this: localhost:~# '''ssh insomnia@easton.saruman.biz''' @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @ WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED! @ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ IT IS POSSIBLE THAT SOMEONE IS DOING SOMETHING NASTY! Someone could be eavesdropping on you right now (man-in-the-middle attack)! It is also possible that the RSA host key has just been changed. The fingerprint for the RSA key sent by the remote host is f7:1a:5a:11:ca:20:99:fa:db:1b:b8:75:8e:e5:f1:12. Please contact your system administrator. Add correct host key in /home/sixpacjo/.ssh/known_hosts to get rid of this message. Offending key in /home/sixpacjo/.ssh/known_hosts:4 RSA host key for easton.saruman.biz has changed and you have requested strict checking. Host key verification failed. localhost:~# _ When you get this message it is not possible to connect to the machine mentioned, until you've solved the problem of the RSA key. There are multiple ways to correct the key, but the simplest method seems to be to simply remove the offending key with ''ssh-keygen''. Note that Debian "Lenny" stores the RSA key in ''two'' places: one for the host name, one for the IP number. To prevent annoying messages like this: Warning: the RSA host key for 'easton.saruman.biz' differs from the key for the IP address '192.168.67.5' Offending key for IP in /home/sixpacjo/.ssh/known_hosts:4 you should remove the RSA key for the IP number as well. This you do with the following two commands: localhost:~# '''ssh-keygen -R easton.saruman.biz''' /home/sixpacjo/.ssh/known_hosts updated. Original contents retained as /home/sixpacjo/.ssh/known_hosts.old localhost:~# '''ssh-keygen -R 192.168.67.5''' /home/sixpacjo/.ssh/known_hosts updated. Original contents retained as /home/sixpacjo/.ssh/known_hosts.old localhost:~# _ After deleting the "offending RSA keys" like this, you can SSH to the box in question, and your SSH client will save the (new) RSA key for you in your ''known_hosts'' file. 28fcb503016735a91b0df0392af89a15eb2875f9 0 1480 2664 2566 2011-04-05T07:53:38Z Saruman! 2 /* DAHDI */ section moved wikitext text/x-wiki = Asterisk basic configuration principles = In this section we'll have a look at the basic configuration of an Asterisk PBX. Contrary to the TFOT-book, we'll be looking at it from the theory side, and from there go to an example configuration. For this example configuration, we'll start from a server with on the "outside" a POTS line and a SIP account with an Internet provider, and on the "inside" two analogue telephones and a SIP softphone. Our goal is to let the PBX behave as if we don't even have a PBX, but a standard home situation: for an incoming call, all phones ring; and every internal phone can make calls to the outside. = Asterisk channel configuration basics = The first thing to realise is that Asterisk sees each connected telephony device as a "channel". But what is a Channel? To Asterisk, a channel is a connection which brings in a call to the Asterisk PBX. A channel could be a connection to an ordinary telephone handset or an ordinary telephone line, or to a logical call (like an Internet phone call). Asterisk makes no distinction between "FXO" and "FXS" style channels (that is, it doesn't distinguish between telephone lines and telephones). Every call is placed or received on a distinct channel. The second thing to realise, is that every type of device attached to the Asterisk PBX have their own specific configuration files. Correctly setting up each (set of) telephony devices makes them available in our Asterisk PBX as channels. Thus, the device configuration files serve as a kind of abstraction layer, and simplify our final Asterisk configuration by putting "channel-specific" information in separate files. If you've followed the previous Asterisk sections in this Wiki, or followed the first four chapters of the TFOT-book, then you've encountered the following configuration files: * ''zaptel.conf'' - in this file, you can set up the most basic parameters for your Zap-type hardware channels, most notably Digium telephony cards. You're configuring the hardware itself, via its driver. You could think of this file as belonging to the hardware, not Asterisk. If you'd have other software on your machine besides Asterisk that could make use of your telephony hardware, then that'd be influenced as well when you change ''zaptel.conf''. * ''zapata.conf'' (and possibly ''zapata-channels.conf'' if you're on Debian) - this file handles the Asterisk-specific configuration of the hardware telephony channels. It thus "sets up the Zap channels" that Asterisk sees - for incoming and outgoing calls. All parameters that set up the channel are specified here. * ''vpb.conf'' - this file is used to configure [http://www.voicetronix.com/ Voicetronix] cards with Asterisk. If you've a Voicetronix card in use, then you've also installed the Voicetronix drivers. This makes the card(s) useable under Linux. But to have Asterisk use the card(s), you need this ''vpb.conf'' file. It thus serves the same purpose as ''zapata.conf''. * ''sip.conf'' - this file contains all information on all SIP devices that we want to connect to our Asterisk server; be it one or more SIP accounts with Internet providers, or SIP capable telephones (hardware or software). When ''sip.conf'' has been set up correctly, we can refer to a SIP device by a friendly name like [1000] or [Jane]. * ''iax.conf'' - this file is just the same as the ''sip.conf'' file, only it handles devices that talk IAX2 protocol instead of the SIP protocol. These five files define all channels that our basic Asterisk PBX might handle (well, it won't even handle the last one, since we're not connecting any other Asterisk boxes or IAX-(soft)phones to our PBX, and it won't handle the third one if you don't have a Voicetronix card). As a reference, we're going to list the contents of four example files, and explain what they do in the way of preparing channels for our simple Asterisk server.: ==zaptel.conf== # Autogenerated by ./genzaptelconf -- do not hand edit # Zaptel Configuration File # # This file is parsed by the Zaptel Configurator, ztcfg # # It must be in the module loading order # Span 1: WCTDM/0 "Wildcard TDM410P Board 1" (MASTER) fxoks=1 fxoks=2 fxsks=3 # channel 4, WCTDM, no module. # Global data loadzone = nl defaultzone = nl This is a relatively simple file, configuring three Digium modules. As you can see, the ''genzaptelconf'' command has generated it for us. It belongs with a Digium TDM410P card, which has two FXS modules in positions 1 and 2, and one FXO module in position 3. The first two non-commented lines define the protocol that the FXS modules must "talk" with the attached devices, which "naturally" is the FXO protocol (yes, FXS talks FXO, and FXO talks FXS... a bit like electric current flowing from negative to positive. It's just a matter of definitions).<br> The third line defines that the FXO module talks FXS protocol.<br> The fourth line configures a set of indications to use for the defined channels. Since we're loading "nl", we're configuring Dutch dialtones etcetera for the channels.<br> Finally, the last line tell the server that any channel that does not have a zone assigned to it, should have the specified default zone configured - Dutch as well in this example.<br> With this simple file, the driver for our example card (''wctdm24xxp'', by the way) can set up the hardware just as we want it. Now to tell Asterisk how to use it... ==zapata-channels.conf== ; Autogenerated by ./genzaptelconf -- do not hand edit ; Zaptel Channels Configurations (zapata.conf) ; ; This is not intended to be a complete zapata.conf. Rather, it is intended ; to be #include-d by /etc/zapata.conf that will include the global settings ; ; Span 1: WCTDM/0 "Wildcard TDM410P Board 1" (MASTER) ;;; line="1 WCTDM/0/0" signalling=fxo_ks callerid="Channel 1" <6001> mailbox=6001 group=5 context=from-internal channel => 1 callerid= mailbox= group= context=default ;;; line="2 WCTDM/0/1" signalling=fxo_ks callerid="Channel 2" <6002> mailbox=6002 group=5 context=from-internal channel => 2 callerid= mailbox= group= context=default ;;; line="3 WCTDM/0/2" signalling=fxs_ks callerid=asreceived group=0 context=from-pstn channel => 3 context=default This second file is also auto-generated. It sets up three channels, associated with the three Digium hardware modules that we've configured with ''zaptel.conf''. Here, we also see how the channel numbers get assigned to the physical ports. The first module gets to be Zap channel 1 ('''Zap/1'''), the second '''Zap/2''' and so on. So if we would like our FXO module to be channel 1, and our FXS modules 2 and three, we could rotate the three channel numbers in this file. Probably we'd then also want to rotate the ''callerid''`s though... Furthermore, we don't think it's a good idea to assign channels to Zap devices in a different order than the devices are found in the system - meaning "stick with the default numbering as much as possible". Note that the way ''zapata-channels.conf'' is interpreted, means that any statement like ''signalling=fxs_ks'' actually ''sets'' the ''signalling'' parameter; when the ''channel => 1'' line is reached, then all preceding parameter assignments are applied to that particular channel. This also means that if you somewhere have set a channel to belong to context "foo", and then never set a context again, then every next channel also gets assigned to "foo". So remember: if you don't see a parameter being set with a specific channel, you CANNOT assume that it then has it's default value; if a preceding channel has set that parameter to value "bar", then for your specific channel, it is "bar" also. An interesting thing to see here is how ''genzaptelconf'' deals with the above concept. After defining each channel, it resets the most important parameters (a.o. the ones that should be unique with a channel) to empty or "default". This means that if you yourself are very meticulous, you could do without that safety net, and rewrite the above configuration file as: signalling=fxo_ks callerid="Channel 1" <6001> mailbox=6001 group=5 context=from-internal channel => 1 signalling=fxo_ks callerid="Channel 2" <6002> mailbox=6002 group=5 context=from-internal channel => 2 signalling=fxs_ks callerid=asreceived group=0 context=from-pstn channel => 3 Note: we like the thoroughnes of the ''genzaptelconf'' configuration, but we like the readability of the second file more. ==zapata.conf== [trunkgroups] [channels] switchtype=national rxwink=300 ; Atlas seems to use long (250ms) winks usecallerid=yes hidecallerid=no callwaiting=yes usecallingpres=yes callwaitingcallerid=yes threewaycalling=yes transfer=yes canpark=yes cancallforward=yes callreturn=yes echocancel=yes echocancelwhenbridged=yes rxgain=0.0 txgain=0.0 callgroup=1 pickupgroup=1 immediate=no #include zapata-channels.conf Under Debian, ==sip.conf== This is a sample configuration for VOIP with XS4ALL ;;/etc/asterisk/sip.conf;; [general] context=default externip=setyoureiphere dtfmmode=inband localnet=192.168.70.0/24 port=5060 bindaddr=0.0.0.0 disallow=all allow=alaw allow=ulaw registerattempts=0 defaultexpiry=7200 register => 08787XXXXX:PASSWORD@sip.xs4all.nl/08787XXXXX [xs4all] type=friend username=08787XXXXX fromuser=08787XXXXX fromdomain=sip.xs4all.nl secret=PASSWORD host=sip.xs4all.nl insecure=invite context=fromxs4all canreinvite=no dtmfmode=inband disallow=all allow=alaw allow=ulaw ==DAHDI== From Asterisk version 1.4, the ''zaptel'' hardware driver has been renamed to ''DAHDI'' witch stands for "Digium Asterisk Hardware Device Interface". For information on the compilation and installation of DAHDI, see [[Installing_and_configuring_DAHDI|here]]. = Asterisk dialplans - contexts = A dial plan consists of a number of extensions. Each extensions consists of a number of priorities. Extensions are grouped in contexts. For each priority, an application is called. [context] exten => id, priority, command When Asterisk receives an incoming connection on a channel, Asterisk looks at the context defined for that channel for commands telling Asterisk what it should do. The context defines different sets of commands depending on what extension the user has dialed. For example, a context might provide one set of commands for what to do if the user dials "123", and another set of commands for what to do if the user dials "9", and another set of commands for what to do if the user dials any number beginning with "555". For some kinds of connections — such incoming calls from an outside telephone line — the user has not dialed an extension. In that case, Asterisk behaves as if the user had dialed a special extension named "s" (for Start). Asterisk will look for an extension "number" s in the definition of the context for that channel for instructions about what it should do to handle the call. Let's say, for example, that you have a channel "Zap/1" which is a connection to a telephone handset in your building. And let's say that in the configuration file for Zap channels (zapata.conf), you have defined context=john for Zap channel 1. So when you use that handset to dial a number, Asterisk looks for a context with the name "john" in extensions.conf to find out what it should do. You begin the definition of a context in extensions.conf by putting the name of the context in square brackets on a line by itself, like this: [john] == extensions.conf == [globals] [general] autofallthrough=yes [default] include => fromxs4all [fromxs4all] exten => 08787XXXXX,1,Dial(DAHDI/2) exten => 08787XXXXX,n,Hangup() [outgoing] exten => _X.,1,Dial(sip/xs4all/${EXTEN},60,r) [internal] exten => 6004,1,Dial(sip/6004) exten => 6003,1,Dial(sip/6003) exten => 6005,1,Dial(DAHDI/2) exten => 6006,1,Answer() exten => 6006,n,Playback(hello-world) exten => 6006,n,Hangup() [phones] include => internal include => fromxs4all include => outgoing e8429598361591a1e6882eed79e4309824639c64 0 1 2665 2501 2011-04-09T04:10:58Z Saruman! 2 added backup link wikitext text/x-wiki <big>'''Welcome to SaruWiki.'''</big> This Wiki is intended to document bits and bobs about [http://www.kernel.org/ Linux] (and some Unix) in general, and [http://www.debian.org Debian] in particular. In it, [[SaruWiki:About|we]] wish to collect the tips and tricks of both [[SaruWiki:About|our own team of Linux admins]] and those of other interested users. If you are interested in my work on [http://www.dya.info DYA|Infrastructure], please visit the [https://dya-knowledge.sogeti.nl/ SmartMart demo site]. Consult the [http://meta.wikimedia.org/wiki/Help:Contents User's Guide] for information on using this wiki's software. <big>NOTE:</big> '''you must confirm edits''' when you're not logged in with a user account. Thanks to the Mediawiki ConfirmEdit extension we've cut our wikispam considerably. Sorry to make you anonymous contributors jump through this little hoop for every edit, but there you are. ---- <big>'''Main Content'''</big> * Setting up a [[Debian Lenny base server]] is a howto on the installation of a very basic Linux box under Lenny (it's actually not even a server yet). * Using ''md'' for [[software-based RAID]] contains our ideas and observations on redundancy. * The use of [[APT and aptitude]] is crucial to the concept of a Debian machine. * [[Roll your own kernel]] discusses the pros and cons of compiling your own kernel, and how to do it. * [[Essential system software]] lists all (sets of) packages that we deem, well, essential. * [[Apache2 and PHP5]] are essential packages if you want to light your own little [[LAMP]]. * [[Pluggable Authentication Modules (PAM)]] is a great way to secure your server and arrange logins - if you get to understand them * [[Certificate fundamentals | The "certificates" section]] explains how you create your own Certificate Authority (CA) and the neat things you can do with it. * [[Database 101]] introduces you to MySQL. * [[OpenLDAP]] is a rudimentary howto about getting OpenLDAP to be your central user repository. * The [[Installing SaMBa with OpenLDAP support | SaMBa section]] explains how to install SaMBa with OpenLDAP as user backend. * [[Add an X11 server]] to your server, if you need one. * Of course we have a [[e-mail server section]], where we focus on Postfix and virtual mail domains, and add in a whiff of MySQL and OpenLDAP. * The [[Asterisk section]] is about all things re: telephony on Debian Lenny. * The [[system boot procedure]] section explains what we can customise in the standard ways Debian boots. * The [[networking section]] treats subjects like setting persistent routes. * The [[firewall section]] is where we discuss "IPtables" (netfilter) and how we use it for firewalling. * The [[native IPsec tunnel]] section describes how to configure an IPsec tunnel. * [[Hardware monitoring]] is important for your server's health and reliability. * [[Vmware_server|VMware Server basics]] gives some pointers on how to install VMware Server on a Debian server box. * Make your server a [[Microsoft PPTP server | Microsoft client compatible VPN Server ]]. * Creating a [[backup]] for your server. * How to install [[Mediawiki Installation | Mediawiki]] on your Debian server - like what you're looking at now. If you'd like to create a new page, please log in and go ahead: <inputbox> type=create </inputbox> ---- '''Note''': the Wiki admins reserve the right to edit or remove any content they feel is not suitable for this site, not relevant, (too) inaccurate or otherwise not in line with the intentions and spirit of the admin team. ---- <websiteFrame> website=http://www.google.com/talk/service/badge/Show?tk&#61;z01q6amlqld8jocej2ca891jl9dunqqra83nhehaoqpednb5skkur0fv70jsuavce4ii9ms5e9afdr8qmpsc1d9upni4jom8g1em3p1cvq1p5eo1ugv162fosgprdv867iuememlcogfle8n3dmcf97durjld85avnh8k5lm1&amp;w=200&amp;h=60 border=0 height=60 width=200 name=GoogleChatwithSaruman! allowtransparency=true </websiteFrame> 21f345707570accec12ca59c5d5fd64d42d4a83f 2669 2665 2011-04-12T09:44:11Z Saruman! 2 moved to squeeze wikitext text/x-wiki <big>'''Welcome to SaruWiki.'''</big> This Wiki is intended to document bits and bobs about [http://www.kernel.org/ Linux] (and some Unix) in general, and [http://www.debian.org Debian] in particular. In it, [[SaruWiki:About|we]] wish to collect the tips and tricks of both [[SaruWiki:About|our own team of Linux admins]] and those of other interested users. If you are interested in my work on [http://www.dya.info DYA|Infrastructure], please visit the [https://dya-knowledge.sogeti.nl/ SmartMart demo site]. Consult the [http://meta.wikimedia.org/wiki/Help:Contents User's Guide] for information on using this wiki's software. <big>NOTE:</big> '''you must confirm edits''' when you're not logged in with a user account. Thanks to the Mediawiki ConfirmEdit extension we've cut our wikispam considerably. Sorry to make you anonymous contributors jump through this little hoop for every edit, but there you are. ---- <big>'''Main Content'''</big> * Setting up a [[Debian Squeeze base server]] is a howto on the installation of a very basic Linux box under Lenny (it's actually not even a server yet). * Using ''md'' for [[software-based RAID]] contains our ideas and observations on redundancy. * The use of [[APT and aptitude]] is crucial to the concept of a Debian machine. * [[Roll your own kernel]] discusses the pros and cons of compiling your own kernel, and how to do it. * [[Essential system software]] lists all (sets of) packages that we deem, well, essential. * [[Apache2 and PHP5]] are essential packages if you want to light your own little [[LAMP]]. * [[Pluggable Authentication Modules (PAM)]] is a great way to secure your server and arrange logins - if you get to understand them * [[Certificate fundamentals | The "certificates" section]] explains how you create your own Certificate Authority (CA) and the neat things you can do with it. * [[Database 101]] introduces you to MySQL. * [[OpenLDAP]] is a rudimentary howto about getting OpenLDAP to be your central user repository. * The [[Installing SaMBa with OpenLDAP support | SaMBa section]] explains how to install SaMBa with OpenLDAP as user backend. * [[Add an X11 server]] to your server, if you need one. * Of course we have a [[e-mail server section]], where we focus on Postfix and virtual mail domains, and add in a whiff of MySQL and OpenLDAP. * The [[Asterisk section]] is about all things re: telephony on Debian Lenny. * The [[system boot procedure]] section explains what we can customise in the standard ways Debian boots. * The [[networking section]] treats subjects like setting persistent routes. * The [[firewall section]] is where we discuss "IPtables" (netfilter) and how we use it for firewalling. * The [[native IPsec tunnel]] section describes how to configure an IPsec tunnel. * [[Hardware monitoring]] is important for your server's health and reliability. * [[Vmware_server|VMware Server basics]] gives some pointers on how to install VMware Server on a Debian server box. * Make your server a [[Microsoft PPTP server | Microsoft client compatible VPN Server ]]. * Creating a [[backup]] for your server. * How to install [[Mediawiki Installation | Mediawiki]] on your Debian server - like what you're looking at now. If you'd like to create a new page, please log in and go ahead: <inputbox> type=create </inputbox> ---- '''Note''': the Wiki admins reserve the right to edit or remove any content they feel is not suitable for this site, not relevant, (too) inaccurate or otherwise not in line with the intentions and spirit of the admin team. ---- <websiteFrame> website=http://www.google.com/talk/service/badge/Show?tk&#61;z01q6amlqld8jocej2ca891jl9dunqqra83nhehaoqpednb5skkur0fv70jsuavce4ii9ms5e9afdr8qmpsc1d9upni4jom8g1em3p1cvq1p5eo1ugv162fosgprdv867iuememlcogfle8n3dmcf97durjld85avnh8k5lm1&amp;w=200&amp;h=60 border=0 height=60 width=200 name=GoogleChatwithSaruman! allowtransparency=true </websiteFrame> 9a3403b19915fe2b5dc17f1df13ab0fe6ddfedd4 0 1617 2666 2011-04-09T04:54:53Z Saruman! 2 backup outlined wikitext text/x-wiki If you have a server, you need a good backup. No really. You need a good backup. You only have the server because it delivers services that you want to have delivered, and you've invested time and effort in getting the server to deliver those services. Furthermore, your server will contain more or less valuable data. There may come a time when you lose part or all of your server: due to hardware failure, corruption due to unexpected shutdown, malware, hacking, theft, fire or other disasters, failed upgrade, or user or operator error. When that happens, you probably want to restore the services your server was providing. This goes much faster and cheaper (in time, money, or both) if you have a current backup. ==What to backup== In essence, everything you need to backup should be on your server's file system. Depending on your configuration, you want to include the following items in your backup: * a file-based backup of ** your ''/data'' directory, as it contains your data (if you've created such a place in your filesystem). Note that if you have daemons or services that keep files open (e.g. a MySQL server that stores its databases under ''/data/mysql''), then you may want to stop the daemon or service, make a copy of the files, and then restart the services ** the ''/home'' directory, as it contains the environment of the ''root'' user, your own user account, and possibly the accounts of other users on the system; ** the ''/etc'' directory, as it contains the complete configuration of your server ** the ''/boot'' directory, as it contains the files with which to boot your server with all it's hardware * a database dump of ** the database's internal database, containing users, permissions and such; ** each of your production databases. * the following bits of system data ** for every hard disk: a copy of the partition table ** for every bootable hard disk in your system: a file containing a copy of the Master Boot Record (MBR) ** if you use LVM: a backup of your LVM configuration There are also things that you probably do NOT want to backup: * the ''/tmp'' directory, * several directories under ''/var'', most likely ''/var/run'', ''/var/spool'' and ''/var/cache''. ==How to backup== # connect and mount an external USB harddisk, e.g. under ''/media/backup''; # make an initial file-based copy of all your data files using ''cp -pR <datapath> <backuppath>'', e.g. #:''cp -pR /data /media/backup'' # copy the partition table of each harddisk, or at least of each bootable harddisk: #: ''sfdisk -d /dev/sda > /media/backup/partitions.sda'' # copy the boot sector of each bootable harddisk: #: ''dd if=/dev/sda of=/media/backup/MBRsda.bin bs=512 count=1'' # backup your LVM configuration: #: ''vgcfgbackup -v -f /media/backup/vgcfgbackup.lvm'' # dump your MySQL databases to files: #: ==What to test== When you've created a backup, you may want to perform some tests before starting that risky upgrade: * REBOOT your server! You must be sure that you've got a backup from a server that can actually reboot. If you have a boot problem, fix it, then update your backup; * Check your filesystems (your reboot may have done that for you). ==How to restore== You should know how to restore the data you've backed up, or the backup is totally useless: "nobody cares if you can backup, only if you can restore". cea7a77b4667b25aea54268d21d6e98f2a7d636b 0 1618 2667 2011-04-12T09:07:04Z Saruman! 2 intermediate save wikitext text/x-wiki <big>'''Debian Squeeze Base Server setup'''</big> ==Getting the hardware== {| class="wikitable" border="1" |- |Note: in the following we're assuming you'll be assembling an x86 or x64 type of machine, as it has about the best price/performance ratio you could wish. Hardware costs for other platforms, e.g. IBM's Series p or HP 9000, can be much higher, while platforms like ARM are just not very powerful. Also, the availability of components and of help can be less than with the ubiquitous x86/x64 platforms. |} Naturally, before we can begin to install the operating system, we need to obtain the necessary hardware. Which hardware you require depends on what you want the server for; a testserver on which you will test only a single feature for a short while does not need the same quality of hardware as does a server that's supposed to act as a homeserver for many tasks for a long time. We'll assume your server will be like ours: a home server that must perform many tasks with sufficient performance for a few users, that's reliable and will last for a couple of years. So build or obtain a server with at least the following hardware: * a spacious casing with big, quiet cooling fans, like the [http://www.coolermaster.com/products/product.php?act=detail&id=317 one we have]; * an efficient, heavy-duty power supply that's rated high enough for your devices, and has a decent efficiency. For example, a [http://www.corsair.com/products/power_supplies.aspx Corsair HX520] power supply; * a server class motherboard, e.g. an [http://www.intel.com/products/server/index.htm?iid=home+hdr_nav2_server Intel] or [http://uk.asus.com/products.aspx?l1=9&l2=39&l3=263 AMD] based single-processor motherboard. DO NOT go for the cheapest motherboard you can find: if you pay peanuts, that's what you'll get. Server class motherboards have the quality, stability and durability you'll need from it, and usually also most of the needed peripherals, like multiple ethernet network cards on-board. Usually a Linux server does not require much in the way of video performance (and the screen will be used rarely, if ever), so any old integrated graphics will do. * a matching CPU - or multiple, if you think you need the power and the selected motherboard has the sockets. Furthermore, it pays to think about the energy use of your server CPU. For instance, you could choose an AMD Athlon X2 5600+, running at 2,8 Ghz and 89W maximum, but you can also go for an AMD Athlon X2 4850E, which is dualcore at 2,5GHz, but uses only 45W maximum - almost half of the former! And over a one year period, this choice can save up to 385 kWH. With electricity costing close to €0,25 per kWH (at least for some of us), that could save you €96,- a year. All I'm saying is: think about power use. * a CD-ROM- or DVD-player - although you might not need it any more after installation. Thus, you may opt to use an external USB DVD-player, if your system allows for booting from it. * ''multiple'' hard disks - you'll want redundancy, because every hard disk fails at some time. The drive with your data on it will fail fatally when it is most inconvenient to you, and any data on it that you consider valuable will likely be lost forever. To make Murphy's work somewhat harder for him, we're going to store our data redundantly, so that if any drive in the server fails, we'll not lose our data or our server. Thus, get yourself at least two hard disks for your operating system, at least 40GiB in size (don't think you'll be able to buy smaller ones nowadays), and spanking new (NEVER use old hard disks for your production server, new ones are just too cheap to run that risk!). You may also consider using 2.5" "notebook" hard disks, since they also consume less power than do 3.5" hard disks. * (multipe) network card(s) (NICs) if your motherboard does not have enough NICs integrated on-board. You'll want a NIC for your network, and another one for your Internet connection; and possible a third one for the wireless segment of your network. Now build a machine out of the above, or have someone build it for you. ==Preparation of the hardware== (Note: in the following we're again assuming you're running an x86/x64 type of machine. Hardware requirements and preparation for other platforms, e.g. IBM's Series p or HP 9000, can differ significantly) Next, check the assembled hardware: * is the configuration complete? If it does not have a CD/DVDplayer from which it can boot, then installing the software gets more difficult - at least get an USB external DVDdrive or something like that. * are all components connected properly (memory modules seated correctly in their sockets, AGP card inserted correctly into the AGP slot, et cetera) and are all cable connections made (multiple power cables to the motherboard, one power cable plus one data cable to each hard disk, etcetera)? Following this, you may hook up the machine. It's going to need power, and you will need at least a keyboard and a monitor attached. And if you want to use a Graphic User Interface to install, a mouse is required also. When you've ensured that everything is safe, you can turn on the machine, and continue to check it: * do all fans start to run when you turn on the machine? (if not, then '''quickly''' turn off your machine and correct the problem!) * does/do the hard disk(s) spin up? * do the power button and reset button operate correctly? * are the power led, HDD led and other display gadgetry functional? * when you let the machine power up, does it emit a single beep? And does it then show a Power-On Self Test screen (POST)? * Does it show the correct amount of memory in the POST screen? The correct number & speed of the CPU(s)? * Does the machine recognise all controller cards (SCSI, S-ATA etc)? And all attached DVD-drives and hard disks? * are all BIOSes/firmwares up to date? * If you have a hardware RAID controller, are your RAID arrays built already? * does the machine attempt to boot from at least the hard disk? ...et cetera. If there is any problem, or you want to update the BIOS or firmwares, it's best to do it before the operating system is installed. This Wiki, however, is not the place to get the information on how to accomplish these type of tasks. The last steps in the preparation of the hardware, are * to ensure that the machine can boot from CD/DVD, so that you can start installing Debian from it. It is possible to install Debian over the network, but that requires setting up a [http://www.debian-administration.org/articles/478 PXE Boot server] which is (currently) outside the scope of this wiki. * to connect the hardware to the Internet, so that it can get all required updates etcetera; please do ''not'' connect the box ''straight'' to the Internet, but make sure that it's safely behind a firewall, or failing that, a NAT router. By now the system should be almost ready to receive it's Operating System. But first we have an issue to tackle: that of redundancy. ==Software or hardware RAID== Your hard disks will fail. They absolutely will. It is never a question of "if", only of "when". So what will you do when the hard disk containing your complete operating system fails (besides pulling your hair out, that is)? What we propose is this: hard disks are pretty cheap nowadays, so let's use [http://en.wikipedia.org/wiki/Redundant_array_of_independent_disks RAID technology] to make our hard drive space resilient against failure of a whole drive. So first make sure that you have ''two'' disks of equal size instead of only one. Had you already been planning to use multiple disks already, then make sure you have at least ''one'' disk more than your space requirements prescribe; the space on that extra drive will provide the needed redundancy. Next, [[RAID fundamentals under Linux | click here]] to learn a bit more about RAID, to make the decision to use hardware-based and/or software-based RAID, and to plan your RAID arrays. In this example, we'll assume you're using hardware RAID on a RAID controller that's supported by the Debian installation software. This means that the installation software will "see" your RAID array(s) and present them as usable drives. ==Planning your network names== If your machine must become a part of an existing network, then it's almost certain that you already have a DNS domain in place; in that case: obtain the DNS suffix your machine will get (the DNS domain your machine will "belong" to). However, it's also possible that this machine is going to be the first machine in your new network, in which case the whole issue of DNS suffixes is wide open. If you need more information on DNS, go [[http://www.isc.org/sw/bind/arm95/Bv9ARM-all.html#id2564824 here]]. For now we'll assume you have (or will quickly obtain) a working knowledge of the DNS system. Here is our tip on choosing a DNS domain for your home network: * do '''not''' use a publicly registered domain name (e.g. "cocacola.com") for any machine that's not primarily intended to serve the public on the Internet; * for machines serving a private network, we urge you to use Top Level Domain name "lan" (to signify your machine is on a Local Area Network or LAN) * for the Domain Name itself, we suggest you use a level 2 name, like "saruman.lan", and not a level 3 name, like "mister.saruman.lan". This is only a short section on DNS, but remember that once a proper DNS system is in place, it's pretty much work to change it. At any rate, this section has most likely showed you that you need to put some thought into the DNS Domain Name design of your home network. OK, with this out of the way, we can get to installing the OS. ==Operating System installation== To install an Operating System (OS), it's kinda instrumental that you have one. Here, we're going to use [http://www.debian.org/intro/about Debian], the biggest [http://www.debian.org/intro/about#free Free] OS that we know of. Free stands for Freedom, but incidentally that Freedom also means it's gratis, an appealing aspect of Free. To get your own copy of Debian, go to their [http://www.debian.org/distrib/ download site] and obtain the latest [http://www.debian.org/releases/ Stable] image - in this wiki it's Debian 6.0, or "Squeeze" as it's also known. Besides the choice which release of Debian you want to run, you also have to know for which platform you're downloading (in our case: either ''amd64'' or ''i386'' depending on your hardware platform) and what kind of install you wish - if you have a working, fast Internet connection available at the time of install, then we recommend getting the [[http://www.debian.org/CD/netinst/ netinst] CD image; it's a relatively small CD, that'll be able to get you going, but gets most of the software you'll need straight from the 'net at install time. In the example at hand we're installing on an AMD Athlon x2-based server, on which we wish to install 64-bits software. We'll download [http://cdimage.debian.org/debian-cd/6.0.1a/amd64/iso-cd/debian-6.0.1a-amd64-CD-1.iso debian-6.0.1a-amd64-CD-1.iso], which is Squeeze after its first update. Burn this to a CD-recordable and boot your prepared hardware platform from this CD. After booting from the CD, a friendly graphic screen shows you the Installer boot menu. Your choices are * Install, the default non-graphical installation; * Graphical install, so you can click things; * Advanced options, where you can select expert options like the rescue mode; * Help; this drops you to a non-graphical screen where you can select help texts by using function keys. The screens explain how you can start the installation with extra parameters to instruct Debian to handle your hardware in a non-standard way, e.g. on an old machine with a problematic videocard you could run "install vga=771" (for some laptops) or "install vga=normal fb=false" (to disable the screen framebuffer). We're going to use the standard Command Line installation, so we choose "Install" and hit &lt;enter&gt;. {| class="wikitable" border="1" |- |We could easily use "Graphic install", in which case we'd have a nice fresh Graphical User Interface for our installation. ''We're'' not going to, because we're real men, and [http://isg.ee.ethz.ch/tools/realmen/ Real Men Don't Click]. Also, we've found that from the GUI it's hard to switch to a second console and then back. We could also go to the Advanced options, and opt for "Expert install" or "Graphical expert install" as installation method, because it gives a much finer grain of control; however we usually don't need that control, and can do without the barrage of extra questions that the "expert" installation method pose. |} After the Linux kernel finishes initializing the machine, a simple text-based installer appears that immediately starts asking questions. Answer them according to your needs. Our example system uses the following choices: * Language: English * country: other &gt; Europe &gt; Netherlands * locale (since there's no default locale for the combination Netherlands/English): United States - en_US.UTF-8 * keymap: American English (since we have a keyboard with US layout) Some installation software loads, and we get to the next phase: if you have multiple NICs in your machine (which we believe you ''should'' have!!), and if they're detected properly, then you're required to indicate which of the detected network interface cards (NIC) is going to be the "primary" NIC. {| class="wikitable" border="1" |- |Here, trouble could begin. If your machine has only network cards that are '''not''' supported, then you'll see '''no''' cards here - but then how are you going to do a NetInstall? A solution would be to (temporarily) install a NIC that ''is'' supported, like a cheap Realtek card, or an old 3Com 905 card. Then, when the whole system is installed, up and running, you could compile a new kernel that contains support for your actual NICs, and when these work, remove the temporary NIC. For now, we'll assume that at least one of your NICs is recognised properly by the Debian installation routine. |} Select the card that's connected and has (indirect) access to Internet (again: it should ''not'' be connected straight to the wild wild web, but sit safely behind a firewall, at least until we've installed our own firewall); if at all possible, let it be the NIC that'll be connected to your home network itself, on the ''inside'' of your server. Let's assume that this NIC is designated ''eth0'' by the Debian installation. This card will now be configured using DHCP, so if you're on a network with a DHCP-server, the network will work straight away. If it's not, you can either configure the network manually or fix your DHCP-server and connection between it and ''eth0''. Next is one of the hardest questions that any OS installation is going to ask you: what will be the host name of the system? You could easily change it at any time in the future, but possibly with lots of hassle, so you better choose wisely. Here are our tips: * do '''not''' name your machine after the user that's going to use it, e.g. "bernie-pc" (at some time in the future, Bernie's machine will be moved to Alice, so then Alice is working on "bernie-pc" which makes the situation quite unclear); * do '''not''' name your machine after the department or workgroup that's using it most, e.g. "accounting-srv" (same reasoning); * do '''not''' name your machine after it's main function, e.g. "printserver" (at some time in the future, the main function is moved to another machine, and/or an alternative function will become the main function of the machine); * do '''not''' name your machine after it's location, e.g. "srv-boston" (at some time in the future, the box will be moved to another location); * do '''not''' name your machine after it's hardware configuration, e.g. "ibmx346" (at some time in the future, either another xSeries x346 will be wheeled in, or the machine will be upgraded to accomodate increased use or overcome hardware problems - your "ibmx346" could suddenly be running on an xSeries x3650). What we feel are safe names for ''any'' machine in your network are true names, perhaps linked to a common theme: names of European cities, names of movie characters, names of countries or holiday destinations et cetera. Less imaginative would be coded names like "server0001". Immediately following comes the question of the Domain Name. This is about a DNS domain, so effectively the installation program is asking which DNS suffix the host name should have; if the DHCP-server already provided something it'll be suggested, but you can override it if need be. In the preparatory phase, you'll have decided on continuation of your current DNS schema, or starting a new one. Either way, put the chosen DNS suffix in and press &lt;enter&gt;. Next comes one '''VERY''' important question: what to use as root password? We cannot stress this enough: choose a SAFE password! Do NOT go for an easy-to-remember one, go for STRONG and SAFE. There are tools to help you generate strong passwords, like [http://www.pctools.com/guides/password/ this page]: use them! We strongly suggest 10 characters or more, including letters, mixed case, and numbers, so something like ''SuCRe4hecH'' (do NOT use this, generate your own!). Next, give the full name of the principal user of this server (your own, we assume), give the login-name (your given name, we assume), and a corresponding password. Again, use a SAFE password. As long as you don't make your principal user equivalent to root, you might go for a slightly weaker password (8 characters instead of 10), but we rather suggest you make the password just as strong (and different from!) the root password. After entering the details of these two users "root" and "you", we get to the server hardware. ==Partitioning== Now comes the question of partitioning, or how to divide the available disk space into chunks for the server to use. This is a tricky subject, because if you put all storage space into one partition, then some day a runaway process will fill up the entire disk with useless logs, and the system will crash. On the other hand, if you divvy up all space into little chunks, then some application is going to need space in one of those partitions where there is none, even though there may be plenty in other partitions. To minimize the chance of either problem occurring, we're going to use [http://tldp.org/HOWTO/LVM-HOWTO/whatisvolman.html Logical Volume Management (LVM2)] so that we can provision enough space to start our server, but keep some space in reserve to apply when needed, where it'll be needed. So, we at Saruman.biz have put together a recommended standard partitioning scheme. The basis (in accordance with the standard [[Debian directory structure]]is this: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Partition !style="background:#ffdead;"|MD !style="background:#ffdead;"|LVG !style="background:#ffdead;"|LV-name !style="background:#ffdead;"|Size <br> (physical machine) !style="background:#ffdead;"|Size (VM) !style="background:#ffdead;"|File System !style="background:#ffdead;"|Mount point |- | 1 | /dev/md0 | &nbsp; | &nbsp; | 100MiB | 100MiB | ext3 | /boot |- | 2 | /dev/md1 | &nbsp; | &nbsp; | 3GiB | 1GiB | ext3 | / |- | rowspan="8" valign="top" | 3 | rowspan="8" valign="top" | /dev/md2 | rowspan="8" valign="top" style="background:lightgrey"| system | style="background:lightgrey" | swap | 1GiB<ref name="swap">Rule of thumb: twice the size of the machine's RAM, but no less than 256MiB and no more than 2GiB</ref> | 256MiB<ref name="swap"/> | swap | &nbsp; |- | style="background:lightgrey" | var | 1GiB | 512MiB | ext3 | /var |- | style="background:lightgrey" | varlog | 1GiB | 512MiB | ext3 | /var/log |- | style="background:lightgrey" | appslog | 3GiB | -<ref>Yes, we think a separate ''appslog'' is a very good idea, but when creating a minimal VM, we have to save disk space ''somewhere''...</ref> | ext3 | /var/appslog |- | style="background:lightgrey" | home | 1GiB<ref name="home">Note that this heavily depends on the purpose of the machine; if it is not to house any users, then (almost) no space is needed for /home. But on the other hand if e.g. a virtual user is to be used for keeping mailstores, or other service users need home space, then /home needs to be big enough for that.</ref> | 512MiB<ref name="home"/> | ext3 | /home |- | style="background:lightgrey" | usr | 3GiB | 3GiB | ext3 | /usr |- | style="background:lightgrey" | tmp | 1GiB | 512MiB | ext3 | /tmp |- | style="background:lightgrey" | opt | 1GiB | - | ext3 | /opt |- ! colspan="4" style="text-align:right"| Total ! 18.1GiB ! 6.9GiB ! colspan="2" | |- |} As you can see, the partition table works as follows: we assume that we wind up with 3 partitions, either on three separate software RAID arrays (''md0'' through ''md2'') or on one single hardware RAID array (in which case the 2nd column ''MD'' does not apply). The size of the partitions depends on your machine's make: for standard physical machines the 5th column does sensible suggestions, even though you could choose to have different sizes and of course different divisions altogether. If your machine happens to be a virtual one, running inside a [http://www.vmware.com/products/server/ VMware Server] or [http://www.vmware.com/products/vi/esx/ VMware ESX host], or the like, then you might want to start out with more modest partitions. The same holds for small servers that must run off Flash drives. Anyways, we're now at the Debian installation screen that lets us partition our disks. We're ''not'' going to use any of the "guided" partitionings, we go for "manual". Choosing that brings us to a screen showing all drives that the installation routine has detected, and all partitions on those drives that the installer can "see". We're going to do some assuming here once more: let's assume the drive(s) on which you want to install are visible, and are empty (containing no other partitions). <references/> ===Software RAID partitioning=== If you're to use software RAID, you now have to select the free space on the first drive, press &lt;enter&gt;, and then tell what you want to do with the free space: create a new partition, tell which size you want it to be (see table above), give the type of partition (primary), and give where on the disk it'll sit (the beginning). Next, a screen comes up that details how the partition you're requesting will be created. Here we make some changes: under "use as" we're going to select "physical volume for RAID". This clears all the other options in this screen, except for the "bootable" flag, which must be "on" for the first partition that we'll mount as ''/boot''. Now select "Done setting up the partition". Next, go to the free space on the second disk, and do ''exactly'' the same, to create an identical physical volume for RAID - if it's the first partition, select the "bootable" flag as well (we'll want to be able to boot from this second disk if the first disk fails, right?). Then go back to the rest of the free space on the first disk, make the second physical volume for RAID, duplicate it on the second disk. Then, go back to the rest of the free space on the first disk, make the third physical volume for RAID, and again duplicate it on the second disk. If you now go back to the "partition disks" overview, you'll see all the partitions you've specified listed on their respective disks. But at the top an extra option has appeared, called "configure software RAID". When you now select this option, the installer will ask if it may write the changes you've made to disk. This actually creates the partition tables on the disks. Note that at the end of configuring your partitions, an extra screen may appear (image 4): this asks if you care to identify which MD RAID devices must be started in order to be able to mount the root filesystem. Answering this question with a list of MD's like "md0 md1 md2" or simply "all" will let your server start the listed MD's very early in the boot sequence. ===Hardware RAID partitioning=== Now, if you have hardware RAID, then on your first (boot) disk just make 3 partitions, in the following manner: Select the free space on the intended boot disk, press &lt;enter&gt;, select "create a new partition", and fill out the desired size (100MB). Type is primary, location is beginning of the disk, and in the details of the partition, we only need to change the Mount point to "/boot", and set the Bootable flag to "On". Then we're "Done setting up this partition". The second partition is made the same way, but the desired size is 3GB, the Mount point is "/", and the Bootable flag remains off. Again, we're "Done setting up this partition". The third partition is again a primary partition, it takes up the entire rest of the disk, but the type is not ext3, but "physical volume for LVM". Again, we're "Done setting up this partition". But now from the main partitioner screen, we can access "Configure the Logical Volume Manager". The installer asks if it can write out the choices made to the disk, and then enters the LVM setup screen, which begins with a summary explaining that you have one Free Physical Volume, and nothing more. We now create a Volume Group (VG), which (in accordance to our partitioning standard) we'll call "system". In this VG, we'll add all Physical Volumes (being the one partition we've designated so in the previous step) using the space bar. Now we repeat the following process seven times: * select "Create Logical Volume" * select Volume Group "System" * give the LV Name (from the table, e.g. swap, var etc) * give the LV size (from the table, e.g. 1GB for swap etc) After this, we can select "Finish", the partitioner creates the seven LVs, and we're back at the partitioner screen, where there are now 7 extra "disks", with names such as ''LVM VG system, LV appslog - 3.2GB Linux device mapper''. Each of these "disks" has one block of empty space, which we now assign: seven times we repeat the following process: * select the unassigned chunk of empty space of an LV (e.g. appslog) and press &lt;enter&gt;; * Change "Use as: do not use" into the desired filesystem (ext3 - only the LV "swap" gets as filesystem type "swap area") * Change the mount point from "none" to the one corresponding with the name of the LV (note: the swap LV has no mountpoint; the appslog mountpoint must be entered manually as "/var/appslog") * If so desired, a label can be assigned to the partition (we usually don't) * select "Done setting up the partition" Once all this is done, we can look over the configuration once more, and then select "Finish partitioning and write changes to disk". A summary configuration screen will show, and we'll affirm with "yes" that these partitions can indeed be formatted. After some formatting screens flashing by (unless your partitions are particularly big, your system is particularly slow, or something goes wrong) the installation procedure continues. ==Final installer steps== the Debian installer will ask you how it can contact the Debian archives, in the dialoge "configure the package manager". For the NetInstall version of Debian, this is as good as mandatory. So here, we say "yes, use a Network Mirror", and in the following list select the country in which we are (in our case: the Netherlands), so the installer can present us with a number of network mirrors "close by". We select ftp.nl.debian.org. Next screen: should you be behind a proxy server, then it's possible to specify that here. And then the test: the system will say "scanning the mirror..." and try to contact the specified mirror. If it does not succeed, then there is either a network problem, a problem with this box's network card, or you've not specified the mirror or proxy correctly - so fix it. You'll know the network mirror has succesfully been contacted when the next dialogue appears - currently "configuring popularity-contest". Answer this question as you please. And then one of the last "big" questions: Software Selection. In this dialogue, you can easily select bundles of software to be installed. The choices are currently: * Desktop environment * Web server * Print server * DNS server * File server * Mail server * SQL database * Laptop * Standard system (selected by default) We have to make a little confession here: we've never before used this option in the installer. In fact, we even deselect the Standard System, so as to minimize the number of software packages that the base installation of our server contains. This makes it more work to manually add packages later, but we feel it gives us more control and understanding of our systems. So if you are like us: deselect the Standard System entry, and select Continue. The next dialogue handles the installation of the [http://www.gnu.org/software/grub/ ''grub'' bootloader]. Unless your disks weren't empty and you're attempting to make this system multiboot, you'll most likely get a question if you'll allow the installer to install ''grub'' into the boot sector of the first hard disk. We'll confirm with "Yes". After the installation of grub is completed, the CD-ROM is ejected, and the system is ready to reboot into Debian Etch. Remove the CD and select "Continue" ==Finishing up the installation== The system should reboot into Debian. This means you should see the following boot sequence: * your machine's standard POST messages * then, a blue grub menu on a black screen, with two entries: ** Debian GNU/Linux, kernel 2.6.&lt;something&gt; ** Debian GNU/Linux, kernel 2.6.&lt;something&gt (single-user mode); * then, after a default time-out, the first grub option will go into effect, and the Linux kernel is started. Lots of cryptic messages in grey-on-black will scroll by, until the last few lines read: "Debian GNU/Linux 4.0 &lt;hostname&gt; tty1" and "&lt;hostname&gt; login:" If your system does not reach this login, and/or some horrible error messages appear anywhere in this boot sequence, then you've got some extra work ahead. For now we'll assume you've reached the login prompt without problem. Log in as the principal user (try to avoid logging in as root! That's BAD practice!). Once logged in, save a copy of the boot messages using ''sudo dmesg > boot.txt'' or whatever you like. Then look through the boot messages, e.g. with ''vi -R boot.txt''. Furthermore, [[APT_and_aptitude | use Aptitude]] to make sure ''all'' your software is updated to the latest version. Done! Your base system is ready. You probably now want to [[essential system software | install essential software]], [[roll your own kernel]] and [[connect your server to the Internet]]. Furthermore, you might want to create a couple of [[aliases in every profile]] so that your favorite commands are always available. 182df37ac75dcdb4721605921d4045685ac623dd 2668 2667 2011-04-12T09:20:34Z Saruman! 2 /* Partitioning */ intermediate save wikitext text/x-wiki <big>'''Debian Squeeze Base Server setup'''</big> ==Getting the hardware== {| class="wikitable" border="1" |- |Note: in the following we're assuming you'll be assembling an x86 or x64 type of machine, as it has about the best price/performance ratio you could wish. Hardware costs for other platforms, e.g. IBM's Series p or HP 9000, can be much higher, while platforms like ARM are just not very powerful. Also, the availability of components and of help can be less than with the ubiquitous x86/x64 platforms. |} Naturally, before we can begin to install the operating system, we need to obtain the necessary hardware. Which hardware you require depends on what you want the server for; a testserver on which you will test only a single feature for a short while does not need the same quality of hardware as does a server that's supposed to act as a homeserver for many tasks for a long time. We'll assume your server will be like ours: a home server that must perform many tasks with sufficient performance for a few users, that's reliable and will last for a couple of years. So build or obtain a server with at least the following hardware: * a spacious casing with big, quiet cooling fans, like the [http://www.coolermaster.com/products/product.php?act=detail&id=317 one we have]; * an efficient, heavy-duty power supply that's rated high enough for your devices, and has a decent efficiency. For example, a [http://www.corsair.com/products/power_supplies.aspx Corsair HX520] power supply; * a server class motherboard, e.g. an [http://www.intel.com/products/server/index.htm?iid=home+hdr_nav2_server Intel] or [http://uk.asus.com/products.aspx?l1=9&l2=39&l3=263 AMD] based single-processor motherboard. DO NOT go for the cheapest motherboard you can find: if you pay peanuts, that's what you'll get. Server class motherboards have the quality, stability and durability you'll need from it, and usually also most of the needed peripherals, like multiple ethernet network cards on-board. Usually a Linux server does not require much in the way of video performance (and the screen will be used rarely, if ever), so any old integrated graphics will do. * a matching CPU - or multiple, if you think you need the power and the selected motherboard has the sockets. Furthermore, it pays to think about the energy use of your server CPU. For instance, you could choose an AMD Athlon X2 5600+, running at 2,8 Ghz and 89W maximum, but you can also go for an AMD Athlon X2 4850E, which is dualcore at 2,5GHz, but uses only 45W maximum - almost half of the former! And over a one year period, this choice can save up to 385 kWH. With electricity costing close to €0,25 per kWH (at least for some of us), that could save you €96,- a year. All I'm saying is: think about power use. * a CD-ROM- or DVD-player - although you might not need it any more after installation. Thus, you may opt to use an external USB DVD-player, if your system allows for booting from it. * ''multiple'' hard disks - you'll want redundancy, because every hard disk fails at some time. The drive with your data on it will fail fatally when it is most inconvenient to you, and any data on it that you consider valuable will likely be lost forever. To make Murphy's work somewhat harder for him, we're going to store our data redundantly, so that if any drive in the server fails, we'll not lose our data or our server. Thus, get yourself at least two hard disks for your operating system, at least 40GiB in size (don't think you'll be able to buy smaller ones nowadays), and spanking new (NEVER use old hard disks for your production server, new ones are just too cheap to run that risk!). You may also consider using 2.5" "notebook" hard disks, since they also consume less power than do 3.5" hard disks. * (multipe) network card(s) (NICs) if your motherboard does not have enough NICs integrated on-board. You'll want a NIC for your network, and another one for your Internet connection; and possible a third one for the wireless segment of your network. Now build a machine out of the above, or have someone build it for you. ==Preparation of the hardware== (Note: in the following we're again assuming you're running an x86/x64 type of machine. Hardware requirements and preparation for other platforms, e.g. IBM's Series p or HP 9000, can differ significantly) Next, check the assembled hardware: * is the configuration complete? If it does not have a CD/DVDplayer from which it can boot, then installing the software gets more difficult - at least get an USB external DVDdrive or something like that. * are all components connected properly (memory modules seated correctly in their sockets, AGP card inserted correctly into the AGP slot, et cetera) and are all cable connections made (multiple power cables to the motherboard, one power cable plus one data cable to each hard disk, etcetera)? Following this, you may hook up the machine. It's going to need power, and you will need at least a keyboard and a monitor attached. And if you want to use a Graphic User Interface to install, a mouse is required also. When you've ensured that everything is safe, you can turn on the machine, and continue to check it: * do all fans start to run when you turn on the machine? (if not, then '''quickly''' turn off your machine and correct the problem!) * does/do the hard disk(s) spin up? * do the power button and reset button operate correctly? * are the power led, HDD led and other display gadgetry functional? * when you let the machine power up, does it emit a single beep? And does it then show a Power-On Self Test screen (POST)? * Does it show the correct amount of memory in the POST screen? The correct number & speed of the CPU(s)? * Does the machine recognise all controller cards (SCSI, S-ATA etc)? And all attached DVD-drives and hard disks? * are all BIOSes/firmwares up to date? * If you have a hardware RAID controller, are your RAID arrays built already? * does the machine attempt to boot from at least the hard disk? ...et cetera. If there is any problem, or you want to update the BIOS or firmwares, it's best to do it before the operating system is installed. This Wiki, however, is not the place to get the information on how to accomplish these type of tasks. The last steps in the preparation of the hardware, are * to ensure that the machine can boot from CD/DVD, so that you can start installing Debian from it. It is possible to install Debian over the network, but that requires setting up a [http://www.debian-administration.org/articles/478 PXE Boot server] which is (currently) outside the scope of this wiki. * to connect the hardware to the Internet, so that it can get all required updates etcetera; please do ''not'' connect the box ''straight'' to the Internet, but make sure that it's safely behind a firewall, or failing that, a NAT router. By now the system should be almost ready to receive it's Operating System. But first we have an issue to tackle: that of redundancy. ==Software or hardware RAID== Your hard disks will fail. They absolutely will. It is never a question of "if", only of "when". So what will you do when the hard disk containing your complete operating system fails (besides pulling your hair out, that is)? What we propose is this: hard disks are pretty cheap nowadays, so let's use [http://en.wikipedia.org/wiki/Redundant_array_of_independent_disks RAID technology] to make our hard drive space resilient against failure of a whole drive. So first make sure that you have ''two'' disks of equal size instead of only one. Had you already been planning to use multiple disks already, then make sure you have at least ''one'' disk more than your space requirements prescribe; the space on that extra drive will provide the needed redundancy. Next, [[RAID fundamentals under Linux | click here]] to learn a bit more about RAID, to make the decision to use hardware-based and/or software-based RAID, and to plan your RAID arrays. In this example, we'll assume you're using hardware RAID on a RAID controller that's supported by the Debian installation software. This means that the installation software will "see" your RAID array(s) and present them as usable drives. ==Planning your network names== If your machine must become a part of an existing network, then it's almost certain that you already have a DNS domain in place; in that case: obtain the DNS suffix your machine will get (the DNS domain your machine will "belong" to). However, it's also possible that this machine is going to be the first machine in your new network, in which case the whole issue of DNS suffixes is wide open. If you need more information on DNS, go [[http://www.isc.org/sw/bind/arm95/Bv9ARM-all.html#id2564824 here]]. For now we'll assume you have (or will quickly obtain) a working knowledge of the DNS system. Here is our tip on choosing a DNS domain for your home network: * do '''not''' use a publicly registered domain name (e.g. "cocacola.com") for any machine that's not primarily intended to serve the public on the Internet; * for machines serving a private network, we urge you to use Top Level Domain name "lan" (to signify your machine is on a Local Area Network or LAN) * for the Domain Name itself, we suggest you use a level 2 name, like "saruman.lan", and not a level 3 name, like "mister.saruman.lan". This is only a short section on DNS, but remember that once a proper DNS system is in place, it's pretty much work to change it. At any rate, this section has most likely showed you that you need to put some thought into the DNS Domain Name design of your home network. OK, with this out of the way, we can get to installing the OS. ==Operating System installation== To install an Operating System (OS), it's kinda instrumental that you have one. Here, we're going to use [http://www.debian.org/intro/about Debian], the biggest [http://www.debian.org/intro/about#free Free] OS that we know of. Free stands for Freedom, but incidentally that Freedom also means it's gratis, an appealing aspect of Free. To get your own copy of Debian, go to their [http://www.debian.org/distrib/ download site] and obtain the latest [http://www.debian.org/releases/ Stable] image - in this wiki it's Debian 6.0, or "Squeeze" as it's also known. Besides the choice which release of Debian you want to run, you also have to know for which platform you're downloading (in our case: either ''amd64'' or ''i386'' depending on your hardware platform) and what kind of install you wish - if you have a working, fast Internet connection available at the time of install, then we recommend getting the [[http://www.debian.org/CD/netinst/ netinst] CD image; it's a relatively small CD, that'll be able to get you going, but gets most of the software you'll need straight from the 'net at install time. In the example at hand we're installing on an AMD Athlon x2-based server, on which we wish to install 64-bits software. We'll download [http://cdimage.debian.org/debian-cd/6.0.1a/amd64/iso-cd/debian-6.0.1a-amd64-CD-1.iso debian-6.0.1a-amd64-CD-1.iso], which is Squeeze after its first update. Burn this to a CD-recordable and boot your prepared hardware platform from this CD. After booting from the CD, a friendly graphic screen shows you the Installer boot menu. Your choices are * Install, the default non-graphical installation; * Graphical install, so you can click things; * Advanced options, where you can select expert options like the rescue mode; * Help; this drops you to a non-graphical screen where you can select help texts by using function keys. The screens explain how you can start the installation with extra parameters to instruct Debian to handle your hardware in a non-standard way, e.g. on an old machine with a problematic videocard you could run "install vga=771" (for some laptops) or "install vga=normal fb=false" (to disable the screen framebuffer). We're going to use the standard Command Line installation, so we choose "Install" and hit &lt;enter&gt;. {| class="wikitable" border="1" |- |We could easily use "Graphic install", in which case we'd have a nice fresh Graphical User Interface for our installation. ''We're'' not going to, because we're real men, and [http://isg.ee.ethz.ch/tools/realmen/ Real Men Don't Click]. Also, we've found that from the GUI it's hard to switch to a second console and then back. We could also go to the Advanced options, and opt for "Expert install" or "Graphical expert install" as installation method, because it gives a much finer grain of control; however we usually don't need that control, and can do without the barrage of extra questions that the "expert" installation method pose. |} After the Linux kernel finishes initializing the machine, a simple text-based installer appears that immediately starts asking questions. Answer them according to your needs. Our example system uses the following choices: * Language: English * country: other &gt; Europe &gt; Netherlands * locale (since there's no default locale for the combination Netherlands/English): United States - en_US.UTF-8 * keymap: American English (since we have a keyboard with US layout) Some installation software loads, and we get to the next phase: if you have multiple NICs in your machine (which we believe you ''should'' have!!), and if they're detected properly, then you're required to indicate which of the detected network interface cards (NIC) is going to be the "primary" NIC. {| class="wikitable" border="1" |- |Here, trouble could begin. If your machine has only network cards that are '''not''' supported, then you'll see '''no''' cards here - but then how are you going to do a NetInstall? A solution would be to (temporarily) install a NIC that ''is'' supported, like a cheap Realtek card, or an old 3Com 905 card. Then, when the whole system is installed, up and running, you could compile a new kernel that contains support for your actual NICs, and when these work, remove the temporary NIC. For now, we'll assume that at least one of your NICs is recognised properly by the Debian installation routine. |} Select the card that's connected and has (indirect) access to Internet (again: it should ''not'' be connected straight to the wild wild web, but sit safely behind a firewall, at least until we've installed our own firewall); if at all possible, let it be the NIC that'll be connected to your home network itself, on the ''inside'' of your server. Let's assume that this NIC is designated ''eth0'' by the Debian installation. This card will now be configured using DHCP, so if you're on a network with a DHCP-server, the network will work straight away. If it's not, you can either configure the network manually or fix your DHCP-server and connection between it and ''eth0''. Next is one of the hardest questions that any OS installation is going to ask you: what will be the host name of the system? You could easily change it at any time in the future, but possibly with lots of hassle, so you better choose wisely. Here are our tips: * do '''not''' name your machine after the user that's going to use it, e.g. "bernie-pc" (at some time in the future, Bernie's machine will be moved to Alice, so then Alice is working on "bernie-pc" which makes the situation quite unclear); * do '''not''' name your machine after the department or workgroup that's using it most, e.g. "accounting-srv" (same reasoning); * do '''not''' name your machine after it's main function, e.g. "printserver" (at some time in the future, the main function is moved to another machine, and/or an alternative function will become the main function of the machine); * do '''not''' name your machine after it's location, e.g. "srv-boston" (at some time in the future, the box will be moved to another location); * do '''not''' name your machine after it's hardware configuration, e.g. "ibmx346" (at some time in the future, either another xSeries x346 will be wheeled in, or the machine will be upgraded to accomodate increased use or overcome hardware problems - your "ibmx346" could suddenly be running on an xSeries x3650). What we feel are safe names for ''any'' machine in your network are true names, perhaps linked to a common theme: names of European cities, names of movie characters, names of countries or holiday destinations et cetera. Less imaginative would be coded names like "server0001". Immediately following comes the question of the Domain Name. This is about a DNS domain, so effectively the installation program is asking which DNS suffix the host name should have; if the DHCP-server already provided something it'll be suggested, but you can override it if need be. In the preparatory phase, you'll have decided on continuation of your current DNS schema, or starting a new one. Either way, put the chosen DNS suffix in and press &lt;enter&gt;. Next comes one '''VERY''' important question: what to use as root password? We cannot stress this enough: choose a SAFE password! Do NOT go for an easy-to-remember one, go for STRONG and SAFE. There are tools to help you generate strong passwords, like [http://www.pctools.com/guides/password/ this page]: use them! We strongly suggest 10 characters or more, including letters, mixed case, and numbers, so something like ''SuCRe4hecH'' (do NOT use this, generate your own!). Next, give the full name of the principal user of this server (your own, we assume), give the login-name (your given name, we assume), and a corresponding password. Again, use a SAFE password. As long as you don't make your principal user equivalent to root, you might go for a slightly weaker password (8 characters instead of 10), but we rather suggest you make the password just as strong (and different from!) the root password. After entering the details of these two users "root" and "you", we get to the server hardware. ==Partitioning== Now comes the question of partitioning, or how to divide the available disk space into chunks for the server to use. This is a tricky subject, because if you put all storage space into one partition, then some day a runaway process will fill up the entire disk with useless logs, and the system will crash. On the other hand, if you divvy up all space into little chunks, then some application is going to need space in one of those partitions where there is none, even though there may be plenty in other partitions. To minimize the chance of either problem occurring, we're going to use [http://tldp.org/HOWTO/LVM-HOWTO/whatisvolman.html Logical Volume Management (LVM2)] so that we can provision enough space to start our server, but keep some space in reserve to apply when needed, where it'll be needed. So, we at Saruman.biz have put together a recommended standard partitioning scheme. The basis (in accordance with the standard [[Debian directory structure]] is this: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Partition !style="background:#ffdead;"|MD !style="background:#ffdead;"|LVG !style="background:#ffdead;"|LV-name !style="background:#ffdead;"|Size <br> (physical machine) !style="background:#ffdead;"|Size (VM) !style="background:#ffdead;"|File System !style="background:#ffdead;"|Mount point |- | 1 | /dev/md0 | &nbsp; | &nbsp; | 100MiB | 100MiB | ext3 | /boot |- | 2 | /dev/md1 | &nbsp; | &nbsp; | 3GiB | 1GiB | ext3 | / |- | rowspan="8" valign="top" | 3 | rowspan="8" valign="top" | /dev/md2 | rowspan="8" valign="top" style="background:lightgrey"| system | style="background:lightgrey" | swap | 1GiB<ref name="swap">Rule of thumb: twice the size of the machine's RAM, but no less than 256MiB and no more than 2GiB</ref> | 256MiB<ref name="swap"/> | swap | &nbsp; |- | style="background:lightgrey" | var | 1GiB | 512MiB | ext3 | /var |- | style="background:lightgrey" | varlog | 1GiB | 512MiB | ext3 | /var/log |- | style="background:lightgrey" | appslog | 3GiB | -<ref>Yes, we think a separate ''appslog'' is a very good idea, but when creating a minimal VM, we have to save disk space ''somewhere''...</ref> | ext3 | /var/appslog |- | style="background:lightgrey" | home | 1GiB<ref name="home">Note that this heavily depends on the purpose of the machine; if it is not to house any users, then (almost) no space is needed for /home. But on the other hand if e.g. a virtual user is to be used for keeping mailstores, or other service users need home space, then /home needs to be big enough for that.</ref> | 512MiB<ref name="home"/> | ext3 | /home |- | style="background:lightgrey" | usr | 3GiB | 3GiB | ext3 | /usr |- | style="background:lightgrey" | tmp | 1GiB | 512MiB | ext3 | /tmp |- | style="background:lightgrey" | opt | 1GiB | - | ext3 | /opt |- ! colspan="4" style="text-align:right"| Total ! 18.1GiB ! 6.9GiB ! colspan="2" | |- |} As you can see, the partition table works as follows: we assume that we wind up with 3 partitions, either on three separate software RAID arrays (''md0'' through ''md2'') or on one single hardware RAID array (in which case the 2nd column ''MD'' does not apply). The size of the partitions depends on your machine's make: for standard physical machines the 5th column does sensible suggestions, even though you could choose to have different sizes and of course different divisions altogether. If your machine happens to be a virtual one, running inside a [http://www.vmware.com/products/server/ VMware Server] or [http://www.vmware.com/products/vi/esx/ VMware ESX host], or the like, then you might want to start out with more modest partitions. The same holds for small servers that must run off Flash drives. Anyways, we're now at the Debian installation screen that lets us partition our disks. We're ''not'' going to use any of the "guided" partitioning options, we go for "manual". Choosing that brings us to a screen showing all drives that the installation routine has detected, and all partitions on those drives that the installer can "see". We're going to do some assuming here once more: let's assume the drive(s) on which you want to install are visible, and are empty (containing no other partitions). <references/> ===Software RAID partitioning=== If you're to use software RAID, you now have to select the free space on the first drive, press &lt;enter&gt;, and then tell what you want to do with the free space: create a new partition, tell which size you want it to be (see table above), give the type of partition (primary), and give where on the disk it'll sit (the beginning). Next, a screen comes up that details how the partition you're requesting will be created. Here we make some changes: under "use as" we're going to select "physical volume for RAID". This clears all the other options in this screen, except for the "bootable" flag, which must be "on" for the first partition that we'll mount as ''/boot''. Now select "Done setting up the partition". Next, go to the free space on the second disk, and do ''exactly'' the same, to create an identical physical volume for RAID - if it's the first partition, select the "bootable" flag as well (we'll want to be able to boot from this second disk if the first disk fails, right?). Then go back to the rest of the free space on the first disk, make the second physical volume for RAID, duplicate it on the second disk. Then, go back to the rest of the free space on the first disk, make the third physical volume for RAID, and again duplicate it on the second disk. If you now go back to the "partition disks" overview, you'll see all the partitions you've specified listed on their respective disks. But at the top an extra option has appeared, called "configure software RAID". When you now select this option, the installer will ask if it may write the changes you've made to disk. This actually creates the partition tables on the disks. Now you can create RAID devices. The RAID levels that Debian 6.0 offer are 0 (striping), 1 (mirroring), 5 (distributed redundancy), 6 (double distributed redundancy) ant 10 (striped mirrors). For your operating system disk pair, level 1 is the only sane choice. When selecting RAID 1, the installer asks how many active devices to use (2), how many spares (0), and then offers a selection screen where you can mark all members of the array. Select the first partition of both disks (presumably ''/dev/sda1'' and ''/dev/sdb1'') which should correspond to the 100MiB partitions you've created. Then create the other MD devices. Finally, choose &lt;finish&gt;. You'll drop back to the partitioner, but now the three created devices are available in the partitioner as "RAID1 device #0" etc. ===Hardware RAID partitioning=== Now, if you have hardware RAID, then on your first (boot) disk just make 3 partitions, in the following manner: Select the free space on the intended boot disk, press &lt;enter&gt;, select "create a new partition", and fill out the desired size (100MB). Type is primary, location is beginning of the disk, and in the details of the partition, we only need to change the Mount point to "/boot", and set the Bootable flag to "On". Then we're "Done setting up this partition". The second partition is made the same way, but the desired size is 3GB, the Mount point is "/", and the Bootable flag remains off. Again, we're "Done setting up this partition". The third partition is again a primary partition, it takes up the entire rest of the disk, but the type is not ext3, but "physical volume for LVM". Again, we're "Done setting up this partition". But now from the main partitioner screen, we can access "Configure the Logical Volume Manager". The installer asks if it can write out the choices made to the disk, and then enters the LVM setup screen, which begins with a summary explaining that you have one Free Physical Volume, and nothing more. ==Logical Volume creation== We now create a Volume Group (VG), which (in accordance to our partitioning standard) we'll call "system". In this VG, we'll add all Physical Volumes (being the one partition we've designated so in the previous step) using the space bar. Now we repeat the following process seven times: * select "Create Logical Volume" * select Volume Group "System" * give the LV Name (from the table, e.g. swap, var etc) * give the LV size (from the table, e.g. 1GB for swap etc) After this, we can select "Finish", the partitioner creates the seven LVs, and we're back at the partitioner screen, where there are now 7 extra "disks", with names such as ''LVM VG system, LV appslog - 3.2GB Linux device mapper''. Each of these "disks" has one block of empty space, which we now assign: seven times we repeat the following process: * select the unassigned chunk of empty space of an LV (e.g. appslog) and press &lt;enter&gt;; * Change "Use as: do not use" into the desired filesystem (ext3 - only the LV "swap" gets as filesystem type "swap area") * Change the mount point from "none" to the one corresponding with the name of the LV (note: the swap LV has no mountpoint; the appslog mountpoint must be entered manually as "/var/appslog") * If so desired, a label can be assigned to the partition (we usually don't) * select "Done setting up the partition" Once all this is done, we can look over the configuration once more, and then select "Finish partitioning and write changes to disk". A summary configuration screen will show, and we'll affirm with "yes" that these partitions can indeed be formatted. After some formatting screens flashing by (unless your partitions are particularly big, your system is particularly slow, or something goes wrong) the installation procedure continues. ==Final installer steps== the Debian installer will ask you how it can contact the Debian archives, in the dialoge "configure the package manager". For the NetInstall version of Debian, this is as good as mandatory. So here, we say "yes, use a Network Mirror", and in the following list select the country in which we are (in our case: the Netherlands), so the installer can present us with a number of network mirrors "close by". We select ftp.nl.debian.org. Next screen: should you be behind a proxy server, then it's possible to specify that here. And then the test: the system will say "scanning the mirror..." and try to contact the specified mirror. If it does not succeed, then there is either a network problem, a problem with this box's network card, or you've not specified the mirror or proxy correctly - so fix it. You'll know the network mirror has succesfully been contacted when the next dialogue appears - currently "configuring popularity-contest". Answer this question as you please. And then one of the last "big" questions: Software Selection. In this dialogue, you can easily select bundles of software to be installed. The choices are currently: * Desktop environment * Web server * Print server * DNS server * File server * Mail server * SQL database * Laptop * Standard system (selected by default) We have to make a little confession here: we've never before used this option in the installer. In fact, we even deselect the Standard System, so as to minimize the number of software packages that the base installation of our server contains. This makes it more work to manually add packages later, but we feel it gives us more control and understanding of our systems. So if you are like us: deselect the Standard System entry, and select Continue. The next dialogue handles the installation of the [http://www.gnu.org/software/grub/ ''grub'' bootloader]. Unless your disks weren't empty and you're attempting to make this system multiboot, you'll most likely get a question if you'll allow the installer to install ''grub'' into the boot sector of the first hard disk. We'll confirm with "Yes". After the installation of grub is completed, the CD-ROM is ejected, and the system is ready to reboot into Debian Etch. Remove the CD and select "Continue" ==Finishing up the installation== The system should reboot into Debian. This means you should see the following boot sequence: * your machine's standard POST messages * then, a blue grub menu on a black screen, with two entries: ** Debian GNU/Linux, kernel 2.6.&lt;something&gt; ** Debian GNU/Linux, kernel 2.6.&lt;something&gt (single-user mode); * then, after a default time-out, the first grub option will go into effect, and the Linux kernel is started. Lots of cryptic messages in grey-on-black will scroll by, until the last few lines read: "Debian GNU/Linux 4.0 &lt;hostname&gt; tty1" and "&lt;hostname&gt; login:" If your system does not reach this login, and/or some horrible error messages appear anywhere in this boot sequence, then you've got some extra work ahead. For now we'll assume you've reached the login prompt without problem. Log in as the principal user (try to avoid logging in as root! That's BAD practice!). Once logged in, save a copy of the boot messages using ''sudo dmesg > boot.txt'' or whatever you like. Then look through the boot messages, e.g. with ''vi -R boot.txt''. Furthermore, [[APT_and_aptitude | use Aptitude]] to make sure ''all'' your software is updated to the latest version. Done! Your base system is ready. You probably now want to [[essential system software | install essential software]], [[roll your own kernel]] and [[connect your server to the Internet]]. Furthermore, you might want to create a couple of [[aliases in every profile]] so that your favorite commands are always available. b65c29c1ca2900dbd7e96cb47e374a2b215618b8 2670 2668 2011-04-12T10:17:22Z Saruman! 2 partitioning expanded wikitext text/x-wiki <big>'''Debian Squeeze Base Server setup'''</big> ==Getting the hardware== {| class="wikitable" border="1" |- |Note: in the following we're assuming you'll be assembling an x86 or x64 type of machine, as it has about the best price/performance ratio you could wish. Hardware costs for other platforms, e.g. IBM's Series p or HP 9000, can be much higher, while platforms like ARM are just not very powerful. Also, the availability of components and of help can be less than with the ubiquitous x86/x64 platforms. |} Naturally, before we can begin to install the operating system, we need to obtain the necessary hardware. Which hardware you require depends on what you want the server for; a testserver on which you will test only a single feature for a short while does not need the same quality of hardware as does a server that's supposed to act as a homeserver for many tasks for a long time. We'll assume your server will be like ours: a home server that must perform many tasks with sufficient performance for a few users, that's reliable and will last for a couple of years. So build or obtain a server with at least the following hardware: * a spacious casing with big, quiet cooling fans, like the [http://www.coolermaster.com/products/product.php?act=detail&id=317 one we have]; * an efficient, heavy-duty power supply that's rated high enough for your devices, and has a decent efficiency. For example, a [http://www.corsair.com/products/power_supplies.aspx Corsair HX520] power supply; * a server class motherboard, e.g. an [http://www.intel.com/products/server/index.htm?iid=home+hdr_nav2_server Intel] or [http://uk.asus.com/products.aspx?l1=9&l2=39&l3=263 AMD] based single-processor motherboard. DO NOT go for the cheapest motherboard you can find: if you pay peanuts, that's what you'll get. Server class motherboards have the quality, stability and durability you'll need from it, and usually also most of the needed peripherals, like multiple ethernet network cards on-board. Usually a Linux server does not require much in the way of video performance (and the screen will be used rarely, if ever), so any old integrated graphics will do. * a matching CPU - or multiple, if you think you need the power and the selected motherboard has the sockets. Furthermore, it pays to think about the energy use of your server CPU. For instance, you could choose an AMD Athlon X2 5600+, running at 2,8 Ghz and 89W maximum, but you can also go for an AMD Athlon X2 4850E, which is dualcore at 2,5GHz, but uses only 45W maximum - almost half of the former! And over a one year period, this choice can save up to 385 kWH. With electricity costing close to €0,25 per kWH (at least for some of us), that could save you €96,- a year. All I'm saying is: think about power use. * a CD-ROM- or DVD-player - although you might not need it any more after installation. Thus, you may opt to use an external USB DVD-player, if your system allows for booting from it. * ''multiple'' hard disks - you'll want redundancy, because every hard disk fails at some time. The drive with your data on it will fail fatally when it is most inconvenient to you, and any data on it that you consider valuable will likely be lost forever. To make Murphy's work somewhat harder for him, we're going to store our data redundantly, so that if any drive in the server fails, we'll not lose our data or our server. Thus, get yourself at least two hard disks for your operating system, at least 40GiB in size (don't think you'll be able to buy smaller ones nowadays), and spanking new (NEVER use old hard disks for your production server, new ones are just too cheap to run that risk!). You may also consider using 2.5" "notebook" hard disks, since they also consume less power than do 3.5" hard disks. * (multipe) network card(s) (NICs) if your motherboard does not have enough NICs integrated on-board. You'll want a NIC for your network, and another one for your Internet connection; and possible a third one for the wireless segment of your network. Now build a machine out of the above, or have someone build it for you. ==Preparation of the hardware== (Note: in the following we're again assuming you're running an x86/x64 type of machine. Hardware requirements and preparation for other platforms, e.g. IBM's Series p or HP 9000, can differ significantly) Next, check the assembled hardware: * is the configuration complete? If it does not have a CD/DVDplayer from which it can boot, then installing the software gets more difficult - at least get an USB external DVDdrive or something like that. * are all components connected properly (memory modules seated correctly in their sockets, AGP card inserted correctly into the AGP slot, et cetera) and are all cable connections made (multiple power cables to the motherboard, one power cable plus one data cable to each hard disk, etcetera)? Following this, you may hook up the machine. It's going to need power, and you will need at least a keyboard and a monitor attached. And if you want to use a Graphic User Interface to install, a mouse is required also. When you've ensured that everything is safe, you can turn on the machine, and continue to check it: * do all fans start to run when you turn on the machine? (if not, then '''quickly''' turn off your machine and correct the problem!) * does/do the hard disk(s) spin up? * do the power button and reset button operate correctly? * are the power led, HDD led and other display gadgetry functional? * when you let the machine power up, does it emit a single beep? And does it then show a Power-On Self Test screen (POST)? * Does it show the correct amount of memory in the POST screen? The correct number & speed of the CPU(s)? * Does the machine recognise all controller cards (SCSI, S-ATA etc)? And all attached DVD-drives and hard disks? * are all BIOSes/firmwares up to date? * If you have a hardware RAID controller, are your RAID arrays built already? * does the machine attempt to boot from at least the hard disk? ...et cetera. If there is any problem, or you want to update the BIOS or firmwares, it's best to do it before the operating system is installed. This Wiki, however, is not the place to get the information on how to accomplish these type of tasks. The last steps in the preparation of the hardware, are * to ensure that the machine can boot from CD/DVD, so that you can start installing Debian from it. It is possible to install Debian over the network, but that requires setting up a [http://www.debian-administration.org/articles/478 PXE Boot server] which is (currently) outside the scope of this wiki. * to connect the hardware to the Internet, so that it can get all required updates etcetera; please do ''not'' connect the box ''straight'' to the Internet, but make sure that it's safely behind a firewall, or failing that, a NAT router. By now the system should be almost ready to receive it's Operating System. But first we have an issue to tackle: that of redundancy. ==Software or hardware RAID== Your hard disks will fail. They absolutely will. It is never a question of "if", only of "when". So what will you do when the hard disk containing your complete operating system fails (besides pulling your hair out, that is)? What we propose is this: hard disks are pretty cheap nowadays, so let's use [http://en.wikipedia.org/wiki/Redundant_array_of_independent_disks RAID technology] to make our hard drive space resilient against failure of a whole drive. So first make sure that you have ''two'' disks of equal size instead of only one. Had you already been planning to use multiple disks already, then make sure you have at least ''one'' disk more than your space requirements prescribe; the space on that extra drive will provide the needed redundancy. Next, [[RAID fundamentals under Linux | click here]] to learn a bit more about RAID, to make the decision to use hardware-based and/or software-based RAID, and to plan your RAID arrays. In this example, we'll assume you're using hardware RAID on a RAID controller that's supported by the Debian installation software. This means that the installation software will "see" your RAID array(s) and present them as usable drives. ==Planning your network names== If your machine must become a part of an existing network, then it's almost certain that you already have a DNS domain in place; in that case: obtain the DNS suffix your machine will get (the DNS domain your machine will "belong" to). However, it's also possible that this machine is going to be the first machine in your new network, in which case the whole issue of DNS suffixes is wide open. If you need more information on DNS, go [[http://www.isc.org/sw/bind/arm95/Bv9ARM-all.html#id2564824 here]]. For now we'll assume you have (or will quickly obtain) a working knowledge of the DNS system. Here is our tip on choosing a DNS domain for your home network: * do '''not''' use a publicly registered domain name (e.g. "cocacola.com") for any machine that's not primarily intended to serve the public on the Internet; * for machines serving a private network, we urge you to use Top Level Domain name "lan" (to signify your machine is on a Local Area Network or LAN) * for the Domain Name itself, we suggest you use a level 2 name, like "saruman.lan", and not a level 3 name, like "mister.saruman.lan". This is only a short section on DNS, but remember that once a proper DNS system is in place, it's pretty much work to change it. At any rate, this section has most likely showed you that you need to put some thought into the DNS Domain Name design of your home network. OK, with this out of the way, we can get to installing the OS. ==Operating System installation== To install an Operating System (OS), it's kinda instrumental that you have one. Here, we're going to use [http://www.debian.org/intro/about Debian], the biggest [http://www.debian.org/intro/about#free Free] OS that we know of. Free stands for Freedom, but incidentally that Freedom also means it's gratis, an appealing aspect of Free. To get your own copy of Debian, go to their [http://www.debian.org/distrib/ download site] and obtain the latest [http://www.debian.org/releases/ Stable] image - in this wiki it's Debian 6.0, or "Squeeze" as it's also known. Besides the choice which release of Debian you want to run, you also have to know for which platform you're downloading (in our case: either ''amd64'' or ''i386'' depending on your hardware platform) and what kind of install you wish - if you have a working, fast Internet connection available at the time of install, then we recommend getting the [[http://www.debian.org/CD/netinst/ netinst] CD image; it's a relatively small CD, that'll be able to get you going, but gets most of the software you'll need straight from the 'net at install time. In the example at hand we're installing on an AMD Athlon x2-based server, on which we wish to install 64-bits software. We'll download [http://cdimage.debian.org/debian-cd/6.0.1a/amd64/iso-cd/debian-6.0.1a-amd64-CD-1.iso debian-6.0.1a-amd64-CD-1.iso], which is Squeeze after its first update. Burn this to a CD-recordable and boot your prepared hardware platform from this CD. After booting from the CD, a friendly graphic screen shows you the Installer boot menu. Your choices are * Install, the default non-graphical installation; * Graphical install, so you can click things; * Advanced options, where you can select expert options like the rescue mode; * Help; this drops you to a non-graphical screen where you can select help texts by using function keys. The screens explain how you can start the installation with extra parameters to instruct Debian to handle your hardware in a non-standard way, e.g. on an old machine with a problematic videocard you could run "install vga=771" (for some laptops) or "install vga=normal fb=false" (to disable the screen framebuffer). We're going to use the standard Command Line installation, so we choose "Install" and hit &lt;enter&gt;. {| class="wikitable" border="1" |- |We could easily use "Graphic install", in which case we'd have a nice fresh Graphical User Interface for our installation. ''We're'' not going to, because we're real men, and [http://isg.ee.ethz.ch/tools/realmen/ Real Men Don't Click]. Also, we've found that from the GUI it's hard to switch to a second console and then back. We could also go to the Advanced options, and opt for "Expert install" or "Graphical expert install" as installation method, because it gives a much finer grain of control; however we usually don't need that control, and can do without the barrage of extra questions that the "expert" installation method pose. |} After the Linux kernel finishes initializing the machine, a simple text-based installer appears that immediately starts asking questions. Answer them according to your needs. Our example system uses the following choices: * Language: English * country: other &gt; Europe &gt; Netherlands * locale (since there's no default locale for the combination Netherlands/English): United States - en_US.UTF-8 * keymap: American English (since we have a keyboard with US layout) Some installation software loads, and we get to the next phase: if you have multiple NICs in your machine (which we believe you ''should'' have!!), and if they're detected properly, then you're required to indicate which of the detected network interface cards (NIC) is going to be the "primary" NIC. {| class="wikitable" border="1" |- |Here, trouble could begin. If your machine has only network cards that are '''not''' supported, then you'll see '''no''' cards here - but then how are you going to do a NetInstall? A solution would be to (temporarily) install a NIC that ''is'' supported, like a cheap Realtek card, or an old 3Com 905 card. Then, when the whole system is installed, up and running, you could compile a new kernel that contains support for your actual NICs, and when these work, remove the temporary NIC. For now, we'll assume that at least one of your NICs is recognised properly by the Debian installation routine. |} Select the card that's connected and has (indirect) access to Internet (again: it should ''not'' be connected straight to the wild wild web, but sit safely behind a firewall, at least until we've installed our own firewall); if at all possible, let it be the NIC that'll be connected to your home network itself, on the ''inside'' of your server. Let's assume that this NIC is designated ''eth0'' by the Debian installation. This card will now be configured using DHCP, so if you're on a network with a DHCP-server, the network will work straight away. If it's not, you can either configure the network manually or fix your DHCP-server and connection between it and ''eth0''. Next is one of the hardest questions that any OS installation is going to ask you: what will be the host name of the system? You could easily change it at any time in the future, but possibly with lots of hassle, so you better choose wisely. Here are our tips: * do '''not''' name your machine after the user that's going to use it, e.g. "bernie-pc" (at some time in the future, Bernie's machine will be moved to Alice, so then Alice is working on "bernie-pc" which makes the situation quite unclear); * do '''not''' name your machine after the department or workgroup that's using it most, e.g. "accounting-srv" (same reasoning); * do '''not''' name your machine after it's main function, e.g. "printserver" (at some time in the future, the main function is moved to another machine, and/or an alternative function will become the main function of the machine); * do '''not''' name your machine after it's location, e.g. "srv-boston" (at some time in the future, the box will be moved to another location); * do '''not''' name your machine after it's hardware configuration, e.g. "ibmx346" (at some time in the future, either another xSeries x346 will be wheeled in, or the machine will be upgraded to accomodate increased use or overcome hardware problems - your "ibmx346" could suddenly be running on an xSeries x3650). What we feel are safe names for ''any'' machine in your network are true names, perhaps linked to a common theme: names of European cities, names of movie characters, names of countries or holiday destinations et cetera. Less imaginative would be coded names like "server0001". Immediately following comes the question of the Domain Name. This is about a DNS domain, so effectively the installation program is asking which DNS suffix the host name should have; if the DHCP-server already provided something it'll be suggested, but you can override it if need be. In the preparatory phase, you'll have decided on continuation of your current DNS schema, or starting a new one. Either way, put the chosen DNS suffix in and press &lt;enter&gt;. Next comes one '''VERY''' important question: what to use as root password? We cannot stress this enough: choose a SAFE password! Do NOT go for an easy-to-remember one, go for STRONG and SAFE. There are tools to help you generate strong passwords, like [http://www.pctools.com/guides/password/ this page]: use them! We strongly suggest 10 characters or more, including letters, mixed case, and numbers, so something like ''SuCRe4hecH'' (do NOT use this, generate your own!). Next, give the full name of the principal user of this server (your own, we assume), give the login-name (your given name, we assume), and a corresponding password. Again, use a SAFE password. As long as you don't make your principal user equivalent to root, you might go for a slightly weaker password (8 characters instead of 10), but we rather suggest you make the password just as strong (and different from!) the root password. After entering the details of these two users "root" and "you", we get to the server hardware. ==Partitioning== Now comes the question of partitioning, or how to divide the available disk space into chunks for the server to use. This is a tricky subject, because if you put all storage space into one partition, then some day a runaway process will fill up the entire disk with useless logs, and the system will crash. On the other hand, if you divvy up all space into little chunks, then some application is going to need space in one of those partitions where there is none, even though there may be plenty in other partitions. To minimize the chance of either problem occurring, we're going to use [http://tldp.org/HOWTO/LVM-HOWTO/whatisvolman.html Logical Volume Management (LVM2)] so that we can provision enough space to start our server, but keep some space in reserve to apply when needed, where it'll be needed. So, we at Saruman.biz have put together a recommended standard partitioning scheme. The basis (in accordance with the standard [[Debian directory structure]] is this: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Partition !style="background:#ffdead;"|MD !style="background:#ffdead;"|LVG !style="background:#ffdead;"|LV-name !style="background:#ffdead;"|Size <br> (physical machine) !style="background:#ffdead;"|Size (VM) !style="background:#ffdead;"|File System !style="background:#ffdead;"|Mount point |- | 1 | /dev/md0 | &nbsp; | &nbsp; | 100MiB | 100MiB | ext3 | /boot |- | 2 | /dev/md1 | &nbsp; | &nbsp; | 3GiB | 1GiB | ext3 | / |- | rowspan="8" valign="top" | 3 | rowspan="8" valign="top" | /dev/md2 | rowspan="8" valign="top" style="background:lightgrey"| system | style="background:lightgrey" | swap | 1GiB<ref name="swap">Rule of thumb: twice the size of the machine's RAM, but no less than 256MiB and no more than 2GiB</ref> | 256MiB<ref name="swap"/> | swap | &nbsp; |- | style="background:lightgrey" | var | 1GiB | 512MiB | ext3 | /var |- | style="background:lightgrey" | varlog | 1GiB | 512MiB | ext3 | /var/log |- | style="background:lightgrey" | appslog | 3GiB | -<ref>Yes, we think a separate ''appslog'' is a very good idea, but when creating a minimal VM, we have to save disk space ''somewhere''...</ref> | ext3 | /var/appslog |- | style="background:lightgrey" | home | 1GiB<ref name="home">Note that this heavily depends on the purpose of the machine; if it is not to house any users, then (almost) no space is needed for /home. But on the other hand if e.g. a virtual user is to be used for keeping mailstores, or other service users need home space, then /home needs to be big enough for that.</ref> | 512MiB<ref name="home"/> | ext3 | /home |- | style="background:lightgrey" | usr | 3GiB | 3GiB | ext3 | /usr |- | style="background:lightgrey" | tmp | 1GiB | 512MiB | ext3 | /tmp |- | style="background:lightgrey" | opt | 1GiB | - | ext3 | /opt |- ! colspan="4" style="text-align:right"| Total ! 18.1GiB ! 6.9GiB ! colspan="2" | |- |} As you can see, the partition table works as follows: we assume that we wind up with 3 partitions, either on three separate software RAID arrays (''md0'' through ''md2'') or on one single hardware RAID array (in which case the 2nd column ''MD'' does not apply). The size of the partitions depends on your machine's make: for standard physical machines the 5th column does sensible suggestions, even though you could choose to have different sizes and of course different divisions altogether. If your machine happens to be a virtual one, running inside a [http://www.vmware.com/products/server/ VMware Server] or [http://www.vmware.com/products/vi/esx/ VMware ESX host], or the like, then you might want to start out with more modest partitions. The same holds for small servers that must run off Flash drives. Anyways, we're now at the Debian installation screen that lets us partition our disks. We're ''not'' going to use any of the "guided" partitioning options, we go for "manual". Choosing that brings us to a screen showing all drives that the installation routine has detected, and all partitions on those drives that the installer can "see". We're going to do some assuming here once more: let's assume the drive(s) on which you want to install are visible, and are empty (containing no other partitions). <references/> ===Software RAID partitioning=== If you're to use software RAID, you now have to select the free space on the first drive, press &lt;enter&gt;, and then tell what you want to do with the free space: create a new partition, tell which size you want it to be (see table above), give the type of partition (primary), and give where on the disk it'll sit (the beginning). Next, a screen comes up that details how the partition you're requesting will be created. Here we make some changes: under "use as" we're going to select "physical volume for RAID". This clears all the other options in this screen, except for the "bootable" flag, which must be "on" for the first partition that we'll mount as ''/boot''. Now select "Done setting up the partition". Next, go to the free space on the second disk, and do ''exactly'' the same, to create an identical physical volume for RAID - if it's the first partition, select the "bootable" flag as well (we'll want to be able to boot from this second disk if the first disk fails, right?). Then go back to the rest of the free space on the first disk, make the second physical volume for RAID, duplicate it on the second disk. Then, go back to the rest of the free space on the first disk, make the third physical volume for RAID, and again duplicate it on the second disk. If you now go back to the "partition disks" overview, you'll see all the partitions you've specified listed on their respective disks. But at the top an extra option has appeared, called "configure software RAID". When you now select this option, the installer will ask if it may write the changes you've made to disk. This actually creates the partition tables on the disks. Now you can create RAID devices. The RAID levels that Debian 6.0 offer are 0 (striping), 1 (mirroring), 5 (distributed redundancy), 6 (double distributed redundancy) ant 10 (striped mirrors). For your operating system disk pair, level 1 is the only sane choice. When selecting RAID 1, the installer asks how many active devices to use (2), how many spares (0), and then offers a selection screen where you can mark all members of the array. Select the first partition of both disks (presumably ''/dev/sda1'' and ''/dev/sdb1'') which should correspond to the 100MiB partitions you've created. Then create the other MD devices. Finally, choose &lt;finish&gt;. You'll drop back to the partitioner, but now the three created devices are available in the partitioner as "RAID1 device #0" etc. ===Hardware RAID partitioning=== Now, if you have hardware RAID, then on your first (boot) disk just make 3 partitions, in the following manner: Select the free space on the intended boot disk, press &lt;enter&gt;, select "create a new partition", and fill out the desired size (100MB). Type is primary, location is beginning of the disk, and in the details of the partition, we only need to change the Mount point to "/boot", and set the Bootable flag to "On". Then we're "Done setting up this partition". The second partition is made the same way, but the desired size is 3GB, the Mount point is "/", and the Bootable flag remains off. Again, we're "Done setting up this partition". The third partition is again a primary partition, it takes up the entire rest of the disk, but the type is not ext3, but "physical volume for LVM". Again, we're "Done setting up this partition". But now from the main partitioner screen, we can access "Configure the Logical Volume Manager". The installer asks if it can write out the choices made to the disk, and then enters the LVM setup screen, which begins with a summary explaining that you have one Free Physical Volume, and nothing more. ==Logical Volume creation== We now create a Volume Group (VG), which (in accordance to our partitioning standard) we'll call "system". In this VG, we'll add all Physical Volumes (being the one partition we've designated so in the previous step) using the space bar. To this end, in the volume group creation dialogue, we select that partition (''/dev/md2''). Note that all other selection choices are either unusable (unusable free space) or assigned to other purposes (/boot and /). Now we repeat the following process seven times: * select "Create Logical Volume" * select Volume Group "System" * give the LV Name (from the table, e.g. swap, var etc) * give the LV size (from the table, e.g. 1GB for swap etc) After this, we can select "Finish", the partitioner creates the seven LVs, and we're back at the partitioner screen, where there are now 7 extra "disks", with names such as ''LVM VG system, LV appslog - 3.0GB Linux device mapper (linear)''. Each of these "disks" has one block of empty space, which we now assign: seven times we repeat the following process: * select the unassigned chunk of empty space of an LV (e.g. ''appslog'') and press &lt;enter&gt;; * Change "Use as: do not use" into the desired filesystem (ext3 - only the LV "swap" gets as filesystem type "swap area"); * Change the mount point from "none" to the one corresponding with the name of the LV (note: the swap LV has no mountpoint; the appslog mountpoint must be entered manually as "/var/appslog" and varlog as "/var/log"); * If so desired, a label can be assigned to the partition (we usually don't); * select "Done setting up the partition". Note that sometimes, after creating and assigning the logical volumes, the installer has forgotten to mount the md0 and md1 partitions as /boot and /. In that case you'll have to reassign these partitions to these points in the filesystem. Once all this is done, we can look over the configuration once more, and then select "Finish partitioning and write changes to disk". A summary configuration screen will show, and we'll affirm with "yes" that these partitions can indeed be formatted. After some formatting screens flashing by (unless your partitions are particularly big, your system is particularly slow, or something goes wrong) the installation procedure continues. ==Final installer steps== Now the Debian installer loads a base system. Then it will ask you how it can contact the Debian archives, in the dialogue "configure the package manager". For the NetInstall version of Debian, this is as good as mandatory. So here, we say "yes, use a Network Mirror", and in the following list select the country in which we are (in our case: the Netherlands), so the installer can present us with a number of network mirrors "close by". We select ftp.nl.debian.org. Next screen: should you be behind a proxy server, then it's possible to specify that here. And then the test: the system will say "scanning the mirror..." and try to contact the specified mirror. If it does not succeed, then there is either a network problem, a problem with this box's network card, or you've not specified the mirror or proxy correctly - so fix it. You'll know the network mirror has succesfully been contacted when the next dialogue appears - currently "configuring popularity-contest". Answer this question as you please. And then one of the last "big" questions: Software Selection. In this dialogue, you can easily select bundles of software to be installed. The choices are currently: * Desktop environment * Web server * Print server * DNS server * File server * Mail server * SQL database * Laptop * Standard system (selected by default) We have to make a little confession here: we've never before used this option in the installer. In fact, we even deselect the Standard System, so as to minimize the number of software packages that the base installation of our server contains. This makes it more work to manually add packages later, but we feel it gives us more control and understanding of our systems. So if you are like us: deselect the Standard System entry, and select Continue. The next dialogue handles the installation of the [http://www.gnu.org/software/grub/ ''grub'' bootloader]. Unless your disks weren't empty and you're attempting to make this system multiboot, you'll most likely get a question if you'll allow the installer to install ''grub'' into the boot sector of the first hard disk. We'll confirm with "Yes". After the installation of grub is completed, the CD-ROM is ejected, and the system is ready to reboot into Debian Etch. Remove the CD and select "Continue" ==Finishing up the installation== The system should reboot into Debian. This means you should see the following boot sequence: * your machine's standard POST messages * then, a blue grub menu on a black screen, with two entries: ** Debian GNU/Linux, kernel 2.6.&lt;something&gt; ** Debian GNU/Linux, kernel 2.6.&lt;something&gt (single-user mode); * then, after a default time-out, the first grub option will go into effect, and the Linux kernel is started. Lots of cryptic messages in grey-on-black will scroll by, until the last few lines read: "Debian GNU/Linux 4.0 &lt;hostname&gt; tty1" and "&lt;hostname&gt; login:" If your system does not reach this login, and/or some horrible error messages appear anywhere in this boot sequence, then you've got some extra work ahead. For now we'll assume you've reached the login prompt without problem. Log in as the principal user (try to avoid logging in as root! That's BAD practice!). Once logged in, save a copy of the boot messages using ''sudo dmesg > boot.txt'' or whatever you like. Then look through the boot messages, e.g. with ''vi -R boot.txt''. Furthermore, [[APT_and_aptitude | use Aptitude]] to make sure ''all'' your software is updated to the latest version. Done! Your base system is ready. You probably now want to [[essential system software | install essential software]], [[roll your own kernel]] and [[connect your server to the Internet]]. Furthermore, you might want to create a couple of [[aliases in every profile]] so that your favorite commands are always available. 603597f8e1aa12fdf559d7e45624cc1ac6bb530b 2671 2670 2011-04-12T11:00:55Z Saruman! 2 finished base installer description wikitext text/x-wiki <big>'''Debian Squeeze Base Server setup'''</big> ==Getting the hardware== {| class="wikitable" border="1" |- |Note: in the following we're assuming you'll be assembling an x86 or x64 type of machine, as it has about the best price/performance ratio you could wish. Hardware costs for other platforms, e.g. IBM's Series p or HP 9000, can be much higher, while platforms like ARM are just not very powerful. Also, the availability of components and of help can be less than with the ubiquitous x86/x64 platforms. |} Naturally, before we can begin to install the operating system, we need to obtain the necessary hardware. Which hardware you require depends on what you want the server for; a testserver on which you will test only a single feature for a short while does not need the same quality of hardware as does a server that's supposed to act as a homeserver for many tasks for a long time. We'll assume your server will be like ours: a home server that must perform many tasks with sufficient performance for a few users, that's reliable and will last for a couple of years. So build or obtain a server with at least the following hardware: * a spacious casing with big, quiet cooling fans, like the [http://www.coolermaster.com/products/product.php?act=detail&id=317 one we have]; * an efficient, heavy-duty power supply that's rated high enough for your devices, and has a decent efficiency. For example, a [http://www.corsair.com/products/power_supplies.aspx Corsair HX520] power supply; * a server class motherboard, e.g. an [http://www.intel.com/products/server/index.htm?iid=home+hdr_nav2_server Intel] or [http://uk.asus.com/products.aspx?l1=9&l2=39&l3=263 AMD] based single-processor motherboard. DO NOT go for the cheapest motherboard you can find: if you pay peanuts, that's what you'll get. Server class motherboards have the quality, stability and durability you'll need from it, and usually also most of the needed peripherals, like multiple ethernet network cards on-board. Usually a Linux server does not require much in the way of video performance (and the screen will be used rarely, if ever), so any old integrated graphics will do. * a matching CPU - or multiple, if you think you need the power and the selected motherboard has the sockets. Furthermore, it pays to think about the energy use of your server CPU. For instance, you could choose an AMD Athlon X2 5600+, running at 2,8 Ghz and 89W maximum, but you can also go for an AMD Athlon X2 4850E, which is dualcore at 2,5GHz, but uses only 45W maximum - almost half of the former! And over a one year period, this choice can save up to 385 kWH. With electricity costing close to €0,25 per kWH (at least for some of us), that could save you €96,- a year. All I'm saying is: think about power use. * a CD-ROM- or DVD-player - although you might not need it any more after installation. Thus, you may opt to use an external USB DVD-player, if your system allows for booting from it. * ''multiple'' hard disks - you'll want redundancy, because every hard disk fails at some time. The drive with your data on it will fail fatally when it is most inconvenient to you, and any data on it that you consider valuable will likely be lost forever. To make Murphy's work somewhat harder for him, we're going to store our data redundantly, so that if any drive in the server fails, we'll not lose our data or our server. Thus, get yourself at least two hard disks for your operating system, at least 40GiB in size (don't think you'll be able to buy smaller ones nowadays), and spanking new (NEVER use old hard disks for your production server, new ones are just too cheap to run that risk!). You may also consider using 2.5" "notebook" hard disks, since they also consume less power than do 3.5" hard disks. * (multipe) network card(s) (NICs) if your motherboard does not have enough NICs integrated on-board. You'll want a NIC for your network, and another one for your Internet connection; and possible a third one for the wireless segment of your network. Now build a machine out of the above, or have someone build it for you. ==Preparation of the hardware== (Note: in the following we're again assuming you're running an x86/x64 type of machine. Hardware requirements and preparation for other platforms, e.g. IBM's Series p or HP 9000, can differ significantly) Next, check the assembled hardware: * is the configuration complete? If it does not have a CD/DVDplayer from which it can boot, then installing the software gets more difficult - at least get an USB external DVDdrive or something like that. * are all components connected properly (memory modules seated correctly in their sockets, AGP card inserted correctly into the AGP slot, et cetera) and are all cable connections made (multiple power cables to the motherboard, one power cable plus one data cable to each hard disk, etcetera)? Following this, you may hook up the machine. It's going to need power, and you will need at least a keyboard and a monitor attached. And if you want to use a Graphic User Interface to install, a mouse is required also. When you've ensured that everything is safe, you can turn on the machine, and continue to check it: * do all fans start to run when you turn on the machine? (if not, then '''quickly''' turn off your machine and correct the problem!) * does/do the hard disk(s) spin up? * do the power button and reset button operate correctly? * are the power led, HDD led and other display gadgetry functional? * when you let the machine power up, does it emit a single beep? And does it then show a Power-On Self Test screen (POST)? * Does it show the correct amount of memory in the POST screen? The correct number & speed of the CPU(s)? * Does the machine recognise all controller cards (SCSI, S-ATA etc)? And all attached DVD-drives and hard disks? * are all BIOSes/firmwares up to date? * If you have a hardware RAID controller, are your RAID arrays built already? * does the machine attempt to boot from at least the hard disk? ...et cetera. If there is any problem, or you want to update the BIOS or firmwares, it's best to do it before the operating system is installed. This Wiki, however, is not the place to get the information on how to accomplish these type of tasks. The last steps in the preparation of the hardware, are * to ensure that the machine can boot from CD/DVD, so that you can start installing Debian from it. It is possible to install Debian over the network, but that requires setting up a [http://www.debian-administration.org/articles/478 PXE Boot server] which is (currently) outside the scope of this wiki. * to connect the hardware to the Internet, so that it can get all required updates etcetera; please do ''not'' connect the box ''straight'' to the Internet, but make sure that it's safely behind a firewall, or failing that, a NAT router. By now the system should be almost ready to receive it's Operating System. But first we have an issue to tackle: that of redundancy. ==Software or hardware RAID== Your hard disks will fail. They absolutely will. It is never a question of "if", only of "when". So what will you do when the hard disk containing your complete operating system fails (besides pulling your hair out, that is)? What we propose is this: hard disks are pretty cheap nowadays, so let's use [http://en.wikipedia.org/wiki/Redundant_array_of_independent_disks RAID technology] to make our hard drive space resilient against failure of a whole drive. So first make sure that you have ''two'' disks of equal size instead of only one. Had you already been planning to use multiple disks already, then make sure you have at least ''one'' disk more than your space requirements prescribe; the space on that extra drive will provide the needed redundancy. Next, [[RAID fundamentals under Linux | click here]] to learn a bit more about RAID, to make the decision to use hardware-based and/or software-based RAID, and to plan your RAID arrays. In this example, we'll assume you're using hardware RAID on a RAID controller that's supported by the Debian installation software. This means that the installation software will "see" your RAID array(s) and present them as usable drives. ==Planning your network names== If your machine must become a part of an existing network, then it's almost certain that you already have a DNS domain in place; in that case: obtain the DNS suffix your machine will get (the DNS domain your machine will "belong" to). However, it's also possible that this machine is going to be the first machine in your new network, in which case the whole issue of DNS suffixes is wide open. If you need more information on DNS, go [[http://www.isc.org/sw/bind/arm95/Bv9ARM-all.html#id2564824 here]]. For now we'll assume you have (or will quickly obtain) a working knowledge of the DNS system. Here is our tip on choosing a DNS domain for your home network: * do '''not''' use a publicly registered domain name (e.g. "cocacola.com") for any machine that's not primarily intended to serve the public on the Internet; * for machines serving a private network, we urge you to use Top Level Domain name "lan" (to signify your machine is on a Local Area Network or LAN) * for the Domain Name itself, we suggest you use a level 2 name, like "saruman.lan", and not a level 3 name, like "mister.saruman.lan". This is only a short section on DNS, but remember that once a proper DNS system is in place, it's pretty much work to change it. At any rate, this section has most likely showed you that you need to put some thought into the DNS Domain Name design of your home network. OK, with this out of the way, we can get to installing the OS. ==Operating System installation== To install an Operating System (OS), it's kinda instrumental that you have one. Here, we're going to use [http://www.debian.org/intro/about Debian], the biggest [http://www.debian.org/intro/about#free Free] OS that we know of. Free stands for Freedom, but incidentally that Freedom also means it's gratis, an appealing aspect of Free. To get your own copy of Debian, go to their [http://www.debian.org/distrib/ download site] and obtain the latest [http://www.debian.org/releases/ Stable] image - in this wiki it's Debian 6.0, or "Squeeze" as it's also known. Besides the choice which release of Debian you want to run, you also have to know for which platform you're downloading (in our case: either ''amd64'' or ''i386'' depending on your hardware platform) and what kind of install you wish - if you have a working, fast Internet connection available at the time of install, then we recommend getting the [[http://www.debian.org/CD/netinst/ netinst] CD image; it's a relatively small CD, that'll be able to get you going, but gets most of the software you'll need straight from the 'net at install time. In the example at hand we're installing on an AMD Athlon x2-based server, on which we wish to install 64-bits software. We'll download [http://cdimage.debian.org/debian-cd/6.0.1a/amd64/iso-cd/debian-6.0.1a-amd64-CD-1.iso debian-6.0.1a-amd64-CD-1.iso], which is Squeeze after its first update. Burn this to a CD-recordable and boot your prepared hardware platform from this CD. After booting from the CD, a friendly graphic screen shows you the Installer boot menu. Your choices are * Install, the default non-graphical installation; * Graphical install, so you can click things; * Advanced options, where you can select expert options like the rescue mode; * Help; this drops you to a non-graphical screen where you can select help texts by using function keys. The screens explain how you can start the installation with extra parameters to instruct Debian to handle your hardware in a non-standard way, e.g. on an old machine with a problematic videocard you could run "install vga=771" (for some laptops) or "install vga=normal fb=false" (to disable the screen framebuffer). We're going to use the standard Command Line installation, so we choose "Install" and hit &lt;enter&gt;. {| class="wikitable" border="1" |- |We could easily use "Graphic install", in which case we'd have a nice fresh Graphical User Interface for our installation. ''We're'' not going to, because we're real men, and [http://isg.ee.ethz.ch/tools/realmen/ Real Men Don't Click]. Also, we've found that from the GUI it's hard to switch to a second console and then back. We could also go to the Advanced options, and opt for "Expert install" or "Graphical expert install" as installation method, because it gives a much finer grain of control; however we usually don't need that control, and can do without the barrage of extra questions that the "expert" installation method pose. |} After the Linux kernel finishes initializing the machine, a simple text-based installer appears that immediately starts asking questions. Answer them according to your needs. Our example system uses the following choices: * Language: English * country: other &gt; Europe &gt; Netherlands * locale (since there's no default locale for the combination Netherlands/English): United States - en_US.UTF-8 * keymap: American English (since we have a keyboard with US layout) Some installation software loads, and we get to the next phase: if you have multiple NICs in your machine (which we believe you ''should'' have!!), and if they're detected properly, then you're required to indicate which of the detected network interface cards (NIC) is going to be the "primary" NIC. {| class="wikitable" border="1" |- |Here, trouble could begin. If your machine has only network cards that are '''not''' supported, then you'll see '''no''' cards here - but then how are you going to do a NetInstall? A solution would be to (temporarily) install a NIC that ''is'' supported, like a cheap Realtek card, or an old 3Com 905 card. Then, when the whole system is installed, up and running, you could compile a new kernel that contains support for your actual NICs, and when these work, remove the temporary NIC. For now, we'll assume that at least one of your NICs is recognised properly by the Debian installation routine. |} Select the card that's connected and has (indirect) access to Internet (again: it should ''not'' be connected straight to the wild wild web, but sit safely behind a firewall, at least until we've installed our own firewall); if at all possible, let it be the NIC that'll be connected to your home network itself, on the ''inside'' of your server. Let's assume that this NIC is designated ''eth0'' by the Debian installation. This card will now be configured using DHCP, so if you're on a network with a DHCP-server, the network will work straight away. If it's not, you can either configure the network manually or fix your DHCP-server and connection between it and ''eth0''. Next is one of the hardest questions that any OS installation is going to ask you: what will be the host name of the system? You could easily change it at any time in the future, but possibly with lots of hassle, so you better choose wisely. Here are our tips: * do '''not''' name your machine after the user that's going to use it, e.g. "bernie-pc" (at some time in the future, Bernie's machine will be moved to Alice, so then Alice is working on "bernie-pc" which makes the situation quite unclear); * do '''not''' name your machine after the department or workgroup that's using it most, e.g. "accounting-srv" (same reasoning); * do '''not''' name your machine after it's main function, e.g. "printserver" (at some time in the future, the main function is moved to another machine, and/or an alternative function will become the main function of the machine); * do '''not''' name your machine after it's location, e.g. "srv-boston" (at some time in the future, the box will be moved to another location); * do '''not''' name your machine after it's hardware configuration, e.g. "ibmx346" (at some time in the future, either another xSeries x346 will be wheeled in, or the machine will be upgraded to accomodate increased use or overcome hardware problems - your "ibmx346" could suddenly be running on an xSeries x3650). What we feel are safe names for ''any'' machine in your network are true names, perhaps linked to a common theme: names of European cities, names of movie characters, names of countries or holiday destinations et cetera. Less imaginative would be coded names like "server0001". Immediately following comes the question of the Domain Name. This is about a DNS domain, so effectively the installation program is asking which DNS suffix the host name should have; if the DHCP-server already provided something it'll be suggested, but you can override it if need be. In the preparatory phase, you'll have decided on continuation of your current DNS schema, or starting a new one. Either way, put the chosen DNS suffix in and press &lt;enter&gt;. Next comes one '''VERY''' important question: what to use as root password? We cannot stress this enough: choose a SAFE password! Do NOT go for an easy-to-remember one, go for STRONG and SAFE. There are tools to help you generate strong passwords, like [http://www.pctools.com/guides/password/ this page]: use them! We strongly suggest 10 characters or more, including letters, mixed case, and numbers, so something like ''SuCRe4hecH'' (do NOT use this, generate your own!). Next, give the full name of the principal user of this server (your own, we assume), give the login-name (your given name, we assume), and a corresponding password. Again, use a SAFE password. As long as you don't make your principal user equivalent to root, you might go for a slightly weaker password (8 characters instead of 10), but we rather suggest you make the password just as strong (and different from!) the root password. After entering the details of these two users "root" and "you", we get to the server hardware. ==Partitioning== Now comes the question of partitioning, or how to divide the available disk space into chunks for the server to use. This is a tricky subject, because if you put all storage space into one partition, then some day a runaway process will fill up the entire disk with useless logs, and the system will crash. On the other hand, if you divvy up all space into little chunks, then some application is going to need space in one of those partitions where there is none, even though there may be plenty in other partitions. To minimize the chance of either problem occurring, we're going to use [http://tldp.org/HOWTO/LVM-HOWTO/whatisvolman.html Logical Volume Management (LVM2)] so that we can provision enough space to start our server, but keep some space in reserve to apply when needed, where it'll be needed. So, we at Saruman.biz have put together a recommended standard partitioning scheme. The basis (in accordance with the standard [[Debian directory structure]] is this: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Partition !style="background:#ffdead;"|MD !style="background:#ffdead;"|LVG !style="background:#ffdead;"|LV-name !style="background:#ffdead;"|Size <br> (physical machine) !style="background:#ffdead;"|Size (VM) !style="background:#ffdead;"|File System !style="background:#ffdead;"|Mount point |- | 1 | /dev/md0 | &nbsp; | &nbsp; | 100MiB | 100MiB | ext3 | /boot |- | 2 | /dev/md1 | &nbsp; | &nbsp; | 3GiB | 1GiB | ext3 | / |- | rowspan="8" valign="top" | 3 | rowspan="8" valign="top" | /dev/md2 | rowspan="8" valign="top" style="background:lightgrey"| system | style="background:lightgrey" | swap | 1GiB<ref name="swap">Rule of thumb: twice the size of the machine's RAM, but no less than 256MiB and no more than 2GiB</ref> | 256MiB<ref name="swap"/> | swap | &nbsp; |- | style="background:lightgrey" | var | 1GiB | 512MiB | ext3 | /var |- | style="background:lightgrey" | varlog | 1GiB | 512MiB | ext3 | /var/log |- | style="background:lightgrey" | appslog | 3GiB | -<ref>Yes, we think a separate ''appslog'' is a very good idea, but when creating a minimal VM, we have to save disk space ''somewhere''...</ref> | ext3 | /var/appslog |- | style="background:lightgrey" | home | 1GiB<ref name="home">Note that this heavily depends on the purpose of the machine; if it is not to house any users, then (almost) no space is needed for /home. But on the other hand if e.g. a virtual user is to be used for keeping mailstores, or other service users need home space, then /home needs to be big enough for that.</ref> | 512MiB<ref name="home"/> | ext3 | /home |- | style="background:lightgrey" | usr | 3GiB | 3GiB | ext3 | /usr |- | style="background:lightgrey" | tmp | 1GiB | 512MiB | ext3 | /tmp |- | style="background:lightgrey" | opt | 1GiB | - | ext3 | /opt |- ! colspan="4" style="text-align:right"| Total ! 18.1GiB ! 6.9GiB ! colspan="2" | |- |} As you can see, the partition table works as follows: we assume that we wind up with 3 partitions, either on three separate software RAID arrays (''md0'' through ''md2'') or on one single hardware RAID array (in which case the 2nd column ''MD'' does not apply). The size of the partitions depends on your machine's make: for standard physical machines the 5th column does sensible suggestions, even though you could choose to have different sizes and of course different divisions altogether. If your machine happens to be a virtual one, running inside a [http://www.vmware.com/products/server/ VMware Server] or [http://www.vmware.com/products/vi/esx/ VMware ESX host], or the like, then you might want to start out with more modest partitions. The same holds for small servers that must run off Flash drives. Anyways, we're now at the Debian installation screen that lets us partition our disks. We're ''not'' going to use any of the "guided" partitioning options, we go for "manual". Choosing that brings us to a screen showing all drives that the installation routine has detected, and all partitions on those drives that the installer can "see". We're going to do some assuming here once more: let's assume the drive(s) on which you want to install are visible, and are empty (containing no other partitions). <references/> ===Software RAID partitioning=== If you're to use software RAID, you now have to select the free space on the first drive, press &lt;enter&gt;, and then tell what you want to do with the free space: create a new partition, tell which size you want it to be (see table above), give the type of partition (primary), and give where on the disk it'll sit (the beginning). Next, a screen comes up that details how the partition you're requesting will be created. Here we make some changes: under "use as" we're going to select "physical volume for RAID". This clears all the other options in this screen, except for the "bootable" flag, which must be "on" for the first partition that we'll mount as ''/boot''. Now select "Done setting up the partition". Next, go to the free space on the second disk, and do ''exactly'' the same, to create an identical physical volume for RAID - if it's the first partition, select the "bootable" flag as well (we'll want to be able to boot from this second disk if the first disk fails, right?). Then go back to the rest of the free space on the first disk, make the second physical volume for RAID, duplicate it on the second disk. Then, go back to the rest of the free space on the first disk, make the third physical volume for RAID, and again duplicate it on the second disk. If you now go back to the "partition disks" overview, you'll see all the partitions you've specified listed on their respective disks. But at the top an extra option has appeared, called "configure software RAID". When you now select this option, the installer will ask if it may write the changes you've made to disk. This actually creates the partition tables on the disks. Now you can create RAID devices. The RAID levels that Debian 6.0 offer are 0 (striping), 1 (mirroring), 5 (distributed redundancy), 6 (double distributed redundancy) ant 10 (striped mirrors). For your operating system disk pair, level 1 is the only sane choice. When selecting RAID 1, the installer asks how many active devices to use (2), how many spares (0), and then offers a selection screen where you can mark all members of the array. Select the first partition of both disks (presumably ''/dev/sda1'' and ''/dev/sdb1'') which should correspond to the 100MiB partitions you've created. Then create the other MD devices. Finally, choose &lt;finish&gt;. You'll drop back to the partitioner, but now the three created devices are available in the partitioner as "RAID1 device #0" etc. ===Hardware RAID partitioning=== Now, if you have hardware RAID, then on your first (boot) disk just make 3 partitions, in the following manner: Select the free space on the intended boot disk, press &lt;enter&gt;, select "create a new partition", and fill out the desired size (100MB). Type is primary, location is beginning of the disk, and in the details of the partition, we only need to change the Mount point to "/boot", and set the Bootable flag to "On". Then we're "Done setting up this partition". The second partition is made the same way, but the desired size is 3GB, the Mount point is "/", and the Bootable flag remains off. Again, we're "Done setting up this partition". The third partition is again a primary partition, it takes up the entire rest of the disk, but the type is not ext3, but "physical volume for LVM". Again, we're "Done setting up this partition". But now from the main partitioner screen, we can access "Configure the Logical Volume Manager". The installer asks if it can write out the choices made to the disk, and then enters the LVM setup screen, which begins with a summary explaining that you have one Free Physical Volume, and nothing more. ==Logical Volume creation== We now create a Volume Group (VG), which (in accordance to our partitioning standard) we'll call "system". In this VG, we'll add all Physical Volumes (being the one partition we've designated so in the previous step) using the space bar. To this end, in the volume group creation dialogue, we select that partition (''/dev/md2''). Note that all other selection choices are either unusable (unusable free space) or assigned to other purposes (/boot and /). Now we repeat the following process seven times: * select "Create Logical Volume" * select Volume Group "System" * give the LV Name (from the table, e.g. swap, var etc) * give the LV size (from the table, e.g. 1GB for swap etc) After this, we can select "Finish", the partitioner creates the seven LVs, and we're back at the partitioner screen, where there are now 7 extra "disks", with names such as ''LVM VG system, LV appslog - 3.0GB Linux device mapper (linear)''. Each of these "disks" has one block of empty space, which we now assign: seven times we repeat the following process: * select the unassigned chunk of empty space of an LV (e.g. ''appslog'') and press &lt;enter&gt;; * Change "Use as: do not use" into the desired filesystem (ext3 - only the LV "swap" gets as filesystem type "swap area"); * Change the mount point from "none" to the one corresponding with the name of the LV (note: the swap LV has no mountpoint; the appslog mountpoint must be entered manually as "/var/appslog" and varlog as "/var/log"); * If so desired, a label can be assigned to the partition (we usually don't); * select "Done setting up the partition". Note that sometimes, after creating and assigning the logical volumes, the installer has forgotten to mount the md0 and md1 partitions as /boot and /. In that case you'll have to reassign these partitions to these points in the filesystem. Once all this is done, we can look over the configuration once more, and then select "Finish partitioning and write changes to disk". A summary configuration screen will show, and we'll affirm with "yes" that these partitions can indeed be formatted. After some formatting screens flashing by (unless your partitions are particularly big, your system is particularly slow, or something goes wrong) the installation procedure continues. ==Base system setup== Now the Debian installer loads a base system. It will scan your installation CD/DVD, and ask if it should scan more CD/DVDs. We're going with "no" here. Then it will ask you how it can contact the Debian archives, in the dialogue "configure the package manager". For the NetInstall version of Debian, this is as good as mandatory. So here, we say "yes, use a Network Mirror", and in the following list select the country in which we are (in our case: the Netherlands), so the installer can present us with a number of network mirrors "close by". We select ftp.nl.debian.org. Next screen: should you be behind a proxy server, then it's possible to specify that here. And then the test: the system will say "scanning the mirror..." and try to contact the specified mirror. If it does not succeed, then there is either a network problem, a problem with this box's network card, or you've not specified the mirror or proxy correctly - so fix it. You'll know the network mirror has successfully been contacted when it's saying "Retrieving file 1 of 5". A number of files are retrieved, and the base system is set up. Somewhere early in this setup, the next dialogue appears - currently "configuring popularity-contest". Answer this question as you please. And then one of the last "big" questions: Software Selection. In this dialogue, you can easily select bundles of software to be installed. The choices are currently: * Graphical desktop environment * Web server * Print server * DNS server * File server * Mail server * SQL database * SSH server * Laptop * Standard system utilities (selected by default) We have to make a little confession here: we've never before used this option in the installer. In fact, we even deselect the Standard System, so as to minimize the number of software packages that the base installation of our server contains. This makes it more work to manually add packages later, but we feel it gives us more control and understanding of our systems. So if you're like us: deselect the "Standard system utilities" entry, and select Continue. The next dialogue handles the installation of the [http://www.gnu.org/software/grub/ ''grub'' bootloader]. Unless your disks weren't empty and you're attempting to make this system multiboot, you'll most likely get a question if you'll allow the installer to install ''grub'' into the boot sector of the first hard disk. We'll confirm with "Yes". After the installation of grub is completed, the CD-ROM is ejected, and the system is ready to reboot into Debian Squeeze. Remove the CD and select "Continue" ==Finishing up the installation== The system should reboot into Debian. This means you should see the following boot sequence: * your machine's standard POST messages * then, a blue grub menu on a black screen, with two entries: ** Debian GNU/Linux, kernel 2.6.&lt;something&gt; ** Debian GNU/Linux, kernel 2.6.&lt;something&gt (single-user mode); * then, after a default time-out, the first grub option will go into effect, and the Linux kernel is started. Lots of cryptic messages in grey-on-black will scroll by, until the last few lines read: "Debian GNU/Linux 4.0 &lt;hostname&gt; tty1" and "&lt;hostname&gt; login:" If your system does not reach this login, and/or some horrible error messages appear anywhere in this boot sequence, then you've got some extra work ahead. For now we'll assume you've reached the login prompt without problem. Log in as the principal user (try to avoid logging in as root! That's BAD practice!). Once logged in, save a copy of the boot messages using ''sudo dmesg > boot.txt'' or whatever you like. Then look through the boot messages, e.g. with ''vi -R boot.txt''. Furthermore, [[APT_and_aptitude | use Aptitude]] to make sure ''all'' your software is updated to the latest version. Done! Your base system is ready. You probably now want to [[essential system software | install essential software]], [[roll your own kernel]] and [[connect your server to the Internet]]. Furthermore, you might want to create a couple of [[aliases in every profile]] so that your favorite commands are always available. e9359bade836e91bc7f0d82a73118925aa0a965f 2672 2671 2011-04-12T11:08:27Z Saruman! 2 /* Finishing up the installation */ messages for squeeze wikitext text/x-wiki <big>'''Debian Squeeze Base Server setup'''</big> ==Getting the hardware== {| class="wikitable" border="1" |- |Note: in the following we're assuming you'll be assembling an x86 or x64 type of machine, as it has about the best price/performance ratio you could wish. Hardware costs for other platforms, e.g. IBM's Series p or HP 9000, can be much higher, while platforms like ARM are just not very powerful. Also, the availability of components and of help can be less than with the ubiquitous x86/x64 platforms. |} Naturally, before we can begin to install the operating system, we need to obtain the necessary hardware. Which hardware you require depends on what you want the server for; a testserver on which you will test only a single feature for a short while does not need the same quality of hardware as does a server that's supposed to act as a homeserver for many tasks for a long time. We'll assume your server will be like ours: a home server that must perform many tasks with sufficient performance for a few users, that's reliable and will last for a couple of years. So build or obtain a server with at least the following hardware: * a spacious casing with big, quiet cooling fans, like the [http://www.coolermaster.com/products/product.php?act=detail&id=317 one we have]; * an efficient, heavy-duty power supply that's rated high enough for your devices, and has a decent efficiency. For example, a [http://www.corsair.com/products/power_supplies.aspx Corsair HX520] power supply; * a server class motherboard, e.g. an [http://www.intel.com/products/server/index.htm?iid=home+hdr_nav2_server Intel] or [http://uk.asus.com/products.aspx?l1=9&l2=39&l3=263 AMD] based single-processor motherboard. DO NOT go for the cheapest motherboard you can find: if you pay peanuts, that's what you'll get. Server class motherboards have the quality, stability and durability you'll need from it, and usually also most of the needed peripherals, like multiple ethernet network cards on-board. Usually a Linux server does not require much in the way of video performance (and the screen will be used rarely, if ever), so any old integrated graphics will do. * a matching CPU - or multiple, if you think you need the power and the selected motherboard has the sockets. Furthermore, it pays to think about the energy use of your server CPU. For instance, you could choose an AMD Athlon X2 5600+, running at 2,8 Ghz and 89W maximum, but you can also go for an AMD Athlon X2 4850E, which is dualcore at 2,5GHz, but uses only 45W maximum - almost half of the former! And over a one year period, this choice can save up to 385 kWH. With electricity costing close to €0,25 per kWH (at least for some of us), that could save you €96,- a year. All I'm saying is: think about power use. * a CD-ROM- or DVD-player - although you might not need it any more after installation. Thus, you may opt to use an external USB DVD-player, if your system allows for booting from it. * ''multiple'' hard disks - you'll want redundancy, because every hard disk fails at some time. The drive with your data on it will fail fatally when it is most inconvenient to you, and any data on it that you consider valuable will likely be lost forever. To make Murphy's work somewhat harder for him, we're going to store our data redundantly, so that if any drive in the server fails, we'll not lose our data or our server. Thus, get yourself at least two hard disks for your operating system, at least 40GiB in size (don't think you'll be able to buy smaller ones nowadays), and spanking new (NEVER use old hard disks for your production server, new ones are just too cheap to run that risk!). You may also consider using 2.5" "notebook" hard disks, since they also consume less power than do 3.5" hard disks. * (multipe) network card(s) (NICs) if your motherboard does not have enough NICs integrated on-board. You'll want a NIC for your network, and another one for your Internet connection; and possible a third one for the wireless segment of your network. Now build a machine out of the above, or have someone build it for you. ==Preparation of the hardware== (Note: in the following we're again assuming you're running an x86/x64 type of machine. Hardware requirements and preparation for other platforms, e.g. IBM's Series p or HP 9000, can differ significantly) Next, check the assembled hardware: * is the configuration complete? If it does not have a CD/DVDplayer from which it can boot, then installing the software gets more difficult - at least get an USB external DVDdrive or something like that. * are all components connected properly (memory modules seated correctly in their sockets, AGP card inserted correctly into the AGP slot, et cetera) and are all cable connections made (multiple power cables to the motherboard, one power cable plus one data cable to each hard disk, etcetera)? Following this, you may hook up the machine. It's going to need power, and you will need at least a keyboard and a monitor attached. And if you want to use a Graphic User Interface to install, a mouse is required also. When you've ensured that everything is safe, you can turn on the machine, and continue to check it: * do all fans start to run when you turn on the machine? (if not, then '''quickly''' turn off your machine and correct the problem!) * does/do the hard disk(s) spin up? * do the power button and reset button operate correctly? * are the power led, HDD led and other display gadgetry functional? * when you let the machine power up, does it emit a single beep? And does it then show a Power-On Self Test screen (POST)? * Does it show the correct amount of memory in the POST screen? The correct number & speed of the CPU(s)? * Does the machine recognise all controller cards (SCSI, S-ATA etc)? And all attached DVD-drives and hard disks? * are all BIOSes/firmwares up to date? * If you have a hardware RAID controller, are your RAID arrays built already? * does the machine attempt to boot from at least the hard disk? ...et cetera. If there is any problem, or you want to update the BIOS or firmwares, it's best to do it before the operating system is installed. This Wiki, however, is not the place to get the information on how to accomplish these type of tasks. The last steps in the preparation of the hardware, are * to ensure that the machine can boot from CD/DVD, so that you can start installing Debian from it. It is possible to install Debian over the network, but that requires setting up a [http://www.debian-administration.org/articles/478 PXE Boot server] which is (currently) outside the scope of this wiki. * to connect the hardware to the Internet, so that it can get all required updates etcetera; please do ''not'' connect the box ''straight'' to the Internet, but make sure that it's safely behind a firewall, or failing that, a NAT router. By now the system should be almost ready to receive it's Operating System. But first we have an issue to tackle: that of redundancy. ==Software or hardware RAID== Your hard disks will fail. They absolutely will. It is never a question of "if", only of "when". So what will you do when the hard disk containing your complete operating system fails (besides pulling your hair out, that is)? What we propose is this: hard disks are pretty cheap nowadays, so let's use [http://en.wikipedia.org/wiki/Redundant_array_of_independent_disks RAID technology] to make our hard drive space resilient against failure of a whole drive. So first make sure that you have ''two'' disks of equal size instead of only one. Had you already been planning to use multiple disks already, then make sure you have at least ''one'' disk more than your space requirements prescribe; the space on that extra drive will provide the needed redundancy. Next, [[RAID fundamentals under Linux | click here]] to learn a bit more about RAID, to make the decision to use hardware-based and/or software-based RAID, and to plan your RAID arrays. In this example, we'll assume you're using hardware RAID on a RAID controller that's supported by the Debian installation software. This means that the installation software will "see" your RAID array(s) and present them as usable drives. ==Planning your network names== If your machine must become a part of an existing network, then it's almost certain that you already have a DNS domain in place; in that case: obtain the DNS suffix your machine will get (the DNS domain your machine will "belong" to). However, it's also possible that this machine is going to be the first machine in your new network, in which case the whole issue of DNS suffixes is wide open. If you need more information on DNS, go [[http://www.isc.org/sw/bind/arm95/Bv9ARM-all.html#id2564824 here]]. For now we'll assume you have (or will quickly obtain) a working knowledge of the DNS system. Here is our tip on choosing a DNS domain for your home network: * do '''not''' use a publicly registered domain name (e.g. "cocacola.com") for any machine that's not primarily intended to serve the public on the Internet; * for machines serving a private network, we urge you to use Top Level Domain name "lan" (to signify your machine is on a Local Area Network or LAN) * for the Domain Name itself, we suggest you use a level 2 name, like "saruman.lan", and not a level 3 name, like "mister.saruman.lan". This is only a short section on DNS, but remember that once a proper DNS system is in place, it's pretty much work to change it. At any rate, this section has most likely showed you that you need to put some thought into the DNS Domain Name design of your home network. OK, with this out of the way, we can get to installing the OS. ==Operating System installation== To install an Operating System (OS), it's kinda instrumental that you have one. Here, we're going to use [http://www.debian.org/intro/about Debian], the biggest [http://www.debian.org/intro/about#free Free] OS that we know of. Free stands for Freedom, but incidentally that Freedom also means it's gratis, an appealing aspect of Free. To get your own copy of Debian, go to their [http://www.debian.org/distrib/ download site] and obtain the latest [http://www.debian.org/releases/ Stable] image - in this wiki it's Debian 6.0, or "Squeeze" as it's also known. Besides the choice which release of Debian you want to run, you also have to know for which platform you're downloading (in our case: either ''amd64'' or ''i386'' depending on your hardware platform) and what kind of install you wish - if you have a working, fast Internet connection available at the time of install, then we recommend getting the [[http://www.debian.org/CD/netinst/ netinst] CD image; it's a relatively small CD, that'll be able to get you going, but gets most of the software you'll need straight from the 'net at install time. In the example at hand we're installing on an AMD Athlon x2-based server, on which we wish to install 64-bits software. We'll download [http://cdimage.debian.org/debian-cd/6.0.1a/amd64/iso-cd/debian-6.0.1a-amd64-CD-1.iso debian-6.0.1a-amd64-CD-1.iso], which is Squeeze after its first update. Burn this to a CD-recordable and boot your prepared hardware platform from this CD. After booting from the CD, a friendly graphic screen shows you the Installer boot menu. Your choices are * Install, the default non-graphical installation; * Graphical install, so you can click things; * Advanced options, where you can select expert options like the rescue mode; * Help; this drops you to a non-graphical screen where you can select help texts by using function keys. The screens explain how you can start the installation with extra parameters to instruct Debian to handle your hardware in a non-standard way, e.g. on an old machine with a problematic videocard you could run "install vga=771" (for some laptops) or "install vga=normal fb=false" (to disable the screen framebuffer). We're going to use the standard Command Line installation, so we choose "Install" and hit &lt;enter&gt;. {| class="wikitable" border="1" |- |We could easily use "Graphic install", in which case we'd have a nice fresh Graphical User Interface for our installation. ''We're'' not going to, because we're real men, and [http://isg.ee.ethz.ch/tools/realmen/ Real Men Don't Click]. Also, we've found that from the GUI it's hard to switch to a second console and then back. We could also go to the Advanced options, and opt for "Expert install" or "Graphical expert install" as installation method, because it gives a much finer grain of control; however we usually don't need that control, and can do without the barrage of extra questions that the "expert" installation method pose. |} After the Linux kernel finishes initializing the machine, a simple text-based installer appears that immediately starts asking questions. Answer them according to your needs. Our example system uses the following choices: * Language: English * country: other &gt; Europe &gt; Netherlands * locale (since there's no default locale for the combination Netherlands/English): United States - en_US.UTF-8 * keymap: American English (since we have a keyboard with US layout) Some installation software loads, and we get to the next phase: if you have multiple NICs in your machine (which we believe you ''should'' have!!), and if they're detected properly, then you're required to indicate which of the detected network interface cards (NIC) is going to be the "primary" NIC. {| class="wikitable" border="1" |- |Here, trouble could begin. If your machine has only network cards that are '''not''' supported, then you'll see '''no''' cards here - but then how are you going to do a NetInstall? A solution would be to (temporarily) install a NIC that ''is'' supported, like a cheap Realtek card, or an old 3Com 905 card. Then, when the whole system is installed, up and running, you could compile a new kernel that contains support for your actual NICs, and when these work, remove the temporary NIC. For now, we'll assume that at least one of your NICs is recognised properly by the Debian installation routine. |} Select the card that's connected and has (indirect) access to Internet (again: it should ''not'' be connected straight to the wild wild web, but sit safely behind a firewall, at least until we've installed our own firewall); if at all possible, let it be the NIC that'll be connected to your home network itself, on the ''inside'' of your server. Let's assume that this NIC is designated ''eth0'' by the Debian installation. This card will now be configured using DHCP, so if you're on a network with a DHCP-server, the network will work straight away. If it's not, you can either configure the network manually or fix your DHCP-server and connection between it and ''eth0''. Next is one of the hardest questions that any OS installation is going to ask you: what will be the host name of the system? You could easily change it at any time in the future, but possibly with lots of hassle, so you better choose wisely. Here are our tips: * do '''not''' name your machine after the user that's going to use it, e.g. "bernie-pc" (at some time in the future, Bernie's machine will be moved to Alice, so then Alice is working on "bernie-pc" which makes the situation quite unclear); * do '''not''' name your machine after the department or workgroup that's using it most, e.g. "accounting-srv" (same reasoning); * do '''not''' name your machine after it's main function, e.g. "printserver" (at some time in the future, the main function is moved to another machine, and/or an alternative function will become the main function of the machine); * do '''not''' name your machine after it's location, e.g. "srv-boston" (at some time in the future, the box will be moved to another location); * do '''not''' name your machine after it's hardware configuration, e.g. "ibmx346" (at some time in the future, either another xSeries x346 will be wheeled in, or the machine will be upgraded to accomodate increased use or overcome hardware problems - your "ibmx346" could suddenly be running on an xSeries x3650). What we feel are safe names for ''any'' machine in your network are true names, perhaps linked to a common theme: names of European cities, names of movie characters, names of countries or holiday destinations et cetera. Less imaginative would be coded names like "server0001". Immediately following comes the question of the Domain Name. This is about a DNS domain, so effectively the installation program is asking which DNS suffix the host name should have; if the DHCP-server already provided something it'll be suggested, but you can override it if need be. In the preparatory phase, you'll have decided on continuation of your current DNS schema, or starting a new one. Either way, put the chosen DNS suffix in and press &lt;enter&gt;. Next comes one '''VERY''' important question: what to use as root password? We cannot stress this enough: choose a SAFE password! Do NOT go for an easy-to-remember one, go for STRONG and SAFE. There are tools to help you generate strong passwords, like [http://www.pctools.com/guides/password/ this page]: use them! We strongly suggest 10 characters or more, including letters, mixed case, and numbers, so something like ''SuCRe4hecH'' (do NOT use this, generate your own!). Next, give the full name of the principal user of this server (your own, we assume), give the login-name (your given name, we assume), and a corresponding password. Again, use a SAFE password. As long as you don't make your principal user equivalent to root, you might go for a slightly weaker password (8 characters instead of 10), but we rather suggest you make the password just as strong (and different from!) the root password. After entering the details of these two users "root" and "you", we get to the server hardware. ==Partitioning== Now comes the question of partitioning, or how to divide the available disk space into chunks for the server to use. This is a tricky subject, because if you put all storage space into one partition, then some day a runaway process will fill up the entire disk with useless logs, and the system will crash. On the other hand, if you divvy up all space into little chunks, then some application is going to need space in one of those partitions where there is none, even though there may be plenty in other partitions. To minimize the chance of either problem occurring, we're going to use [http://tldp.org/HOWTO/LVM-HOWTO/whatisvolman.html Logical Volume Management (LVM2)] so that we can provision enough space to start our server, but keep some space in reserve to apply when needed, where it'll be needed. So, we at Saruman.biz have put together a recommended standard partitioning scheme. The basis (in accordance with the standard [[Debian directory structure]] is this: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Partition !style="background:#ffdead;"|MD !style="background:#ffdead;"|LVG !style="background:#ffdead;"|LV-name !style="background:#ffdead;"|Size <br> (physical machine) !style="background:#ffdead;"|Size (VM) !style="background:#ffdead;"|File System !style="background:#ffdead;"|Mount point |- | 1 | /dev/md0 | &nbsp; | &nbsp; | 100MiB | 100MiB | ext3 | /boot |- | 2 | /dev/md1 | &nbsp; | &nbsp; | 3GiB | 1GiB | ext3 | / |- | rowspan="8" valign="top" | 3 | rowspan="8" valign="top" | /dev/md2 | rowspan="8" valign="top" style="background:lightgrey"| system | style="background:lightgrey" | swap | 1GiB<ref name="swap">Rule of thumb: twice the size of the machine's RAM, but no less than 256MiB and no more than 2GiB</ref> | 256MiB<ref name="swap"/> | swap | &nbsp; |- | style="background:lightgrey" | var | 1GiB | 512MiB | ext3 | /var |- | style="background:lightgrey" | varlog | 1GiB | 512MiB | ext3 | /var/log |- | style="background:lightgrey" | appslog | 3GiB | -<ref>Yes, we think a separate ''appslog'' is a very good idea, but when creating a minimal VM, we have to save disk space ''somewhere''...</ref> | ext3 | /var/appslog |- | style="background:lightgrey" | home | 1GiB<ref name="home">Note that this heavily depends on the purpose of the machine; if it is not to house any users, then (almost) no space is needed for /home. But on the other hand if e.g. a virtual user is to be used for keeping mailstores, or other service users need home space, then /home needs to be big enough for that.</ref> | 512MiB<ref name="home"/> | ext3 | /home |- | style="background:lightgrey" | usr | 3GiB | 3GiB | ext3 | /usr |- | style="background:lightgrey" | tmp | 1GiB | 512MiB | ext3 | /tmp |- | style="background:lightgrey" | opt | 1GiB | - | ext3 | /opt |- ! colspan="4" style="text-align:right"| Total ! 18.1GiB ! 6.9GiB ! colspan="2" | |- |} As you can see, the partition table works as follows: we assume that we wind up with 3 partitions, either on three separate software RAID arrays (''md0'' through ''md2'') or on one single hardware RAID array (in which case the 2nd column ''MD'' does not apply). The size of the partitions depends on your machine's make: for standard physical machines the 5th column does sensible suggestions, even though you could choose to have different sizes and of course different divisions altogether. If your machine happens to be a virtual one, running inside a [http://www.vmware.com/products/server/ VMware Server] or [http://www.vmware.com/products/vi/esx/ VMware ESX host], or the like, then you might want to start out with more modest partitions. The same holds for small servers that must run off Flash drives. Anyways, we're now at the Debian installation screen that lets us partition our disks. We're ''not'' going to use any of the "guided" partitioning options, we go for "manual". Choosing that brings us to a screen showing all drives that the installation routine has detected, and all partitions on those drives that the installer can "see". We're going to do some assuming here once more: let's assume the drive(s) on which you want to install are visible, and are empty (containing no other partitions). <references/> ===Software RAID partitioning=== If you're to use software RAID, you now have to select the free space on the first drive, press &lt;enter&gt;, and then tell what you want to do with the free space: create a new partition, tell which size you want it to be (see table above), give the type of partition (primary), and give where on the disk it'll sit (the beginning). Next, a screen comes up that details how the partition you're requesting will be created. Here we make some changes: under "use as" we're going to select "physical volume for RAID". This clears all the other options in this screen, except for the "bootable" flag, which must be "on" for the first partition that we'll mount as ''/boot''. Now select "Done setting up the partition". Next, go to the free space on the second disk, and do ''exactly'' the same, to create an identical physical volume for RAID - if it's the first partition, select the "bootable" flag as well (we'll want to be able to boot from this second disk if the first disk fails, right?). Then go back to the rest of the free space on the first disk, make the second physical volume for RAID, duplicate it on the second disk. Then, go back to the rest of the free space on the first disk, make the third physical volume for RAID, and again duplicate it on the second disk. If you now go back to the "partition disks" overview, you'll see all the partitions you've specified listed on their respective disks. But at the top an extra option has appeared, called "configure software RAID". When you now select this option, the installer will ask if it may write the changes you've made to disk. This actually creates the partition tables on the disks. Now you can create RAID devices. The RAID levels that Debian 6.0 offer are 0 (striping), 1 (mirroring), 5 (distributed redundancy), 6 (double distributed redundancy) ant 10 (striped mirrors). For your operating system disk pair, level 1 is the only sane choice. When selecting RAID 1, the installer asks how many active devices to use (2), how many spares (0), and then offers a selection screen where you can mark all members of the array. Select the first partition of both disks (presumably ''/dev/sda1'' and ''/dev/sdb1'') which should correspond to the 100MiB partitions you've created. Then create the other MD devices. Finally, choose &lt;finish&gt;. You'll drop back to the partitioner, but now the three created devices are available in the partitioner as "RAID1 device #0" etc. ===Hardware RAID partitioning=== Now, if you have hardware RAID, then on your first (boot) disk just make 3 partitions, in the following manner: Select the free space on the intended boot disk, press &lt;enter&gt;, select "create a new partition", and fill out the desired size (100MB). Type is primary, location is beginning of the disk, and in the details of the partition, we only need to change the Mount point to "/boot", and set the Bootable flag to "On". Then we're "Done setting up this partition". The second partition is made the same way, but the desired size is 3GB, the Mount point is "/", and the Bootable flag remains off. Again, we're "Done setting up this partition". The third partition is again a primary partition, it takes up the entire rest of the disk, but the type is not ext3, but "physical volume for LVM". Again, we're "Done setting up this partition". But now from the main partitioner screen, we can access "Configure the Logical Volume Manager". The installer asks if it can write out the choices made to the disk, and then enters the LVM setup screen, which begins with a summary explaining that you have one Free Physical Volume, and nothing more. ==Logical Volume creation== We now create a Volume Group (VG), which (in accordance to our partitioning standard) we'll call "system". In this VG, we'll add all Physical Volumes (being the one partition we've designated so in the previous step) using the space bar. To this end, in the volume group creation dialogue, we select that partition (''/dev/md2''). Note that all other selection choices are either unusable (unusable free space) or assigned to other purposes (/boot and /). Now we repeat the following process seven times: * select "Create Logical Volume" * select Volume Group "System" * give the LV Name (from the table, e.g. swap, var etc) * give the LV size (from the table, e.g. 1GB for swap etc) After this, we can select "Finish", the partitioner creates the seven LVs, and we're back at the partitioner screen, where there are now 7 extra "disks", with names such as ''LVM VG system, LV appslog - 3.0GB Linux device mapper (linear)''. Each of these "disks" has one block of empty space, which we now assign: seven times we repeat the following process: * select the unassigned chunk of empty space of an LV (e.g. ''appslog'') and press &lt;enter&gt;; * Change "Use as: do not use" into the desired filesystem (ext3 - only the LV "swap" gets as filesystem type "swap area"); * Change the mount point from "none" to the one corresponding with the name of the LV (note: the swap LV has no mountpoint; the appslog mountpoint must be entered manually as "/var/appslog" and varlog as "/var/log"); * If so desired, a label can be assigned to the partition (we usually don't); * select "Done setting up the partition". Note that sometimes, after creating and assigning the logical volumes, the installer has forgotten to mount the md0 and md1 partitions as /boot and /. In that case you'll have to reassign these partitions to these points in the filesystem. Once all this is done, we can look over the configuration once more, and then select "Finish partitioning and write changes to disk". A summary configuration screen will show, and we'll affirm with "yes" that these partitions can indeed be formatted. After some formatting screens flashing by (unless your partitions are particularly big, your system is particularly slow, or something goes wrong) the installation procedure continues. ==Base system setup== Now the Debian installer loads a base system. It will scan your installation CD/DVD, and ask if it should scan more CD/DVDs. We're going with "no" here. Then it will ask you how it can contact the Debian archives, in the dialogue "configure the package manager". For the NetInstall version of Debian, this is as good as mandatory. So here, we say "yes, use a Network Mirror", and in the following list select the country in which we are (in our case: the Netherlands), so the installer can present us with a number of network mirrors "close by". We select ftp.nl.debian.org. Next screen: should you be behind a proxy server, then it's possible to specify that here. And then the test: the system will say "scanning the mirror..." and try to contact the specified mirror. If it does not succeed, then there is either a network problem, a problem with this box's network card, or you've not specified the mirror or proxy correctly - so fix it. You'll know the network mirror has successfully been contacted when it's saying "Retrieving file 1 of 5". A number of files are retrieved, and the base system is set up. Somewhere early in this setup, the next dialogue appears - currently "configuring popularity-contest". Answer this question as you please. And then one of the last "big" questions: Software Selection. In this dialogue, you can easily select bundles of software to be installed. The choices are currently: * Graphical desktop environment * Web server * Print server * DNS server * File server * Mail server * SQL database * SSH server * Laptop * Standard system utilities (selected by default) We have to make a little confession here: we've never before used this option in the installer. In fact, we even deselect the Standard System, so as to minimize the number of software packages that the base installation of our server contains. This makes it more work to manually add packages later, but we feel it gives us more control and understanding of our systems. So if you're like us: deselect the "Standard system utilities" entry, and select Continue. The next dialogue handles the installation of the [http://www.gnu.org/software/grub/ ''grub'' bootloader]. Unless your disks weren't empty and you're attempting to make this system multiboot, you'll most likely get a question if you'll allow the installer to install ''grub'' into the boot sector of the first hard disk. We'll confirm with "Yes". After the installation of grub is completed, the CD-ROM is ejected, and the system is ready to reboot into Debian Squeeze. Remove the CD and select "Continue" ==Finishing up the installation== The system should reboot into Debian. This means you should see the following boot sequence: * your machine's standard POST messages * briefly a '''welcome to GRUB''' message * then, a blue grub menu on a black screen, with two entries: ** Debian GNU/Linux, with Linux 2.6.32-5-686 ** Debian GNU/Linux, with Linux 2.6.32-5-686 (recovery mode) * then, after a default (short!) time-out, the first grub option will go into effect, and the Linux kernel is started. Lots of cryptic messages in grey-on-black will scroll by, until the last few lines read: Debian GNU/Linux 6.0 easton2 tty1 easton2 login: '''_''' If your system does not reach this login, and/or some horrible error messages appear anywhere in this boot sequence, then you've got some extra work ahead. For now we'll assume you've reached the login prompt without problem. Log in as the principal user (try to avoid logging in as root! That's BAD practice!). Once logged in, save a copy of the boot messages using ''sudo dmesg > boot.txt'' or whatever you like. Then look through the boot messages, e.g. with ''vi -R boot.txt''. Furthermore, [[APT_and_aptitude | use Aptitude]] to make sure ''all'' your software is updated to the latest version. Done! Your base system is ready. You probably now want to [[essential system software | install essential software]], [[roll your own kernel]] and [[connect your server to the Internet]]. Furthermore, you might want to create a couple of [[aliases in every profile]] so that your favourite commands are always available. ad90f62f90c5b94eea3d0cde8df6552753e214aa 0 1467 2673 2432 2011-04-12T19:45:50Z Saruman! 2 moved [[OpenLDAP]] to [[OpenLDAP 2.4.11]]: new ldap version wikitext text/x-wiki == OpenLDAP installation== Note: we're going to install OpenLDAP on our server as [http://www.openldap.org/doc/admin24/config.html#Local%20Directory%20Service the local directory service], without replication, referrals or other advanced features. Installing OpenLDAP on your Debian server is ridiculously simple. Just make sure your server is up-to-date (''sudo apt-get update'' followed by ''sudo apt-get upgrade''), and then install the two main components for your OpenLDAP server: sudo apt-get install slapd ldap-utils The Debian configuration script will ask you for only one single thing: an administrator password. As always: generate a strong password! When you've provided the password, the LDAP database is created with the administrator name "admin" and as a base directory path, something based on your DNS name. Suppose your internal domain is "amber.lan", then the script will generate ''suffix "dc=amber,dc=lan"''<ref>Should you see a third, empty, domain component (''dc='') then this is caused by a trailing dot in your particular DNS name: the DNS root. You might have specified your domain as "amber.lan.". You ''should'' change your domain name to a name without the DNS root, and you ''must'' regenerate your LDAP directory.</ref>. Since this might not always be the most convenient configuration, we recommend that you run the configuration again using ''dpkg-reconfigure slapd''. Interestingly enough, this reconfiguration asks you many ''more'' questions. The answers could look like this: omit OpenLDAP config: no DNS domain name: saruman.biz Organization name: Saruman Administrator passwd: wEt3udes Database backend: HDB DB remove after purge: no Move old DB: yes Allow LDAPv2: no As you can see, the reconfiguration yields much more configuration options than plain installation - although really you'll probably answer most questions with their default values anyway, with the exception of the database backend, which by default is BDB (see further down for the difference between BDB and HDB).<br> Anyway, the above method of configuring yields you an LDAP database with only two objects in it: * a single Organization (o="Saruman") with Distinguished Name dn="dc=saruman,dc=biz" * a single administrator with Common Name cn="admin", and dn="cn=admin,dc=saruman,dc=biz" The database that your OpenLDAP server uses is a standard Berkeley DB (BDB/HDB) database. Now we most likely will require some other databases as well in our server setup, something modern like PostgreSQL or MySQL - so why don't we configure our OpenLDAP to use this same database as well? For the answer, see [http://www.openldap.org/doc/admin24/intro.html#LDAP%20vs%20RDBMS here] - in short, the LDAP tree structure does not lend itself very well to inclusion in a modern relational database. Thus, we advise to stick with the Berkeley database provided with OpenLDAP. Now, for the database backend, we have the choice between two almost identical flavours: the ''bdb'' backend is the recommended primary backend for a normal slapd database. It uses the Oracle Berkeley DB package, referred to as ''BDB'', to store data. It makes extensive use of indexing and caching to speed data access. ''hdb'' is a variant of the ''bdb'' backend that uses a hierarchical database layout which supports subtree renames. It is otherwise identical to the ''bdb'' behavior, and all the same configuration options apply. <references/> ==OpenLDAP configuration== To finetune the OpenLDAP configuration, we make some changes to the main configuration file for the OpenLDAP server, ''/etc/ldap/slapd.conf''. Note: make SURE that the permissions on this file are rw-r----- (640) and the owner is ''root:openldap'', so that OpenLDAP can read the configuration, but only you can change it. When changing the configuration of your LDAP server, keep in mind that everything ''above'' the first ''backend hdb'' (or ''backend <something>'') should contain only global directives, and everything under it only backend directives that will apply to all databases that you're going to run under that backend type. In our examples, we're only going to run a single database of a single backend type, so all backend directives will apply to our single database. Nevertheless, you should put your global directives above the backend declaration, and the rest below. ===global directives=== We check to be certain all necessary '''schemas''' are included: in the beginning of the file we should see include /etc/ldap/schema/core.schema include /etc/ldap/schema/cosine.schema include /etc/ldap/schema/nis.schema include /etc/ldap/schema/inetorgperson.schema If any line got missing, we need to (re)enter it in order to be able to create the LDAP entries that we want. We find the line beginning with '''loglevel''' and change it from ''none'' to ''256''. This value means connections/operations/results wil be logged to the ''syslogd'' daemon. There, it will be logged to the ''LOG_LOCAL4'' facility. The default hash algorithm for '''encrypting user passwords''' is {SSHA}, which is the SHA-1 algorithm (FIPS160-1) wit a seed number. However, OpenLDAP can understand more hashes, even multiple at the same time. To specify which hash or hashes, we can specify something like password-hash {SSHA} password-hash {MD5} Valid hashes are {SHA}, {SSHA} (the default), {MD5}, {SMD5}, {CRYPT} and {CLEARTEXT}. We usually don't need to change the default, but if you do, put in the directive and restart your LDAP server. More information: "man 5 slapd.conf". ===backend directives=== We find the line beginning with ''index'', and add one or more lines under it, containing the attributes that we would like to be indexed. For starters, we would advise you to index not only ''objectClass'', but also ''uid'' and ''memberUid''. This will make the section look like this: index objectClass eq index uid eq index memberUid eq The purpose of this change is to make the OpenLDAP server create another index, on LDAP attribute ''uid'', and another one on LDAP attribute ''memberUid''. The ''uid'' index is important, because under some circumstances you might not receive any result on a valid query unless the searched entries are indexed. This entry makes sure all objects with a ''uid'' attribute are indexed, and thus can be found when queried. The ''memberUid'' index is not so important, but creating it will prevent a lot of informational messages in our syslog that go like Nov 9 10:24:40 dworkin slapd[13998]: <= bdb_equality_candidates: (memberUid) not indexed After these little refinements, we must stop, reindex, and restart the OpenLDAP server. This can be done with the following sequence of commands: sudo invoke-rc.d slapd stop sudo -u openldap slapindex sudo invoke-rc.d slapd start Note: you need to have your ''sudo'' configured to allow you to ''su'' to user ''openldap'' in order to run the second command. ==Installing and configuring an LDAP Account Manager== It's perfectly normal to manipulate your LDAP from the command line using LDAP utilities like ''ldapsearch'', ''ldapadd'', ''ldapdelete'' and ''ldapmodify'', as well as ''slapcat'', ''slappasswd'' etcetera. However, many people find a GUI for LDAP indispensible. If you are amongst those, then for you, my friend, the question becomes: which graphic tool do you want to use? Many people speak highly of ''[http://gq-project.org/ gq]'', ''[http://luma.sourceforge.net/about.html luma]'' and ''[http://phpldapadmin.sourceforge.net/ phpldapadmin]''. We go for ''lam'' ([http://lam.sourceforge.net/index.htm LDAP acount Manager]).<br> To install ''lam'', first ensure that you have installed Apache2 and PHP5. Then we can use ''apt-get install ldap-account-manager''. After installation, we can right away surf to http://<server-IP>/lam, where we can log in. However, note that in the upper right, there's a link ''LAM configuration''. We'll go there first. Under the LAM configuration page, there are two links to areas, where settings can be specified. The first one is "Edit general settings", and clicking it prompts you for a master password - by default this is "lam". Behind that password is a simple settings page, that can be filled with values like this ('''bold''' values deviate from the default): * Security settings ** Session timeout: '''15''' (the amount of minutes of inactivity that's allowed before a user is logged off) ** Allowed hosts: '''192.168.67.*''' (the range of IP numbers from which LAM accepts connections; empty would mean "all" so we recommend limiting the scope to your internal network, or even less if possible. Multiple hosts or network ranges can be inserted below each other) * Password policy (in this section you can specify lower limits on your LDAP passwords - tho currently it's not clear to us what you're limiting. We suspect it's the creation of all LDAP passwords from within LAM). ** Minimum password length: '''6''' ** Minimum lowercase characters: 0 ** Minimum uppercase characters: 0 ** Minimum numeric characters: 0 ** Minimum symbolic characters: 0 ** Minimum character classes: '''3''' (The character classes are: lowercase, uppercase, numeric and symbols) * Logging ** Log level: notice (this is the most detailed level; "warning" logs less information, "error" less still) ** Log destination: syslog (outputs all LAM messages to the syslogger; alternatively specify "no logging" or a file name & location) * Change master password ** New master password: '''*****''' (this is the password that'll replace "lam" to log into the LAM configuration; it is NOT the password of your rootdn, and if anywhere possible, you should avoid using that particular password here - for safety. Generate [http://www.pctools.com/guides/password/ yet another strong password].) ** Reenter new master password: '''*****''' After entering the above settings, we at least know LAM is operational, and coarsely secured (it's not using SSL yet). Click ''OK'' to save, or ''back to login'' if you change your mind and just want to go back. The second link from the LAM configuration page, "Edit server profiles" will again prompt you. However, this password prompt page contains an extra pulldown option, currently filled with the word "lam". This is because there is only one server profile, named "lam", and filled with some default values for your LDAP server. And under those two boxes, there's a link "manage server profiles".<br> Now first we'll rename that profile to something more descriptive. Click the "manage server profiles" link, in the "profile management page" check the radio button next to ''&#091;lam&#093; Rename profile'', put in the new name (e.g. "sarumanbiz"), fill in the shiny new master LAM password &#8212; it should no longer be the default "lam" since you've changed it, in line with the paragraph above :-) &#8212; and then click OK. Presto! The server profile is renamed.<br> When you now enter your password to edit the server preferences for profile "sarumanbiz", you get to a page with a lot of settings; the only ones we're currently interested in are: * Server settings ** Server address: ldap://localhost:389 (verify that it's either localhost, if both the LDAP server and your LAM Apache2 are on the same machine, or a correct IP address or DNS name if that's not the case) ** Tree Suffix: '''dc=saruman,dc=biz''' (the same suffix you've installed your LDAP server with) * Account types ** Edit Account types *** Users **** LDAP Suffix: '''ou=people,dc=saruman,dc=biz''' (You'll have to designate an OU in which to store user accounts; it does not have to exist yet (LAM can create it for you any time you log in) but the base has to be accessible; in our example: saruman.biz. Any name will do, but since we're storing identities, and not specifically users, we're calling the OU "people") *** Groups **** LDAP Suffix: '''ou=groups,dc=saruman,dc=biz''' (This is the OU where groups will be stored) *** Hosts **** LDAP Suffix: '''ou=hosts,dc=saruman,dc=biz''' (This is where machines, i.e. hosts, will be stored) *** Samba domains **** LDAP Suffix: '''ou=domains,dc=saruman,dc=biz''' (This is where all Windows workgroups/domains will wind up) * Security settings ** List of valid users: '''cn=admin,dc=saruman,dc=biz''' (or whatever you've designated your root DN) ** New password: '''''leave empty''''' (because this is to change the master password to edit ''this'' server profile; when this remains empty, the "master master password" for LAM remains in effect) ** Reenter password: (make this the same as the new password, i.e. empty) Now click OK, and your LAM should be ready to go. When you first log into the LAM profile you've just created, LAM will ask you if it should create the four OU's you've designated for people/groups/machines/domains. This is a nice test: if LAM cannot create those OU's, then you've misconfigured it (or the LDAP tree itself). If it can, then you'll be able to click ''tree view'' and browse the LDAP tree. At least the administrator (e.g. cn=admin) and the four OU's (e.g. domains/groups/hosts/people) should be present under the root (e.g. dc=saruman,dc=biz).<br> Incidentally, the configuration you've just entered into LAM as profile "sarumanbiz" can also be found at ''/usr/share/ldap-account-manager/config/sarumanbiz.conf'', so if need be, you can edit the profile by hand. ==Securing LAM communications with SSL== Until just now, all communications with LAM have taken place over unencrypted connections - not a nice way to work in a production environment. We really need to use SSL to secure the LAM environment. Fortunately, that is as easy as enabling SSL on the underlying Apache2 webserver. ==Where to go from here== This completes the setup of the LDAP server. * To fill it with relevant data, go to [[Filling an OpenLDAP database | the next section]]. * To set your system to accept LDAP users logging in to the machine, [[Accessing_a_shell_with_LDAP_authentication | go here]]. 8a9cf06fef9dfa8fdba749d933799fc03ea4b425 0 1620 2689 2011-06-12T14:18:58Z Saruman! 2 Created page with "Note: if you need information on the OpenLDAP version from Debian 5.0, see this page: [[OpenLDAP 2.4.11]] == OpenLDAP installation== Note: we're going to install OpenLDAP on ou..." wikitext text/x-wiki Note: if you need information on the OpenLDAP version from Debian 5.0, see this page: [[OpenLDAP 2.4.11]] == OpenLDAP installation== Note: we're going to install OpenLDAP on our server as [http://www.openldap.org/doc/admin24/config.html#Local%20Directory%20Service the local directory service], without replication, referrals or other advanced features. Under Debian Squeeze, this is OpenLDAP 2.4.23. Installing OpenLDAP on your Debian server is ridiculously simple. Just make sure your server is up-to-date (''sudo apt-get update'' followed by ''sudo apt-get upgrade''), and then install the two main components for your OpenLDAP server. First off: the LDAP client and utilities sudo apt-get install ldap-utils This will result in the installation of as much as 8 different packages (''ldap-utils'', ''libgcrypt11'', ''libgnutls26'', ''libgpg-error0'', ''libldap-2.4-2'', ''libsasl2-2'', ''libsasl2-modules'', and ''libtasn1-3''). Next the main component of an LDAP server installation, the stand-alone LDAP daemon "slapd" sudo apt-get install slapd This may also install up to 8 packages (''slapd'', ''libltdl7'', ''libperl5.10'', ''libslp1'', ''odbcinst'', ''odbcinst1debian2'', ''psmisc'' and ''unixodbc''). The Debian configuration script will ask you for only one single thing: an administrator password. As always: generate a strong password! After you've provided the password, the LDAP database is created with the administrator name "admin" and as a base directory, something based on your DNS name. Suppose your internal domain is "amber.lan", then the script will generate ''suffix "dc=amber,dc=lan"''<ref>Should you see a third, empty, domain component (''dc='') then this is caused by a trailing dot in your particular DNS name: the DNS root. You might have specified your domain as "amber.lan.". You ''should'' change your domain name to a name without the DNS root, and you ''must'' regenerate your LDAP directory.</ref>. After installation of the package, it should automatically have been started, and should now be operational. This can be checked with a utility like ''nmap'': root@server1:/etc/ldap# '''nmap -p 389 localhost''' Starting Nmap 5.00 ( http://nmap.org ) at 2011-04-13 21:19 CEST Interesting ports on localhost (127.0.0.1): PORT STATE SERVICE 389/tcp open ldap Nmap done: 1 IP address (1 host up) scanned in 0.40 seconds root@server1:/etc/ldap#'''_''' Another way to test if the LDAP server is functional, is by querying it with the ''ldapsearch'' utility, part of the package ''ldap-utils''. Let's see if we can find the naming context of the LDAP server: root@server1:/etc/ssh# '''ldapsearch -x -b <nowiki>''</nowiki> -s base '(objectclass=*)' namingContexts''' # extended LDIF # # LDAPv3 # base <> with scope baseObject # filter: (objectclass=*) # requesting: namingContexts # # dn: namingContexts: dc=amber,dc=lan # search result search: 2 result: 0 Success # numResponses: 2 # numEntries: 1 root@server1:/etc/ssh# '''_''' With this command, we do a search using * basic authentication (instead of one encrypted with SASL), * searching within the LDAP tree from base <nowiki>''</nowiki> (meaning the absolute root of the tree), * looking for base object only (instead of a one-level search, a subtree search, or a children-search), * filtering for objects of any class, * asking for the naming context of the result. The output shows that the server responds; two objects have been considered, but none match the filter (that the object should have an objectClass). Finally, you could simply install and run a graphical management tool for LDAP servers, like [http://directory.apache.org/studio/ Apache Directory Studio]. Note however that if this check fails, then this could also mean problems with firewalls, network connections et cetera. <references/> ==OpenLDAP post-install reconfiguration== Since the default configuration with the server's DNS domain as LDAP base might not always be the most convenient configuration, you could run the configuration again using ''dpkg-reconfigure slapd''. However, following this procedure is '''only''' necessary if you want to change any of the default installation values like the backend database type or DNS domain name; things like the organization name can be edited with other means, as will be shown later on. To be able to reconfigure the LDAP service, make sure you complete the following preparatory steps: * stop the LDAP daemon with ''sudo /etc/init.d/slapd stop'' * remove the existing configuration from directory ''/etc/ldap/slapd.d'' with ''sudo rm -rf /etc/ldap/slapd.d/*'' Now you can run the reconfiguration command ''sudo dpkg-reconfigure slapd''. Interestingly enough, this reconfiguration asks you many ''more'' questions. The answers could look like this: omit OpenLDAP config: no DNS domain name: saruman.biz Organization name: Saruman Administrator passwd: wEt3udes Database backend: HDB DB remove after purge: yes Move old DB: yes Allow LDAPv2: no As you can see, the reconfiguration yields much more configuration options than plain installation - although really you'll probably answer most questions with their default values anyway. The above method of configuring yields you an LDAP database with only two objects in it: * a single Organization (o="Saruman") with Distinguished Name dn="dc=saruman,dc=biz" * a single administrator with Common Name cn="admin", and dn="cn=admin,dc=saruman,dc=biz" Also note that the reconfiguration creates a backup of the "old" LDAP database in a directory with a name like ''/var/backup/unknown-2.4.23-7.ldapdb''; if you just reconfigured after installation, then you probably don't need this backup, so you can remove it. The database that your OpenLDAP server uses is a standard Berkeley DB (BDB/HDB) database. Now we most likely will require some other databases as well in our server setup, something modern like PostgreSQL or MySQL - so why don't we configure our OpenLDAP to use this same database as well? For the answer, see [http://www.openldap.org/doc/admin24/intro.html#LDAP%20vs%20RDBMS here] - in short, the LDAP tree structure does not lend itself very well to inclusion in a modern relational database. Thus, we advise to stick with the Berkeley database provided with OpenLDAP. Now, for the database backend, we have the choice between two almost identical flavours: * the ''bdb'' backend used to be the recommended primary backend for a normal slapd database. It uses the Oracle Berkeley DB package, referred to as ''BDB'', to store data. It makes extensive use of indexing and caching to speed data access. * the ''hdb'' backend is a variant of the ''bdb'' backend that uses a hierarchical database layout which supports subtree renames. It is otherwise identical to the ''bdb'' behavior, and all the same configuration options apply. In Debian 6.0 "Squeeze" with OpenLDAP 2.4.23, HDB is the default backend. ==OpenLDAP configuration== <small>(text from http://www.rjsystems.nl/en/2100-d6-openldap-provider.php)</small> As of OpenLDAP 2.4.23-3, the ''slapd'' runtime configuration is fully LDAP-enabled. The default is to manage it using the standard LDAP operations with data in LDIF. The old ''slapd.conf'' format is still supported, but since that file must now be converted to the new ''slapd-config'' format to allow runtime changes to be saved, it seems likely that the developers will eventually phase it out. Therefore, we'll focus only on the new configuration method, the main advantage of which is that any changes made are immediately active, so it is no longer necessary to restart ''slapd'' after making configuration changes. The new configuration format uses a slapd backend database that is found in the ''/etc/ldap/slapd.d/'' directory. The configuration is stored as a special LDAP directory with a predefined schema and DIT, the root of which is called ''cn=config''. If you go look there, you'll find that most parts of this LDAP directory consist of editable flat files. ===Check the current LDAP configuration=== From the command line, there really are only two ways to check the current LDAP configuration # you can see the configuration by browsing through all the flat files in ''/etc/ldap/slapd.d/'' and its subdirectories. # to get an idea of what the ''cn=config'' database looks like ''within LDAP itself'', you can run this command: root@server1:/etc/ldap# '''slapcat -b cn=config''' dn: cn=config objectClass: olcGlobal cn: config olcArgsFile: /var/run/slapd/slapd.args olcLogLevel: none olcPidFile: /var/run/slapd/slapd.pid olcToolThreads: 1 '''''(more LDIF texts)''''' entryUUID: f2a8f568-fa40-102f-8b9d-5d4cbccf32a9 creatorsName: cn=admin,cn=config createTimestamp: 20110413174103Z entryCSN: 20110413174103.641065Z#000000#000#000000 modifiersName: cn=admin,cn=config modifyTimestamp: 20110413174103Z root@server1:/etc/ldap# '''_''' : As you can see, this generates a pretty large LDIF dump of the contents of the ''cn=config'' directory. Much of it consists of schema information. The LDAP configuration directives are attributes of the directory entries (objects) and most them start with the prefix "olc" ('''O'''pen'''L'''DAP '''C'''onfiguration). Also, some of the objects have names with numbers between curly brackets. This is to compensate for the fact that LDAP databases do not store their contents in any particular order; they are inherently unordered. The numbers constitute a numeric index to ensure a consistent order in the configuration database and thereby preserve all ordering dependencies. The index numbers, however, are generated automatically in the order they are created and usually do not have to be provided. Note that by default there is no third way. If you'd like to browse this configuration using a GUI tool like [http://directory.apache.org/studio/ apache directory studio], don't bother. Debian sets the ''cn=config'' part of the database with a root user of ''cn=admin,cn=config'', but without a password, so you cannot bind to the ''cn=config'' database, so you cannot edit it by GUI. Furthermore, since there is only one bind DN which has no password, you cannot rely on the good old LDAP CLI tools such as ''ldapsearch''. ===Adding or modifying configuration information=== The simple way of changing anything in the database goes like this: ===Adding schemas=== A major task in LDAP maintenance is the addition of LDAP schemas. By default, only 4 schemas will be present in your LDAP server: ''core'', ''cosine'', ''nis'' and ''inetorgperson''. Any other schema, -- say, for Samba -- would need to be added. To this end, you need a schema in LDIF format, which you can then add to the LDAP database using the ''ldapadd'' command. Suppose you have a schema file ''samba.schema'' which you've copied to the ''/etc/ldap/schema'' directory. You'd first convert this to an LDIF file using root@server1:/etc/ldap/schema# '''slaptest -f samba.schema -F /etc/ldap/schema -s "cn=schema,cn=config"''' ldapadd -x -H ldap://<LDAP SERVER>/ -D "cn=config" -W -f <SCHEMA>.ldif Enter LDAP Password: adding new entry "cn=<SCHEMA>,cn=schema,cn=config" ==OpenLDAP finetuning== To finetune the OpenLDAP configuration, we make some changes to the main configuration file for the OpenLDAP server, ''/etc/ldap/slapd.conf''. Note: make SURE that the permissions on this file are rw-r----- (640) and the owner is ''root:openldap'', so that OpenLDAP can read the configuration, but only you can change it. When changing the configuration of your LDAP server, keep in mind that everything ''above'' the first ''backend hdb'' (or ''backend <something>'') should contain only global directives, and everything under it only backend directives that will apply to all databases that you're going to run under that backend type. In our examples, we're only going to run a single database of a single backend type, so all backend directives will apply to our single database. Nevertheless, you should put your global directives above the backend declaration, and the rest below. ffd1fd3697f5b9f148851eb7a29e4664a5a8da00 2690 2689 2011-06-12T17:58:39Z Saruman! 2 /* Adding or modifying configuration information */ slappasswd wikitext text/x-wiki Note: if you need information on the OpenLDAP version from Debian 5.0, see this page: [[OpenLDAP 2.4.11]] == OpenLDAP installation== Note: we're going to install OpenLDAP on our server as [http://www.openldap.org/doc/admin24/config.html#Local%20Directory%20Service the local directory service], without replication, referrals or other advanced features. Under Debian Squeeze, this is OpenLDAP 2.4.23. Installing OpenLDAP on your Debian server is ridiculously simple. Just make sure your server is up-to-date (''sudo apt-get update'' followed by ''sudo apt-get upgrade''), and then install the two main components for your OpenLDAP server. First off: the LDAP client and utilities sudo apt-get install ldap-utils This will result in the installation of as much as 8 different packages (''ldap-utils'', ''libgcrypt11'', ''libgnutls26'', ''libgpg-error0'', ''libldap-2.4-2'', ''libsasl2-2'', ''libsasl2-modules'', and ''libtasn1-3''). Next the main component of an LDAP server installation, the stand-alone LDAP daemon "slapd" sudo apt-get install slapd This may also install up to 8 packages (''slapd'', ''libltdl7'', ''libperl5.10'', ''libslp1'', ''odbcinst'', ''odbcinst1debian2'', ''psmisc'' and ''unixodbc''). The Debian configuration script will ask you for only one single thing: an administrator password. As always: generate a strong password! After you've provided the password, the LDAP database is created with the administrator name "admin" and as a base directory, something based on your DNS name. Suppose your internal domain is "amber.lan", then the script will generate ''suffix "dc=amber,dc=lan"''<ref>Should you see a third, empty, domain component (''dc='') then this is caused by a trailing dot in your particular DNS name: the DNS root. You might have specified your domain as "amber.lan.". You ''should'' change your domain name to a name without the DNS root, and you ''must'' regenerate your LDAP directory.</ref>. After installation of the package, it should automatically have been started, and should now be operational. This can be checked with a utility like ''nmap'': root@server1:/etc/ldap# '''nmap -p 389 localhost''' Starting Nmap 5.00 ( http://nmap.org ) at 2011-04-13 21:19 CEST Interesting ports on localhost (127.0.0.1): PORT STATE SERVICE 389/tcp open ldap Nmap done: 1 IP address (1 host up) scanned in 0.40 seconds root@server1:/etc/ldap#'''_''' Another way to test if the LDAP server is functional, is by querying it with the ''ldapsearch'' utility, part of the package ''ldap-utils''. Let's see if we can find the naming context of the LDAP server: root@server1:/etc/ssh# '''ldapsearch -x -b <nowiki>''</nowiki> -s base '(objectclass=*)' namingContexts''' # extended LDIF # # LDAPv3 # base <> with scope baseObject # filter: (objectclass=*) # requesting: namingContexts # # dn: namingContexts: dc=amber,dc=lan # search result search: 2 result: 0 Success # numResponses: 2 # numEntries: 1 root@server1:/etc/ssh# '''_''' With this command, we do a search using * basic authentication (instead of one encrypted with SASL), * searching within the LDAP tree from base <nowiki>''</nowiki> (meaning the absolute root of the tree), * looking for base object only (instead of a one-level search, a subtree search, or a children-search), * filtering for objects of any class, * asking for the naming context of the result. The output shows that the server responds; two objects have been considered, but none match the filter (that the object should have an objectClass). Finally, you could simply install and run a graphical management tool for LDAP servers, like [http://directory.apache.org/studio/ Apache Directory Studio]. Note however that if this check fails, then this could also mean problems with firewalls, network connections et cetera. <references/> ==OpenLDAP post-install reconfiguration== Since the default configuration with the server's DNS domain as LDAP base might not always be the most convenient configuration, you could run the configuration again using ''dpkg-reconfigure slapd''. However, following this procedure is '''only''' necessary if you want to change any of the default installation values like the backend database type or DNS domain name; things like the organization name can be edited with other means, as will be shown later on. To be able to reconfigure the LDAP service, make sure you complete the following preparatory steps: * stop the LDAP daemon with ''sudo /etc/init.d/slapd stop'' * remove the existing configuration from directory ''/etc/ldap/slapd.d'' with ''sudo rm -rf /etc/ldap/slapd.d/*'' Now you can run the reconfiguration command ''sudo dpkg-reconfigure slapd''. Interestingly enough, this reconfiguration asks you many ''more'' questions. The answers could look like this: omit OpenLDAP config: no DNS domain name: saruman.biz Organization name: Saruman Administrator passwd: wEt3udes Database backend: HDB DB remove after purge: yes Move old DB: yes Allow LDAPv2: no As you can see, the reconfiguration yields much more configuration options than plain installation - although really you'll probably answer most questions with their default values anyway. The above method of configuring yields you an LDAP database with only two objects in it: * a single Organization (o="Saruman") with Distinguished Name dn="dc=saruman,dc=biz" * a single administrator with Common Name cn="admin", and dn="cn=admin,dc=saruman,dc=biz" Also note that the reconfiguration creates a backup of the "old" LDAP database in a directory with a name like ''/var/backup/unknown-2.4.23-7.ldapdb''; if you just reconfigured after installation, then you probably don't need this backup, so you can remove it. The database that your OpenLDAP server uses is a standard Berkeley DB (BDB/HDB) database. Now we most likely will require some other databases as well in our server setup, something modern like PostgreSQL or MySQL - so why don't we configure our OpenLDAP to use this same database as well? For the answer, see [http://www.openldap.org/doc/admin24/intro.html#LDAP%20vs%20RDBMS here] - in short, the LDAP tree structure does not lend itself very well to inclusion in a modern relational database. Thus, we advise to stick with the Berkeley database provided with OpenLDAP. Now, for the database backend, we have the choice between two almost identical flavours: * the ''bdb'' backend used to be the recommended primary backend for a normal slapd database. It uses the Oracle Berkeley DB package, referred to as ''BDB'', to store data. It makes extensive use of indexing and caching to speed data access. * the ''hdb'' backend is a variant of the ''bdb'' backend that uses a hierarchical database layout which supports subtree renames. It is otherwise identical to the ''bdb'' behavior, and all the same configuration options apply. In Debian 6.0 "Squeeze" with OpenLDAP 2.4.23, HDB is the default backend. ==OpenLDAP configuration== <small>(text from http://www.rjsystems.nl/en/2100-d6-openldap-provider.php)</small> As of OpenLDAP 2.4.23-3, the ''slapd'' runtime configuration is fully LDAP-enabled. The default is to manage it using the standard LDAP operations with data in LDIF. The old ''slapd.conf'' format is still supported, but since that file must now be converted to the new ''slapd-config'' format to allow runtime changes to be saved, it seems likely that the developers will eventually phase it out. Therefore, we'll focus only on the new configuration method, the main advantage of which is that any changes made are immediately active, so it is no longer necessary to restart ''slapd'' after making configuration changes. The new configuration format uses a slapd backend database that is found in the ''/etc/ldap/slapd.d/'' directory. The configuration is stored as a special LDAP directory with a predefined schema and DIT, the root of which is called ''cn=config''. If you go look there, you'll find that most parts of this LDAP directory consist of editable flat files. ===Check the current LDAP configuration=== From the command line, there really are only two ways to check the current LDAP configuration # you can see the configuration by browsing through all the flat files in ''/etc/ldap/slapd.d/'' and its subdirectories. # to get an idea of what the ''cn=config'' database looks like ''within LDAP itself'', you can run this command: root@server1:/etc/ldap# '''slapcat -b cn=config''' dn: cn=config objectClass: olcGlobal cn: config olcArgsFile: /var/run/slapd/slapd.args olcLogLevel: none olcPidFile: /var/run/slapd/slapd.pid olcToolThreads: 1 '''''(more LDIF texts)''''' entryUUID: f2a8f568-fa40-102f-8b9d-5d4cbccf32a9 creatorsName: cn=admin,cn=config createTimestamp: 20110413174103Z entryCSN: 20110413174103.641065Z#000000#000#000000 modifiersName: cn=admin,cn=config modifyTimestamp: 20110413174103Z root@server1:/etc/ldap# '''_''' : As you can see, this generates a pretty large LDIF dump of the contents of the ''cn=config'' directory. Much of it consists of schema information. The LDAP configuration directives are attributes of the directory entries (objects) and most them start with the prefix "olc" ('''O'''pen'''L'''DAP '''C'''onfiguration). Also, some of the objects have names with numbers between curly brackets. This is to compensate for the fact that LDAP databases do not store their contents in any particular order; they are inherently unordered. The numbers constitute a numeric index to ensure a consistent order in the configuration database and thereby preserve all ordering dependencies. The index numbers, however, are generated automatically in the order they are created and usually do not have to be provided. Note that by default there is no third way. If you'd like to browse this configuration using a GUI tool like [http://directory.apache.org/studio/ apache directory studio], don't bother. Debian sets the ''cn=config'' part of the database with a root user of ''cn=admin,cn=config'', but without a password, so you cannot bind to the ''cn=config'' database, so you cannot edit it by GUI. Furthermore, since there is only one bind DN which has no password, you cannot rely on the good old LDAP CLI tools such as ''ldapsearch''. ===Adding or modifying configuration information=== The simple way of changing anything in the database goes like this: To add a password to the config RootDN, try the ''slappasswd'' command. By default it'll create an SSHA password, but by specifying MD5 as hash (using '' -h {MD5}'') it will create an MD5 encrypted password. The command interactively asks you for the password, and won't show you what you've typed, so be precise: root@server1:/etc/ldap# '''slappasswd -h {MD5}''' New password: Re-enter new password: {MD5}d1gyCh7gYGjifK4PGh01uw== root@server1:/etc/ldap# '''_''' Now you can paste the generated string into the LDAP configuration files. ===Adding schemas=== A major task in LDAP maintenance is the addition of LDAP schemas. By default, only 4 schemas will be present in your LDAP server: ''core'', ''cosine'', ''nis'' and ''inetorgperson''. Any other schema, -- say, for Samba -- would need to be added. To this end, you need a schema in LDIF format, which you can then add to the LDAP database using the ''ldapadd'' command. Suppose you have a schema file ''samba.schema'' which you've copied to the ''/etc/ldap/schema'' directory. You'd first convert this to an LDIF file using root@server1:/etc/ldap/schema# '''slaptest -f samba.schema -F /etc/ldap/schema -s "cn=schema,cn=config"''' ldapadd -x -H ldap://<LDAP SERVER>/ -D "cn=config" -W -f <SCHEMA>.ldif Enter LDAP Password: adding new entry "cn=<SCHEMA>,cn=schema,cn=config" ==OpenLDAP finetuning== To finetune the OpenLDAP configuration, we make some changes to the main configuration file for the OpenLDAP server, ''/etc/ldap/slapd.conf''. Note: make SURE that the permissions on this file are rw-r----- (640) and the owner is ''root:openldap'', so that OpenLDAP can read the configuration, but only you can change it. When changing the configuration of your LDAP server, keep in mind that everything ''above'' the first ''backend hdb'' (or ''backend <something>'') should contain only global directives, and everything under it only backend directives that will apply to all databases that you're going to run under that backend type. In our examples, we're only going to run a single database of a single backend type, so all backend directives will apply to our single database. Nevertheless, you should put your global directives above the backend declaration, and the rest below. 654d8a8ac4d27d4e5df0770885a703bbc8d03e4c 2691 2690 2011-06-13T13:47:06Z Saruman! 2 /* Adding or modifying configuration information */ hmz wikitext text/x-wiki Note: if you need information on the OpenLDAP version from Debian 5.0, see this page: [[OpenLDAP 2.4.11]] == OpenLDAP installation== Note: we're going to install OpenLDAP on our server as [http://www.openldap.org/doc/admin24/config.html#Local%20Directory%20Service the local directory service], without replication, referrals or other advanced features. Under Debian Squeeze, this is OpenLDAP 2.4.23. Installing OpenLDAP on your Debian server is ridiculously simple. Just make sure your server is up-to-date (''sudo apt-get update'' followed by ''sudo apt-get upgrade''), and then install the two main components for your OpenLDAP server. First off: the LDAP client and utilities sudo apt-get install ldap-utils This will result in the installation of as much as 8 different packages (''ldap-utils'', ''libgcrypt11'', ''libgnutls26'', ''libgpg-error0'', ''libldap-2.4-2'', ''libsasl2-2'', ''libsasl2-modules'', and ''libtasn1-3''). Next the main component of an LDAP server installation, the stand-alone LDAP daemon "slapd" sudo apt-get install slapd This may also install up to 8 packages (''slapd'', ''libltdl7'', ''libperl5.10'', ''libslp1'', ''odbcinst'', ''odbcinst1debian2'', ''psmisc'' and ''unixodbc''). The Debian configuration script will ask you for only one single thing: an administrator password. As always: generate a strong password! After you've provided the password, the LDAP database is created with the administrator name "admin" and as a base directory, something based on your DNS name. Suppose your internal domain is "amber.lan", then the script will generate ''suffix "dc=amber,dc=lan"''<ref>Should you see a third, empty, domain component (''dc='') then this is caused by a trailing dot in your particular DNS name: the DNS root. You might have specified your domain as "amber.lan.". You ''should'' change your domain name to a name without the DNS root, and you ''must'' regenerate your LDAP directory.</ref>. After installation of the package, it should automatically have been started, and should now be operational. This can be checked with a utility like ''nmap'': root@server1:/etc/ldap# '''nmap -p 389 localhost''' Starting Nmap 5.00 ( http://nmap.org ) at 2011-04-13 21:19 CEST Interesting ports on localhost (127.0.0.1): PORT STATE SERVICE 389/tcp open ldap Nmap done: 1 IP address (1 host up) scanned in 0.40 seconds root@server1:/etc/ldap#'''_''' Another way to test if the LDAP server is functional, is by querying it with the ''ldapsearch'' utility, part of the package ''ldap-utils''. Let's see if we can find the naming context of the LDAP server: root@server1:/etc/ssh# '''ldapsearch -x -b <nowiki>''</nowiki> -s base '(objectclass=*)' namingContexts''' # extended LDIF # # LDAPv3 # base <> with scope baseObject # filter: (objectclass=*) # requesting: namingContexts # # dn: namingContexts: dc=amber,dc=lan # search result search: 2 result: 0 Success # numResponses: 2 # numEntries: 1 root@server1:/etc/ssh# '''_''' With this command, we do a search using * basic authentication (instead of one encrypted with SASL), * searching within the LDAP tree from base <nowiki>''</nowiki> (meaning the absolute root of the tree), * looking for base object only (instead of a one-level search, a subtree search, or a children-search), * filtering for objects of any class, * asking for the naming context of the result. The output shows that the server responds; two objects have been considered, but none match the filter (that the object should have an objectClass). Finally, you could simply install and run a graphical management tool for LDAP servers, like [http://directory.apache.org/studio/ Apache Directory Studio]. Note however that if this check fails, then this could also mean problems with firewalls, network connections et cetera. <references/> ==OpenLDAP post-install reconfiguration== Since the default configuration with the server's DNS domain as LDAP base might not always be the most convenient configuration, you could run the configuration again using ''dpkg-reconfigure slapd''. However, following this procedure is '''only''' necessary if you want to change any of the default installation values like the backend database type or DNS domain name; things like the organization name can be edited with other means, as will be shown later on. To be able to reconfigure the LDAP service, make sure you complete the following preparatory steps: * stop the LDAP daemon with ''sudo /etc/init.d/slapd stop'' * remove the existing configuration from directory ''/etc/ldap/slapd.d'' with ''sudo rm -rf /etc/ldap/slapd.d/*'' Now you can run the reconfiguration command ''sudo dpkg-reconfigure slapd''. Interestingly enough, this reconfiguration asks you many ''more'' questions. The answers could look like this: omit OpenLDAP config: no DNS domain name: saruman.biz Organization name: Saruman Administrator passwd: wEt3udes Database backend: HDB DB remove after purge: yes Move old DB: yes Allow LDAPv2: no As you can see, the reconfiguration yields much more configuration options than plain installation - although really you'll probably answer most questions with their default values anyway. The above method of configuring yields you an LDAP database with only two objects in it: * a single Organization (o="Saruman") with Distinguished Name dn="dc=saruman,dc=biz" * a single administrator with Common Name cn="admin", and dn="cn=admin,dc=saruman,dc=biz" Also note that the reconfiguration creates a backup of the "old" LDAP database in a directory with a name like ''/var/backup/unknown-2.4.23-7.ldapdb''; if you just reconfigured after installation, then you probably don't need this backup, so you can remove it. The database that your OpenLDAP server uses is a standard Berkeley DB (BDB/HDB) database. Now we most likely will require some other databases as well in our server setup, something modern like PostgreSQL or MySQL - so why don't we configure our OpenLDAP to use this same database as well? For the answer, see [http://www.openldap.org/doc/admin24/intro.html#LDAP%20vs%20RDBMS here] - in short, the LDAP tree structure does not lend itself very well to inclusion in a modern relational database. Thus, we advise to stick with the Berkeley database provided with OpenLDAP. Now, for the database backend, we have the choice between two almost identical flavours: * the ''bdb'' backend used to be the recommended primary backend for a normal slapd database. It uses the Oracle Berkeley DB package, referred to as ''BDB'', to store data. It makes extensive use of indexing and caching to speed data access. * the ''hdb'' backend is a variant of the ''bdb'' backend that uses a hierarchical database layout which supports subtree renames. It is otherwise identical to the ''bdb'' behavior, and all the same configuration options apply. In Debian 6.0 "Squeeze" with OpenLDAP 2.4.23, HDB is the default backend. ==OpenLDAP configuration== <small>(text from http://www.rjsystems.nl/en/2100-d6-openldap-provider.php)</small> As of OpenLDAP 2.4.23-3, the ''slapd'' runtime configuration is fully LDAP-enabled. The default is to manage it using the standard LDAP operations with data in LDIF. The old ''slapd.conf'' format is still supported, but since that file must now be converted to the new ''slapd-config'' format to allow runtime changes to be saved, it seems likely that the developers will eventually phase it out. Therefore, we'll focus only on the new configuration method, the main advantage of which is that any changes made are immediately active, so it is no longer necessary to restart ''slapd'' after making configuration changes. The new configuration format uses a slapd backend database that is found in the ''/etc/ldap/slapd.d/'' directory. The configuration is stored as a special LDAP directory with a predefined schema and DIT, the root of which is called ''cn=config''. If you go look there, you'll find that most parts of this LDAP directory consist of editable flat files. ===Check the current LDAP configuration=== From the command line, there really are only two ways to check the current LDAP configuration # you can see the configuration by browsing through all the flat files in ''/etc/ldap/slapd.d/'' and its subdirectories. # to get an idea of what the ''cn=config'' database looks like ''within LDAP itself'', you can run this command: root@server1:/etc/ldap# '''slapcat -b cn=config''' dn: cn=config objectClass: olcGlobal cn: config olcArgsFile: /var/run/slapd/slapd.args olcLogLevel: none olcPidFile: /var/run/slapd/slapd.pid olcToolThreads: 1 '''''(more LDIF texts)''''' entryUUID: f2a8f568-fa40-102f-8b9d-5d4cbccf32a9 creatorsName: cn=admin,cn=config createTimestamp: 20110413174103Z entryCSN: 20110413174103.641065Z#000000#000#000000 modifiersName: cn=admin,cn=config modifyTimestamp: 20110413174103Z root@server1:/etc/ldap# '''_''' : As you can see, this generates a pretty large LDIF dump of the contents of the ''cn=config'' directory. Much of it consists of schema information. The LDAP configuration directives are attributes of the directory entries (objects) and most them start with the prefix "olc" ('''O'''pen'''L'''DAP '''C'''onfiguration). Also, some of the objects have names with numbers between curly brackets. This is to compensate for the fact that LDAP databases do not store their contents in any particular order; they are inherently unordered. The numbers constitute a numeric index to ensure a consistent order in the configuration database and thereby preserve all ordering dependencies. The index numbers, however, are generated automatically in the order they are created and usually do not have to be provided. Note that by default there is no third way. If you'd like to browse this configuration using a GUI tool like [http://directory.apache.org/studio/ apache directory studio], don't bother. Debian sets the ''cn=config'' part of the database with a root user of ''cn=admin,cn=config'', but without a password, so you cannot bind to the ''cn=config'' database, so you cannot edit it by GUI. Furthermore, since there is only one bind DN which has no password, you cannot rely on the good old LDAP CLI tools such as ''ldapsearch''. ===Adding or modifying configuration information=== The simple way of changing anything in the database goes like this: To add a password to the config RootDN, try the ''slappasswd'' command. By default it'll create an SSHA password, but by specifying MD5 as hash (using '' -h {MD5}'') it will create an MD5 encrypted password. The command interactively asks you for the password, and won't show you what you've typed, so be precise: root@server1:/etc/ldap# '''slappasswd -h {MD5}''' New password: Re-enter new password: {MD5}d1gyCh7gYGjifK4PGh01uw== root@server1:/etc/ldap# '''_''' Now we determine the DN (Distinguished Name) for the database that contains the RootDN password. To do this we used the following LDAP search command. root@server1:/etc/ldap# '''ldapsearch -LLL -Y EXTERNAL -H ldapi:/// -b cn=config olcRootDN=cn=admin,cn=config dn olcRootDN olcRootPW''' SASL/EXTERNAL authentication started SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth SASL SSF: 0 dn: olcDatabase={0}config,cn=config olcRootDN: cn=admin,cn=config root@server1:/etc/ldap# '''_''' Note the olcDatabase line, as it's the result we were looking for; it'll be needed for the ''ldapmodify'' command. Furthermore, note the absence of an olcRootPW entry; this is the starting point for a Debian OpenLDAP server.<br> Now we can stick in a new password. If no password is present, you can use this root@server1:/etc/ldap# '''''' root@server1:/etc/ldap# '''_''' ===Adding schemas=== A major task in LDAP maintenance is the addition of LDAP schemas. By default, only 4 schemas will be present in your LDAP server: ''core'', ''cosine'', ''nis'' and ''inetorgperson''. Any other schema, -- say, for Samba -- would need to be added. To this end, you need a schema in LDIF format, which you can then add to the LDAP database using the ''ldapadd'' command. Suppose you have a schema file ''samba.schema'' which you've copied to the ''/etc/ldap/schema'' directory. You'd first convert this to an LDIF file using root@server1:/etc/ldap/schema# '''slaptest -f samba.schema -F /etc/ldap/schema -s "cn=schema,cn=config"''' ldapadd -x -H ldap://<LDAP SERVER>/ -D "cn=config" -W -f <SCHEMA>.ldif Enter LDAP Password: adding new entry "cn=<SCHEMA>,cn=schema,cn=config" ==OpenLDAP finetuning== To finetune the OpenLDAP configuration, we make some changes to the main configuration file for the OpenLDAP server, ''/etc/ldap/slapd.conf''. Note: make SURE that the permissions on this file are rw-r----- (640) and the owner is ''root:openldap'', so that OpenLDAP can read the configuration, but only you can change it. When changing the configuration of your LDAP server, keep in mind that everything ''above'' the first ''backend hdb'' (or ''backend <something>'') should contain only global directives, and everything under it only backend directives that will apply to all databases that you're going to run under that backend type. In our examples, we're only going to run a single database of a single backend type, so all backend directives will apply to our single database. Nevertheless, you should put your global directives above the backend declaration, and the rest below. dc7c956c122978989b61f2de828509535c6bd33e 2692 2691 2011-06-13T15:54:23Z Saruman! 2 install cleanup wikitext text/x-wiki Note: if you need information on the OpenLDAP version from Debian 5.0, see this page: [[OpenLDAP 2.4.11]] == OpenLDAP installation== Note: we're going to install OpenLDAP on our server as [http://www.openldap.org/doc/admin24/config.html#Local%20Directory%20Service the local directory service], without replication, referrals or other advanced features. Under Debian Squeeze, this is OpenLDAP 2.4.23. ===Standard installation=== Installing OpenLDAP on your Debian server is ridiculously simple. Just make sure your server is up-to-date (''sudo apt-get update'' followed by ''sudo apt-get upgrade''), and then install the two main components for your OpenLDAP server. First off: the LDAP client and utilities sudo apt-get install ldap-utils This will result in the installation of as much as 8 different packages (''ldap-utils'', ''libgcrypt11'', ''libgnutls26'', ''libgpg-error0'', ''libldap-2.4-2'', ''libsasl2-2'', ''libsasl2-modules'', and ''libtasn1-3''). Next the main component of an LDAP server installation, the stand-alone LDAP daemon "slapd" sudo apt-get install slapd This may also install up to 8 packages (''slapd'', ''libltdl7'', ''libperl5.10'', ''libslp1'', ''odbcinst'', ''odbcinst1debian2'', ''psmisc'' and ''unixodbc''). The Debian configuration script will ask you for only one single thing: an administrator password. As always: generate a strong password! After you've provided the password, the LDAP database is created with the administrator name "admin" and as a base directory, something based on your DNS name. Suppose your internal domain is "amber.lan", then the script will generate ''suffix "dc=amber,dc=lan"''<ref>Should you see a third, empty, domain component (''dc='') then this is caused by a trailing dot in your particular DNS name: the DNS root. You might have specified your domain as "amber.lan.". You ''should'' change your domain name to a name without the DNS root, and you ''must'' regenerate your LDAP directory.</ref>. The above method of configuring yields you an LDAP database with only two objects in it. Suppose your DNS name is "easton2.amber.lan", then the two objects are: * a single Organization (o="amber.lan") with Distinguished Name dn="dc=amber,dc=lan" * a single administrator with Common Name cn="admin", and dn="cn=admin,dc=amber,dc=lan" Note, however, that there's ''also'' a second LDAP database, "cn=config", which on your server is located under ''/etc/ldap/slapd.d''. We'll cover what's in it further on. <references/> ===Testing the installation=== After installation of the package, it should automatically have been started, and should now be operational. This can be checked with a utility like ''nmap'': root@easton2:~# '''nmap -p 389 localhost''' Starting Nmap 5.00 ( <nowiki>http://nmap.org</nowiki> ) at 2011-04-13 21:19 CEST Interesting ports on localhost (127.0.0.1): PORT STATE SERVICE 389/tcp open ldap Nmap done: 1 IP address (1 host up) scanned in 0.40 seconds root@easton2:~#'''_''' Another way to test if the LDAP server is functional, is by querying it with the ''ldapsearch'' utility, part of the package ''ldap-utils''. Let's see if we can find the naming context of the LDAP server: root@easton2:~# '''ldapsearch -x -b <nowiki>''</nowiki> -s base '(objectclass=*)' namingContexts''' # extended LDIF # # LDAPv3 # base <> with scope baseObject # filter: (objectclass=*) # requesting: namingContexts # # dn: namingContexts: dc=amber,dc=lan # search result search: 2 result: 0 Success # numResponses: 2 # numEntries: 1 root@easton2:~# '''_''' With this command, we do a search using * basic authentication (instead of one encrypted with SASL), * searching within the LDAP tree from base <nowiki>''</nowiki> (meaning the absolute root of the tree), * looking for base object only (instead of a one-level search, a subtree search, or a children-search), * filtering for objects of any class, * asking for the naming context of the result. The output shows that the server responds; two objects have been considered, but none match the filter (that the object should have an objectClass). Let's now do the same but with authentication, to see if we can bind to the LDAP server. We'll first use an incorrect password, then the correct one: root@easton2:~# '''ldapsearch -W -D "cn=admin,dc=amber,dc=lan"''' Enter LDAP Password: ldap_bind: Invalid credentials (49) root@easton2:~# '''ldapsearch -W -D "cn=admin,dc=amber,dc=lan"''' Enter LDAP Password: # extended LDIF # # LDAPv3 # base <> (default) with scope subtree # filter: (objectclass=*) # requesting: ALL # # search result search: 2 result: 32 No such object # numResponses: 1 root@easton2:~# '''_''' Finally, you could simply install and run a graphical management tool for LDAP servers, like [http://directory.apache.org/studio/ Apache Directory Studio]. Note however that if this check fails, then this could also mean problems with firewalls, network connections et cetera. ===Post-install reconfiguration=== Since the default configuration with the server's DNS domain as LDAP base might not always be the most convenient configuration, you could run the configuration again using ''dpkg-reconfigure slapd''. However, following this procedure is '''only''' necessary if you want to change any of the default installation values like the backend database type or DNS domain name; things like the organization name can be edited with other means, as will be shown later on. To be able to reconfigure the LDAP service, you can run the reconfiguration command ''sudo dpkg-reconfigure slapd''. Contrary to some older versions of Debian, you do not need to manually stop the ''slapd'' daemon, and you don't need to manually remove the old configuration or database (in fact, if you do, then the ''slapd'' package will break, so you cannot easily remove it with APT tools). Interestingly enough, this reconfiguration asks you many ''more'' questions. The answers could look like this: omit OpenLDAP config: no DNS domain name: saruman.biz Organization name: Saruman Administrator passwd: wEt3udes Database backend: HDB DB remove after purge: yes Move old DB: yes Allow LDAPv2: no As you can see, the reconfiguration yields much more configuration options than plain installation - although really you'll probably answer most questions with their default values anyway. The above method of configuring yields you an LDAP database with only two objects in it: * a single Organization (o="Saruman") with Distinguished Name dn="dc=saruman,dc=biz" * a single administrator with Common Name cn="admin", and dn="cn=admin,dc=saruman,dc=biz" Also note that the reconfiguration creates a backup of the "old" LDAP database in a directory with a name like ''/var/backup/unknown-2.4.23-7.ldapdb''; if you just reconfigured after installation, then you probably don't need this backup, so you can remove it. The database that your OpenLDAP server uses is a standard Berkeley DB (BDB/HDB) database. Now we most likely will require some other databases as well in our server setup, something modern like PostgreSQL or MySQL - so why don't we configure our OpenLDAP to use this same database as well? For the answer, see [http://www.openldap.org/doc/admin24/intro.html#LDAP%20vs%20RDBMS here] - in short, the LDAP tree structure does not lend itself very well to inclusion in a modern relational database. Thus, we advise to stick with the Berkeley database provided with OpenLDAP. Now, for the database backend, we have the choice between two almost identical flavours: * the ''bdb'' backend used to be the recommended primary backend for a normal slapd database. It uses the Oracle Berkeley DB package, referred to as ''BDB'', to store data. It makes extensive use of indexing and caching to speed data access. * the ''hdb'' backend is a variant of the ''bdb'' backend that uses a hierarchical database layout which supports subtree renames. It is otherwise identical to the ''bdb'' behavior, and all the same configuration options apply. In Debian 6.0 "Squeeze" with OpenLDAP 2.4.23, HDB is the default backend. ==OpenLDAP configuration== <small>(text from http://www.rjsystems.nl/en/2100-d6-openldap-provider.php)</small> As of OpenLDAP 2.4.23-3, the ''slapd'' runtime configuration is fully LDAP-enabled. The default is to manage it using the standard LDAP operations with data in LDIF. The old ''slapd.conf'' format is still supported, but since that file must now be converted to the new ''slapd-config'' format to allow runtime changes to be saved, it seems likely that the developers will eventually phase it out. Therefore, we'll focus only on the new configuration method, the main advantage of which is that any changes made are immediately active, so it is no longer necessary to restart ''slapd'' after making configuration changes. The new configuration format uses a slapd backend database that is found in the ''/etc/ldap/slapd.d/'' directory. The configuration is stored as a special LDAP directory with a predefined schema and DIT, the root of which is called ''cn=config''. If you go look there, you'll find that most parts of this LDAP directory consist of editable flat files. ===Check the current LDAP configuration=== From the command line, there really are only two ways to check the current LDAP configuration # you can see the configuration by browsing through all the flat files in ''/etc/ldap/slapd.d/'' and its subdirectories. # to get an idea of what the ''cn=config'' database looks like ''within LDAP itself'', you can run this command: root@easton2:/etc/ldap# '''slapcat -b cn=config''' dn: cn=config objectClass: olcGlobal cn: config olcArgsFile: /var/run/slapd/slapd.args olcLogLevel: none olcPidFile: /var/run/slapd/slapd.pid olcToolThreads: 1 '''''(more LDIF texts)''''' entryUUID: f2a8f568-fa40-102f-8b9d-5d4cbccf32a9 creatorsName: cn=admin,cn=config createTimestamp: 20110413174103Z entryCSN: 20110413174103.641065Z#000000#000#000000 modifiersName: cn=admin,cn=config modifyTimestamp: 20110413174103Z root@easton2:/etc/ldap# '''_''' : As you can see, this generates a pretty large LDIF dump of the contents of the ''cn=config'' directory. Much of it consists of schema information. The LDAP configuration directives are attributes of the directory entries (objects) and most them start with the prefix "olc" ('''O'''pen'''L'''DAP '''C'''onfiguration). Also, some of the objects have names with numbers between curly brackets. This is to compensate for the fact that LDAP databases do not store their contents in any particular order; they are inherently unordered. The numbers constitute a numeric index to ensure a consistent order in the configuration database and thereby preserve all ordering dependencies. The index numbers, however, are generated automatically in the order they are created and usually do not have to be provided. Note that by default there is no third way. If you'd like to browse this configuration using a GUI tool like [http://directory.apache.org/studio/ apache directory studio], don't bother. Debian sets the ''cn=config'' part of the database with a root user of ''cn=admin,cn=config'', but without a password, so you cannot bind to the ''cn=config'' database, so you cannot edit it by GUI. Furthermore, since there is only one bind DN which has no password, you cannot rely on the good old LDAP CLI tools such as ''ldapsearch''. ===Adding or modifying configuration information=== The simple way of changing anything in the database goes like this: To add a password to the config RootDN, try the ''slappasswd'' command. By default it'll create an SSHA password, but by specifying MD5 as hash (using '' -h {MD5}'') it will create an MD5 encrypted password. The command interactively asks you for the password, and won't show you what you've typed, so be precise: root@easton2:/etc/ldap# '''slappasswd -h {MD5}''' New password: Re-enter new password: {MD5}d1gyCh7gYGjifK4PGh01uw== root@easton2:/etc/ldap# '''_''' Now we determine the DN (Distinguished Name) for the database that contains the RootDN password. To do this we used the following LDAP search command. root@easton2:/etc/ldap# '''ldapsearch -LLL -Y EXTERNAL -H ldapi:/// -b cn=config olcRootDN=cn=admin,cn=config dn olcRootDN olcRootPW''' SASL/EXTERNAL authentication started SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth SASL SSF: 0 dn: olcDatabase={0}config,cn=config olcRootDN: cn=admin,cn=config root@easton2:/etc/ldap# '''_''' Note the olcDatabase line, as it's the result we were looking for; it'll be needed for the ''ldapmodify'' command. Furthermore, note the absence of an olcRootPW entry; this is the starting point for a Debian OpenLDAP server.<br> Now we can stick in a new password. If no password is present, you can use this root@easton2:/etc/ldap# '''''' root@easton2:/etc/ldap# '''_''' ===Adding schemas=== A major task in LDAP maintenance is the addition of LDAP schemas. By default, only 4 schemas will be present in your LDAP server: ''core'', ''cosine'', ''nis'' and ''inetorgperson''. Any other schema, -- say, for Samba -- would need to be added. To this end, you need a schema in LDIF format, which you can then add to the LDAP database using the ''ldapadd'' command. Suppose you have a schema file ''samba.schema'' which you've copied to the ''/etc/ldap/schema'' directory. You'd first convert this to an LDIF file using root@easton2:/etc/ldap/schema# '''slaptest -f samba.schema -F /etc/ldap/schema -s "cn=schema,cn=config"''' ldapadd -x -H ldap://<LDAP SERVER>/ -D "cn=config" -W -f <SCHEMA>.ldif Enter LDAP Password: adding new entry "cn=<SCHEMA>,cn=schema,cn=config" ==OpenLDAP finetuning== To finetune the OpenLDAP configuration, we make some changes to the main configuration file for the OpenLDAP server, ''/etc/ldap/slapd.conf''. Note: make SURE that the permissions on this file are rw-r----- (640) and the owner is ''root:openldap'', so that OpenLDAP can read the configuration, but only you can change it. When changing the configuration of your LDAP server, keep in mind that everything ''above'' the first ''backend hdb'' (or ''backend <something>'') should contain only global directives, and everything under it only backend directives that will apply to all databases that you're going to run under that backend type. In our examples, we're only going to run a single database of a single backend type, so all backend directives will apply to our single database. Nevertheless, you should put your global directives above the backend declaration, and the rest below. 466fc9bfd7d51b96f4bad16a1282a8bfa775e2c4 2693 2692 2011-06-13T18:36:40Z Saruman! 2 /* Check the current LDAP configuration */ complete access tools wikitext text/x-wiki Note: if you need information on the OpenLDAP version from Debian 5.0, see this page: [[OpenLDAP 2.4.11]] == OpenLDAP installation== Note: we're going to install OpenLDAP on our server as [http://www.openldap.org/doc/admin24/config.html#Local%20Directory%20Service the local directory service], without replication, referrals or other advanced features. Under Debian Squeeze, this is OpenLDAP 2.4.23. ===Standard installation=== Installing OpenLDAP on your Debian server is ridiculously simple. Just make sure your server is up-to-date (''sudo apt-get update'' followed by ''sudo apt-get upgrade''), and then install the two main components for your OpenLDAP server. First off: the LDAP client and utilities sudo apt-get install ldap-utils This will result in the installation of as much as 8 different packages (''ldap-utils'', ''libgcrypt11'', ''libgnutls26'', ''libgpg-error0'', ''libldap-2.4-2'', ''libsasl2-2'', ''libsasl2-modules'', and ''libtasn1-3''). Next the main component of an LDAP server installation, the stand-alone LDAP daemon "slapd" sudo apt-get install slapd This may also install up to 8 packages (''slapd'', ''libltdl7'', ''libperl5.10'', ''libslp1'', ''odbcinst'', ''odbcinst1debian2'', ''psmisc'' and ''unixodbc''). The Debian configuration script will ask you for only one single thing: an administrator password. As always: generate a strong password! After you've provided the password, the LDAP database is created with the administrator name "admin" and as a base directory, something based on your DNS name. Suppose your internal domain is "amber.lan", then the script will generate ''suffix "dc=amber,dc=lan"''<ref>Should you see a third, empty, domain component (''dc='') then this is caused by a trailing dot in your particular DNS name: the DNS root. You might have specified your domain as "amber.lan.". You ''should'' change your domain name to a name without the DNS root, and you ''must'' regenerate your LDAP directory.</ref>. The above method of configuring yields you an LDAP database with only two objects in it. Suppose your DNS name is "easton2.amber.lan", then the two objects are: * a single Organization (o="amber.lan") with Distinguished Name dn="dc=amber,dc=lan" * a single administrator with Common Name cn="admin", and dn="cn=admin,dc=amber,dc=lan" Note, however, that there's ''also'' a second LDAP database, "cn=config", which on your server is located under ''/etc/ldap/slapd.d''. We'll cover what's in it further on. <references/> ===Testing the installation=== After installation of the package, it should automatically have been started, and should now be operational. This can be checked with a utility like ''nmap'': root@easton2:~# '''nmap -p 389 localhost''' Starting Nmap 5.00 ( <nowiki>http://nmap.org</nowiki> ) at 2011-04-13 21:19 CEST Interesting ports on localhost (127.0.0.1): PORT STATE SERVICE 389/tcp open ldap Nmap done: 1 IP address (1 host up) scanned in 0.40 seconds root@easton2:~#'''_''' Another way to test if the LDAP server is functional, is by querying it with the ''ldapsearch'' utility, part of the package ''ldap-utils''. Let's see if we can find the naming context of the LDAP server: root@easton2:~# '''ldapsearch -x -b <nowiki>''</nowiki> -s base '(objectclass=*)' namingContexts''' # extended LDIF # # LDAPv3 # base <> with scope baseObject # filter: (objectclass=*) # requesting: namingContexts # # dn: namingContexts: dc=amber,dc=lan # search result search: 2 result: 0 Success # numResponses: 2 # numEntries: 1 root@easton2:~# '''_''' With this command, we do a search using * basic authentication (instead of one encrypted with SASL), * searching within the LDAP tree from base <nowiki>''</nowiki> (meaning the absolute root of the tree), * looking for base object only (instead of a one-level search, a subtree search, or a children-search), * filtering for objects of any class, * asking for the naming context of the result. The output shows that the server responds; two objects have been considered, but none match the filter (that the object should have an objectClass). Let's now do the same but with authentication, to see if we can bind to the LDAP server. We'll first use an incorrect password, then the correct one: root@easton2:~# '''ldapsearch -W -D "cn=admin,dc=amber,dc=lan"''' Enter LDAP Password: ldap_bind: Invalid credentials (49) root@easton2:~# '''ldapsearch -W -D "cn=admin,dc=amber,dc=lan"''' Enter LDAP Password: # extended LDIF # # LDAPv3 # base <> (default) with scope subtree # filter: (objectclass=*) # requesting: ALL # # search result search: 2 result: 32 No such object # numResponses: 1 root@easton2:~# '''_''' Finally, you could simply install and run a graphical management tool for LDAP servers, like [http://directory.apache.org/studio/ Apache Directory Studio]. Note however that if this check fails, then this could also mean problems with firewalls, network connections et cetera. ===Post-install reconfiguration=== Since the default configuration with the server's DNS domain as LDAP base might not always be the most convenient configuration, you could run the configuration again using ''dpkg-reconfigure slapd''. However, following this procedure is '''only''' necessary if you want to change any of the default installation values like the backend database type or DNS domain name; things like the organization name can be edited with other means, as will be shown later on. To be able to reconfigure the LDAP service, you can run the reconfiguration command ''sudo dpkg-reconfigure slapd''. Contrary to some older versions of Debian, you do not need to manually stop the ''slapd'' daemon, and you don't need to manually remove the old configuration or database (in fact, if you do, then the ''slapd'' package will break, so you cannot easily remove it with APT tools). Interestingly enough, this reconfiguration asks you many ''more'' questions. The answers could look like this: omit OpenLDAP config: no DNS domain name: saruman.biz Organization name: Saruman Administrator passwd: wEt3udes Database backend: HDB DB remove after purge: yes Move old DB: yes Allow LDAPv2: no As you can see, the reconfiguration yields much more configuration options than plain installation - although really you'll probably answer most questions with their default values anyway. The above method of configuring yields you an LDAP database with only two objects in it: * a single Organization (o="Saruman") with Distinguished Name dn="dc=saruman,dc=biz" * a single administrator with Common Name cn="admin", and dn="cn=admin,dc=saruman,dc=biz" Also note that the reconfiguration creates a backup of the "old" LDAP database in a directory with a name like ''/var/backup/unknown-2.4.23-7.ldapdb''; if you just reconfigured after installation, then you probably don't need this backup, so you can remove it. The database that your OpenLDAP server uses is a standard Berkeley DB (BDB/HDB) database. Now we most likely will require some other databases as well in our server setup, something modern like PostgreSQL or MySQL - so why don't we configure our OpenLDAP to use this same database as well? For the answer, see [http://www.openldap.org/doc/admin24/intro.html#LDAP%20vs%20RDBMS here] - in short, the LDAP tree structure does not lend itself very well to inclusion in a modern relational database. Thus, we advise to stick with the Berkeley database provided with OpenLDAP. Now, for the database backend, we have the choice between two almost identical flavours: * the ''bdb'' backend used to be the recommended primary backend for a normal slapd database. It uses the Oracle Berkeley DB package, referred to as ''BDB'', to store data. It makes extensive use of indexing and caching to speed data access. * the ''hdb'' backend is a variant of the ''bdb'' backend that uses a hierarchical database layout which supports subtree renames. It is otherwise identical to the ''bdb'' behavior, and all the same configuration options apply. In Debian 6.0 "Squeeze" with OpenLDAP 2.4.23, HDB is the default backend. ==OpenLDAP configuration== <small>(text from http://www.rjsystems.nl/en/2100-d6-openldap-provider.php)</small> As of OpenLDAP 2.4.23-3, the ''slapd'' runtime configuration is fully LDAP-enabled. The default is to manage it using the standard LDAP operations with data in LDIF. The old ''slapd.conf'' format is still supported, but since that file must now be converted to the new ''slapd-config'' format to allow runtime changes to be saved, it seems likely that the developers will eventually phase it out. Therefore, we'll focus only on the new configuration method, the main advantage of which is that any changes made are immediately active, so it is no longer necessary to restart ''slapd'' after making configuration changes. The new configuration format uses a slapd backend database that is found in the ''/etc/ldap/slapd.d/'' directory. The configuration is stored as a special LDAP directory with a predefined schema and DIT, the root of which is called ''cn=config''. If you go look there, you'll find that most parts of this LDAP directory consist of editable flat files. ===Check the current LDAP configuration=== From the command line, there really are several ways to check the current LDAP configuration: * from the server itself, you can use the trusty ''ldapsearch'' command, running under root: this'll authenticate with user ID 0. Filtering only for distinguished names: root@easton2:/etc/ldap# '''ldapsearch -LLL -Y EXTERNAL -H ldapi:/// -b cn=config dn''' SASL/EXTERNAL authentication started SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth SASL SSF: 0 dn: cn=config dn: cn=module{0},cn=config dn: cn=schema,cn=config dn: cn={0}core,cn=schema,cn=config dn: cn={1}cosine,cn=schema,cn=config dn: cn={2}nis,cn=schema,cn=config dn: cn={3}inetorgperson,cn=schema,cn=config dn: olcBackend={0}hdb,cn=config dn: olcDatabase={-1}frontend,cn=config dn: olcDatabase={0}config,cn=config dn: olcDatabase={1}hdb,cn=config root@easton2:/etc/ldap# '''_''' * to get an idea of what the ''cn=config'' database looks like ''within LDAP itself'', you can run this command: root@easton2:/etc/ldap# '''slapcat -b cn=config''' dn: cn=config objectClass: olcGlobal cn: config olcArgsFile: /var/run/slapd/slapd.args olcLogLevel: none olcPidFile: /var/run/slapd/slapd.pid olcToolThreads: 1 '''''(more LDIF texts)''''' entryUUID: f2a8f568-fa40-102f-8b9d-5d4cbccf32a9 creatorsName: cn=admin,cn=config createTimestamp: 20110413174103Z entryCSN: 20110413174103.641065Z#000000#000#000000 modifiersName: cn=admin,cn=config modifyTimestamp: 20110413174103Z root@easton2:/etc/ldap# '''_''' : As you can see, this generates a pretty large LDIF dump of the contents of the ''cn=config'' directory. Much of it consists of schema information. The LDAP configuration directives are attributes of the directory entries (objects) and most them start with the prefix "olc" ('''O'''pen'''L'''DAP '''C'''onfiguration). Also, some of the objects have names with numbers between curly brackets. This is to compensate for the fact that LDAP databases do not store their contents in any particular order; they are inherently unordered. The numbers constitute a numeric index to ensure a consistent order in the configuration database and thereby preserve all ordering dependencies. The index numbers, however, are generated automatically in the order they are created and usually do not have to be provided. * you can see the configuration by browsing through all the plain-text flat files in ''/etc/ldap/slapd.d/'' and its subdirectories. Note that by default there is no way to do this remotely. If you'd like to browse this configuration using a GUI tool like [http://directory.apache.org/studio/ apache directory studio], don't bother. Debian sets the ''cn=config'' part of the database with a root user of ''cn=admin,cn=config'', but without a password, so you cannot bind to the ''cn=config'' database as anything else than the local root user. Thus you cannot access the ''cn=config'' database by GUI. ===Adding or modifying configuration information=== The simple way of changing anything in the database goes like this: To add a password to the config RootDN, try the ''slappasswd'' command. By default it'll create an SSHA password, but by specifying MD5 as hash (using '' -h {MD5}'') it will create an MD5 encrypted password. The command interactively asks you for the password, and won't show you what you've typed, so be precise: root@easton2:/etc/ldap# '''slappasswd -h {MD5}''' New password: Re-enter new password: {MD5}d1gyCh7gYGjifK4PGh01uw== root@easton2:/etc/ldap# '''_''' Now we determine the DN (Distinguished Name) for the database that contains the RootDN password. To do this we used the following LDAP search command. root@easton2:/etc/ldap# '''ldapsearch -LLL -Y EXTERNAL -H ldapi:/// -b cn=config olcRootDN=cn=admin,cn=config dn olcRootDN olcRootPW''' SASL/EXTERNAL authentication started SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth SASL SSF: 0 dn: olcDatabase={0}config,cn=config olcRootDN: cn=admin,cn=config root@easton2:/etc/ldap# '''_''' Note the olcDatabase line, as it's the result we were looking for; it'll be needed for the ''ldapmodify'' command. Furthermore, note the absence of an olcRootPW entry; this is the starting point for a Debian OpenLDAP server.<br> Now we can stick in a new password. If no password is present, you can use this root@easton2:/etc/ldap# '''''' root@easton2:/etc/ldap# '''_''' ===Adding schemas=== A major task in LDAP maintenance is the addition of LDAP schemas. By default, only 4 schemas will be present in your LDAP server: ''core'', ''cosine'', ''nis'' and ''inetorgperson''. Any other schema, -- say, for Samba -- would need to be added. To this end, you need a schema in LDIF format, which you can then add to the LDAP database using the ''ldapadd'' command. Suppose you have a schema file ''samba.schema'' which you've copied to the ''/etc/ldap/schema'' directory. You'd first convert this to an LDIF file using root@easton2:/etc/ldap/schema# '''slaptest -f samba.schema -F /etc/ldap/schema -s "cn=schema,cn=config"''' ldapadd -x -H ldap://<LDAP SERVER>/ -D "cn=config" -W -f <SCHEMA>.ldif Enter LDAP Password: adding new entry "cn=<SCHEMA>,cn=schema,cn=config" ==OpenLDAP finetuning== To finetune the OpenLDAP configuration, we make some changes to the main configuration file for the OpenLDAP server, ''/etc/ldap/slapd.conf''. Note: make SURE that the permissions on this file are rw-r----- (640) and the owner is ''root:openldap'', so that OpenLDAP can read the configuration, but only you can change it. When changing the configuration of your LDAP server, keep in mind that everything ''above'' the first ''backend hdb'' (or ''backend <something>'') should contain only global directives, and everything under it only backend directives that will apply to all databases that you're going to run under that backend type. In our examples, we're only going to run a single database of a single backend type, so all backend directives will apply to our single database. Nevertheless, you should put your global directives above the backend declaration, and the rest below. 1bd77e204502d063c1a515b109048f8f97714def 2694 2693 2011-06-13T19:29:05Z Saruman! 2 /* OpenLDAP configuration */ finished pw addition wikitext text/x-wiki Note: if you need information on the OpenLDAP version from Debian 5.0, see this page: [[OpenLDAP 2.4.11]] == OpenLDAP installation== Note: we're going to install OpenLDAP on our server as [http://www.openldap.org/doc/admin24/config.html#Local%20Directory%20Service the local directory service], without replication, referrals or other advanced features. Under Debian Squeeze, this is OpenLDAP 2.4.23. ===Standard installation=== Installing OpenLDAP on your Debian server is ridiculously simple. Just make sure your server is up-to-date (''sudo apt-get update'' followed by ''sudo apt-get upgrade''), and then install the two main components for your OpenLDAP server. First off: the LDAP client and utilities sudo apt-get install ldap-utils This will result in the installation of as much as 8 different packages (''ldap-utils'', ''libgcrypt11'', ''libgnutls26'', ''libgpg-error0'', ''libldap-2.4-2'', ''libsasl2-2'', ''libsasl2-modules'', and ''libtasn1-3''). Next the main component of an LDAP server installation, the stand-alone LDAP daemon "slapd" sudo apt-get install slapd This may also install up to 8 packages (''slapd'', ''libltdl7'', ''libperl5.10'', ''libslp1'', ''odbcinst'', ''odbcinst1debian2'', ''psmisc'' and ''unixodbc''). The Debian configuration script will ask you for only one single thing: an administrator password. As always: generate a strong password! After you've provided the password, the LDAP database is created with the administrator name "admin" and as a base directory, something based on your DNS name. Suppose your internal domain is "amber.lan", then the script will generate ''suffix "dc=amber,dc=lan"''<ref>Should you see a third, empty, domain component (''dc='') then this is caused by a trailing dot in your particular DNS name: the DNS root. You might have specified your domain as "amber.lan.". You ''should'' change your domain name to a name without the DNS root, and you ''must'' regenerate your LDAP directory.</ref>. The above method of configuring yields you an LDAP database with only two objects in it. Suppose your DNS name is "easton2.amber.lan", then the two objects are: * a single Organization (o="amber.lan") with Distinguished Name dn="dc=amber,dc=lan" * a single administrator with Common Name cn="admin", and dn="cn=admin,dc=amber,dc=lan" Note, however, that there's ''also'' a second LDAP database, "cn=config", which on your server is located under ''/etc/ldap/slapd.d''. We'll cover what's in it further on. <references/> ===Testing the installation=== After installation of the package, it should automatically have been started, and should now be operational. This can be checked with a utility like ''nmap'': root@easton2:~# '''nmap -p 389 localhost''' Starting Nmap 5.00 ( <nowiki>http://nmap.org</nowiki> ) at 2011-04-13 21:19 CEST Interesting ports on localhost (127.0.0.1): PORT STATE SERVICE 389/tcp open ldap Nmap done: 1 IP address (1 host up) scanned in 0.40 seconds root@easton2:~#'''_''' Another way to test if the LDAP server is functional, is by querying it with the ''ldapsearch'' utility, part of the package ''ldap-utils''. Let's see if we can find the naming context of the LDAP server: root@easton2:~# '''ldapsearch -x -b <nowiki>''</nowiki> -s base '(objectclass=*)' namingContexts''' # extended LDIF # # LDAPv3 # base <> with scope baseObject # filter: (objectclass=*) # requesting: namingContexts # # dn: namingContexts: dc=amber,dc=lan # search result search: 2 result: 0 Success # numResponses: 2 # numEntries: 1 root@easton2:~# '''_''' With this command, we do a search using * basic authentication (instead of one encrypted with SASL), * searching within the LDAP tree from base <nowiki>''</nowiki> (meaning the absolute root of the tree), * looking for base object only (instead of a one-level search, a subtree search, or a children-search), * filtering for objects of any class, * asking for the naming context of the result. The output shows that the server responds; two objects have been considered, but none match the filter (that the object should have an objectClass). Let's now do the same but with authentication, to see if we can bind to the LDAP server. We'll first use an incorrect password, then the correct one: root@easton2:~# '''ldapsearch -W -D "cn=admin,dc=amber,dc=lan"''' Enter LDAP Password: ldap_bind: Invalid credentials (49) root@easton2:~# '''ldapsearch -W -D "cn=admin,dc=amber,dc=lan"''' Enter LDAP Password: # extended LDIF # # LDAPv3 # base <> (default) with scope subtree # filter: (objectclass=*) # requesting: ALL # # search result search: 2 result: 32 No such object # numResponses: 1 root@easton2:~# '''_''' Finally, you could simply install and run a graphical management tool for LDAP servers, like [http://directory.apache.org/studio/ Apache Directory Studio]. Note however that if this check fails, then this could also mean problems with firewalls, network connections et cetera. ===Post-install reconfiguration=== Since the default configuration with the server's DNS domain as LDAP base might not always be the most convenient configuration, you could run the configuration again using ''dpkg-reconfigure slapd''. However, following this procedure is '''only''' necessary if you want to change any of the default installation values like the backend database type or DNS domain name; things like the organization name can be edited with other means, as will be shown later on. To be able to reconfigure the LDAP service, you can run the reconfiguration command ''sudo dpkg-reconfigure slapd''. Contrary to some older versions of Debian, you do not need to manually stop the ''slapd'' daemon, and you don't need to manually remove the old configuration or database (in fact, if you do, then the ''slapd'' package will break, so you cannot easily remove it with APT tools). Interestingly enough, this reconfiguration asks you many ''more'' questions. The answers could look like this: omit OpenLDAP config: no DNS domain name: saruman.biz Organization name: Saruman Administrator passwd: wEt3udes Database backend: HDB DB remove after purge: yes Move old DB: yes Allow LDAPv2: no As you can see, the reconfiguration yields much more configuration options than plain installation - although really you'll probably answer most questions with their default values anyway. The above method of configuring yields you an LDAP database with only two objects in it: * a single Organization (o="Saruman") with Distinguished Name dn="dc=saruman,dc=biz" * a single administrator with Common Name cn="admin", and dn="cn=admin,dc=saruman,dc=biz" Also note that the reconfiguration creates a backup of the "old" LDAP database in a directory with a name like ''/var/backup/unknown-2.4.23-7.ldapdb''; if you just reconfigured after installation, then you probably don't need this backup, so you can remove it. The database that your OpenLDAP server uses is a standard Berkeley DB (BDB/HDB) database. Now we most likely will require some other databases as well in our server setup, something modern like PostgreSQL or MySQL - so why don't we configure our OpenLDAP to use this same database as well? For the answer, see [http://www.openldap.org/doc/admin24/intro.html#LDAP%20vs%20RDBMS here] - in short, the LDAP tree structure does not lend itself very well to inclusion in a modern relational database. Thus, we advise to stick with the Berkeley database provided with OpenLDAP. Now, for the database backend, we have the choice between two almost identical flavours: * the ''bdb'' backend used to be the recommended primary backend for a normal slapd database. It uses the Oracle Berkeley DB package, referred to as ''BDB'', to store data. It makes extensive use of indexing and caching to speed data access. * the ''hdb'' backend is a variant of the ''bdb'' backend that uses a hierarchical database layout which supports subtree renames. It is otherwise identical to the ''bdb'' behavior, and all the same configuration options apply. In Debian 6.0 "Squeeze" with OpenLDAP 2.4.23, HDB is the default backend. ==OpenLDAP configuration== <small>(text from http://www.rjsystems.nl/en/2100-d6-openldap-provider.php)</small> As of OpenLDAP 2.4.23-3, the ''slapd'' runtime configuration is fully LDAP-enabled. The default is to manage it using the standard LDAP operations with data in LDIF. The old ''slapd.conf'' format is still supported, but since that file must now be converted to the new ''slapd-config'' format to allow runtime changes to be saved, it seems likely that the developers will eventually phase it out. Therefore, we'll focus only on the new configuration method, the main advantage of which is that any changes made are immediately active, so it is no longer necessary to restart ''slapd'' after making configuration changes. The new configuration format uses a slapd backend database that is found in the ''/etc/ldap/slapd.d/'' directory. The configuration is stored as a special LDAP directory with a predefined schema and DIT, the root of which is called ''cn=config''. If you go look there, you'll find that most parts of this LDAP directory consist of editable flat files. ===Check the current LDAP configuration=== From the command line, there really are several ways to check the current LDAP configuration: * from the server itself, you can use the trusty ''ldapsearch'' command, running under root: this'll authenticate with user ID 0. Filtering only for distinguished names: root@easton2:/etc/ldap# '''ldapsearch -LLL -Y EXTERNAL -H ldapi:/// -b cn=config dn''' SASL/EXTERNAL authentication started SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth SASL SSF: 0 dn: cn=config dn: cn=module{0},cn=config dn: cn=schema,cn=config dn: cn={0}core,cn=schema,cn=config dn: cn={1}cosine,cn=schema,cn=config dn: cn={2}nis,cn=schema,cn=config dn: cn={3}inetorgperson,cn=schema,cn=config dn: olcBackend={0}hdb,cn=config dn: olcDatabase={-1}frontend,cn=config dn: olcDatabase={0}config,cn=config dn: olcDatabase={1}hdb,cn=config root@easton2:/etc/ldap# '''_''' * to get an idea of what the ''cn=config'' database looks like ''within LDAP itself'', you can run this command: root@easton2:/etc/ldap# '''slapcat -b cn=config''' dn: cn=config objectClass: olcGlobal cn: config olcArgsFile: /var/run/slapd/slapd.args olcLogLevel: none olcPidFile: /var/run/slapd/slapd.pid olcToolThreads: 1 '''''(more LDIF texts)''''' entryUUID: f2a8f568-fa40-102f-8b9d-5d4cbccf32a9 creatorsName: cn=admin,cn=config createTimestamp: 20110413174103Z entryCSN: 20110413174103.641065Z#000000#000#000000 modifiersName: cn=admin,cn=config modifyTimestamp: 20110413174103Z root@easton2:/etc/ldap# '''_''' : As you can see, this generates a pretty large LDIF dump of the contents of the ''cn=config'' directory. Much of it consists of schema information. The LDAP configuration directives are attributes of the directory entries (objects) and most them start with the prefix "olc" ('''O'''pen'''L'''DAP '''C'''onfiguration). Also, some of the objects have names with numbers between curly brackets. This is to compensate for the fact that LDAP databases do not store their contents in any particular order; they are inherently unordered. The numbers constitute a numeric index to ensure a consistent order in the configuration database and thereby preserve all ordering dependencies. The index numbers, however, are generated automatically in the order they are created and usually do not have to be provided. * you can see the configuration by browsing through all the plain-text flat files in ''/etc/ldap/slapd.d/'' and its subdirectories. Note that by default there is no way to do this remotely. If you'd like to browse this configuration using a GUI tool like [http://directory.apache.org/studio/ apache directory studio], don't bother. Debian sets the ''cn=config'' part of the database with a root user of ''cn=admin,cn=config'', but without a password, so you cannot bind to the ''cn=config'' database as anything else than the local root user. Thus you cannot access the ''cn=config'' database by GUI. ===Adding or modifying the cn=config admin password=== To add a password to the config RootDN, we first must generate one; for this we can use the ''slappasswd'' command. By default it'll create an SSHA password, but by specifying MD5 as hash (using '' -h {MD5}'') it will create an MD5 encrypted password. The command interactively asks you for the password, and won't show you what you've typed, so be precise: root@easton2:/etc/ldap# '''slappasswd -h {MD5}''' New password: Re-enter new password: {MD5}d1gyCh7gYGjifK4PGh01uw== root@easton2:/etc/ldap# '''_''' Now we determine the DN (Distinguished Name) for the database that contains the RootDN password. We'll also check if there isn't a password in place already. To do this we used the following LDAP search command. root@easton2:/etc/ldap# '''ldapsearch -LLL -Y EXTERNAL -H ldapi:/// -b cn=config olcRootDN=cn=admin,cn=config dn olcRootDN olcRootPW''' SASL/EXTERNAL authentication started SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth SASL SSF: 0 dn: olcDatabase={0}config,cn=config olcRootDN: cn=admin,cn=config root@easton2:/etc/ldap# '''_''' Note the olcDatabase line, as it's the result we were looking for; it'll be needed for the ''ldapmodify'' command. Furthermore, note the absence of an olcRootPW entry; this is the starting point for a Debian OpenLDAP server.<br> Now we can stick in a new password. If no password is present, you can use this interactive procedure: root@easton2:/etc/ldap# '''ldapmodify -Y EXTERNAL -H ldapi:///''' SASL/EXTERNAL authentication started SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth SASL SSF: 0 '''dn: olcDatabase={0}config,cn=config''' '''add: olcRootPW''' '''olcRootPW: {MD5}d5axCh6gYGjhfK4PGs09us==''' modifying entry "olcDatabase={0}config,cn=config" root@easton2:/etc/ldap# '''_''' Note that as soon as you put in an empty line, the entry gets added. Also note that you have to use CTRL-D to end this interactive mode. Finally, note that if a password was already in place, we could still use the above, but we'd interactively feed the second line as '''replace: olcRootPW'''. We could also put the password in an ldif file, and feed that to the server. To this end, we'd create an ldif file with the following content: (@@@ test this later @@@) ===Adding or modifying configuration information=== The simple way of changing anything in the database goes like this: ===Adding schemas=== A major task in LDAP maintenance is the addition of LDAP schemas. By default, only 4 schemas will be present in your LDAP server: ''core'', ''cosine'', ''nis'' and ''inetorgperson''. Any other schema, -- say, for Samba -- would need to be added. To this end, you need a schema in LDIF format, which you can then add to the LDAP database using the ''ldapadd'' command. Suppose you have a schema file ''samba.schema'' which you've copied to the ''/etc/ldap/schema'' directory. You'd first convert this to an LDIF file using root@easton2:/etc/ldap/schema# '''slaptest -f samba.schema -F /etc/ldap/schema -s "cn=schema,cn=config"''' ldapadd -x -H ldap://<LDAP SERVER>/ -D "cn=config" -W -f <SCHEMA>.ldif Enter LDAP Password: adding new entry "cn=<SCHEMA>,cn=schema,cn=config" ==OpenLDAP finetuning== To finetune the OpenLDAP configuration, we make some changes to the main configuration file for the OpenLDAP server, ''/etc/ldap/slapd.conf''. Note: make SURE that the permissions on this file are rw-r----- (640) and the owner is ''root:openldap'', so that OpenLDAP can read the configuration, but only you can change it. When changing the configuration of your LDAP server, keep in mind that everything ''above'' the first ''backend hdb'' (or ''backend <something>'') should contain only global directives, and everything under it only backend directives that will apply to all databases that you're going to run under that backend type. In our examples, we're only going to run a single database of a single backend type, so all backend directives will apply to our single database. Nevertheless, you should put your global directives above the backend declaration, and the rest below. 996e0e4d990a5394c8822f0ac651826eee128fd4 2695 2694 2011-06-13T19:31:44Z Saruman! 2 /* Adding or modifying the cn=config admin password */ fixed password itself wikitext text/x-wiki Note: if you need information on the OpenLDAP version from Debian 5.0, see this page: [[OpenLDAP 2.4.11]] == OpenLDAP installation== Note: we're going to install OpenLDAP on our server as [http://www.openldap.org/doc/admin24/config.html#Local%20Directory%20Service the local directory service], without replication, referrals or other advanced features. Under Debian Squeeze, this is OpenLDAP 2.4.23. ===Standard installation=== Installing OpenLDAP on your Debian server is ridiculously simple. Just make sure your server is up-to-date (''sudo apt-get update'' followed by ''sudo apt-get upgrade''), and then install the two main components for your OpenLDAP server. First off: the LDAP client and utilities sudo apt-get install ldap-utils This will result in the installation of as much as 8 different packages (''ldap-utils'', ''libgcrypt11'', ''libgnutls26'', ''libgpg-error0'', ''libldap-2.4-2'', ''libsasl2-2'', ''libsasl2-modules'', and ''libtasn1-3''). Next the main component of an LDAP server installation, the stand-alone LDAP daemon "slapd" sudo apt-get install slapd This may also install up to 8 packages (''slapd'', ''libltdl7'', ''libperl5.10'', ''libslp1'', ''odbcinst'', ''odbcinst1debian2'', ''psmisc'' and ''unixodbc''). The Debian configuration script will ask you for only one single thing: an administrator password. As always: generate a strong password! After you've provided the password, the LDAP database is created with the administrator name "admin" and as a base directory, something based on your DNS name. Suppose your internal domain is "amber.lan", then the script will generate ''suffix "dc=amber,dc=lan"''<ref>Should you see a third, empty, domain component (''dc='') then this is caused by a trailing dot in your particular DNS name: the DNS root. You might have specified your domain as "amber.lan.". You ''should'' change your domain name to a name without the DNS root, and you ''must'' regenerate your LDAP directory.</ref>. The above method of configuring yields you an LDAP database with only two objects in it. Suppose your DNS name is "easton2.amber.lan", then the two objects are: * a single Organization (o="amber.lan") with Distinguished Name dn="dc=amber,dc=lan" * a single administrator with Common Name cn="admin", and dn="cn=admin,dc=amber,dc=lan" Note, however, that there's ''also'' a second LDAP database, "cn=config", which on your server is located under ''/etc/ldap/slapd.d''. We'll cover what's in it further on. <references/> ===Testing the installation=== After installation of the package, it should automatically have been started, and should now be operational. This can be checked with a utility like ''nmap'': root@easton2:~# '''nmap -p 389 localhost''' Starting Nmap 5.00 ( <nowiki>http://nmap.org</nowiki> ) at 2011-04-13 21:19 CEST Interesting ports on localhost (127.0.0.1): PORT STATE SERVICE 389/tcp open ldap Nmap done: 1 IP address (1 host up) scanned in 0.40 seconds root@easton2:~#'''_''' Another way to test if the LDAP server is functional, is by querying it with the ''ldapsearch'' utility, part of the package ''ldap-utils''. Let's see if we can find the naming context of the LDAP server: root@easton2:~# '''ldapsearch -x -b <nowiki>''</nowiki> -s base '(objectclass=*)' namingContexts''' # extended LDIF # # LDAPv3 # base <> with scope baseObject # filter: (objectclass=*) # requesting: namingContexts # # dn: namingContexts: dc=amber,dc=lan # search result search: 2 result: 0 Success # numResponses: 2 # numEntries: 1 root@easton2:~# '''_''' With this command, we do a search using * basic authentication (instead of one encrypted with SASL), * searching within the LDAP tree from base <nowiki>''</nowiki> (meaning the absolute root of the tree), * looking for base object only (instead of a one-level search, a subtree search, or a children-search), * filtering for objects of any class, * asking for the naming context of the result. The output shows that the server responds; two objects have been considered, but none match the filter (that the object should have an objectClass). Let's now do the same but with authentication, to see if we can bind to the LDAP server. We'll first use an incorrect password, then the correct one: root@easton2:~# '''ldapsearch -W -D "cn=admin,dc=amber,dc=lan"''' Enter LDAP Password: ldap_bind: Invalid credentials (49) root@easton2:~# '''ldapsearch -W -D "cn=admin,dc=amber,dc=lan"''' Enter LDAP Password: # extended LDIF # # LDAPv3 # base <> (default) with scope subtree # filter: (objectclass=*) # requesting: ALL # # search result search: 2 result: 32 No such object # numResponses: 1 root@easton2:~# '''_''' Finally, you could simply install and run a graphical management tool for LDAP servers, like [http://directory.apache.org/studio/ Apache Directory Studio]. Note however that if this check fails, then this could also mean problems with firewalls, network connections et cetera. ===Post-install reconfiguration=== Since the default configuration with the server's DNS domain as LDAP base might not always be the most convenient configuration, you could run the configuration again using ''dpkg-reconfigure slapd''. However, following this procedure is '''only''' necessary if you want to change any of the default installation values like the backend database type or DNS domain name; things like the organization name can be edited with other means, as will be shown later on. To be able to reconfigure the LDAP service, you can run the reconfiguration command ''sudo dpkg-reconfigure slapd''. Contrary to some older versions of Debian, you do not need to manually stop the ''slapd'' daemon, and you don't need to manually remove the old configuration or database (in fact, if you do, then the ''slapd'' package will break, so you cannot easily remove it with APT tools). Interestingly enough, this reconfiguration asks you many ''more'' questions. The answers could look like this: omit OpenLDAP config: no DNS domain name: saruman.biz Organization name: Saruman Administrator passwd: wEt3udes Database backend: HDB DB remove after purge: yes Move old DB: yes Allow LDAPv2: no As you can see, the reconfiguration yields much more configuration options than plain installation - although really you'll probably answer most questions with their default values anyway. The above method of configuring yields you an LDAP database with only two objects in it: * a single Organization (o="Saruman") with Distinguished Name dn="dc=saruman,dc=biz" * a single administrator with Common Name cn="admin", and dn="cn=admin,dc=saruman,dc=biz" Also note that the reconfiguration creates a backup of the "old" LDAP database in a directory with a name like ''/var/backup/unknown-2.4.23-7.ldapdb''; if you just reconfigured after installation, then you probably don't need this backup, so you can remove it. The database that your OpenLDAP server uses is a standard Berkeley DB (BDB/HDB) database. Now we most likely will require some other databases as well in our server setup, something modern like PostgreSQL or MySQL - so why don't we configure our OpenLDAP to use this same database as well? For the answer, see [http://www.openldap.org/doc/admin24/intro.html#LDAP%20vs%20RDBMS here] - in short, the LDAP tree structure does not lend itself very well to inclusion in a modern relational database. Thus, we advise to stick with the Berkeley database provided with OpenLDAP. Now, for the database backend, we have the choice between two almost identical flavours: * the ''bdb'' backend used to be the recommended primary backend for a normal slapd database. It uses the Oracle Berkeley DB package, referred to as ''BDB'', to store data. It makes extensive use of indexing and caching to speed data access. * the ''hdb'' backend is a variant of the ''bdb'' backend that uses a hierarchical database layout which supports subtree renames. It is otherwise identical to the ''bdb'' behavior, and all the same configuration options apply. In Debian 6.0 "Squeeze" with OpenLDAP 2.4.23, HDB is the default backend. ==OpenLDAP configuration== <small>(text from http://www.rjsystems.nl/en/2100-d6-openldap-provider.php)</small> As of OpenLDAP 2.4.23-3, the ''slapd'' runtime configuration is fully LDAP-enabled. The default is to manage it using the standard LDAP operations with data in LDIF. The old ''slapd.conf'' format is still supported, but since that file must now be converted to the new ''slapd-config'' format to allow runtime changes to be saved, it seems likely that the developers will eventually phase it out. Therefore, we'll focus only on the new configuration method, the main advantage of which is that any changes made are immediately active, so it is no longer necessary to restart ''slapd'' after making configuration changes. The new configuration format uses a slapd backend database that is found in the ''/etc/ldap/slapd.d/'' directory. The configuration is stored as a special LDAP directory with a predefined schema and DIT, the root of which is called ''cn=config''. If you go look there, you'll find that most parts of this LDAP directory consist of editable flat files. ===Check the current LDAP configuration=== From the command line, there really are several ways to check the current LDAP configuration: * from the server itself, you can use the trusty ''ldapsearch'' command, running under root: this'll authenticate with user ID 0. Filtering only for distinguished names: root@easton2:/etc/ldap# '''ldapsearch -LLL -Y EXTERNAL -H ldapi:/// -b cn=config dn''' SASL/EXTERNAL authentication started SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth SASL SSF: 0 dn: cn=config dn: cn=module{0},cn=config dn: cn=schema,cn=config dn: cn={0}core,cn=schema,cn=config dn: cn={1}cosine,cn=schema,cn=config dn: cn={2}nis,cn=schema,cn=config dn: cn={3}inetorgperson,cn=schema,cn=config dn: olcBackend={0}hdb,cn=config dn: olcDatabase={-1}frontend,cn=config dn: olcDatabase={0}config,cn=config dn: olcDatabase={1}hdb,cn=config root@easton2:/etc/ldap# '''_''' * to get an idea of what the ''cn=config'' database looks like ''within LDAP itself'', you can run this command: root@easton2:/etc/ldap# '''slapcat -b cn=config''' dn: cn=config objectClass: olcGlobal cn: config olcArgsFile: /var/run/slapd/slapd.args olcLogLevel: none olcPidFile: /var/run/slapd/slapd.pid olcToolThreads: 1 '''''(more LDIF texts)''''' entryUUID: f2a8f568-fa40-102f-8b9d-5d4cbccf32a9 creatorsName: cn=admin,cn=config createTimestamp: 20110413174103Z entryCSN: 20110413174103.641065Z#000000#000#000000 modifiersName: cn=admin,cn=config modifyTimestamp: 20110413174103Z root@easton2:/etc/ldap# '''_''' : As you can see, this generates a pretty large LDIF dump of the contents of the ''cn=config'' directory. Much of it consists of schema information. The LDAP configuration directives are attributes of the directory entries (objects) and most them start with the prefix "olc" ('''O'''pen'''L'''DAP '''C'''onfiguration). Also, some of the objects have names with numbers between curly brackets. This is to compensate for the fact that LDAP databases do not store their contents in any particular order; they are inherently unordered. The numbers constitute a numeric index to ensure a consistent order in the configuration database and thereby preserve all ordering dependencies. The index numbers, however, are generated automatically in the order they are created and usually do not have to be provided. * you can see the configuration by browsing through all the plain-text flat files in ''/etc/ldap/slapd.d/'' and its subdirectories. Note that by default there is no way to do this remotely. If you'd like to browse this configuration using a GUI tool like [http://directory.apache.org/studio/ apache directory studio], don't bother. Debian sets the ''cn=config'' part of the database with a root user of ''cn=admin,cn=config'', but without a password, so you cannot bind to the ''cn=config'' database as anything else than the local root user. Thus you cannot access the ''cn=config'' database by GUI. ===Adding or modifying the cn=config admin password=== To add a password to the config RootDN, we first must generate one; for this we can use the ''slappasswd'' command. By default it'll create an SSHA password, but by specifying MD5 as hash (using '' -h {MD5}'') it will create an MD5 encrypted password. The command interactively asks you for the password, and won't show you what you've typed, so be precise: root@easton2:/etc/ldap# '''slappasswd -h {MD5}''' New password: Re-enter new password: {MD5}d5axCh6gYGjhfK4PGs09us== root@easton2:/etc/ldap# '''_''' Now we determine the DN (Distinguished Name) for the database that contains the RootDN password. We'll also check if there isn't a password in place already. To do this we used the following LDAP search command. root@easton2:/etc/ldap# '''ldapsearch -LLL -Y EXTERNAL -H ldapi:/// -b cn=config olcRootDN=cn=admin,cn=config dn olcRootDN olcRootPW''' SASL/EXTERNAL authentication started SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth SASL SSF: 0 dn: olcDatabase={0}config,cn=config olcRootDN: cn=admin,cn=config root@easton2:/etc/ldap# '''_''' Note the olcDatabase line, as it's the result we were looking for; it'll be needed for the ''ldapmodify'' command. Furthermore, note the absence of an olcRootPW entry; this is the starting point for a Debian OpenLDAP server.<br> Now we can stick in a new password. If no password is present, you can use this interactive procedure: root@easton2:/etc/ldap# '''ldapmodify -Y EXTERNAL -H ldapi:///''' SASL/EXTERNAL authentication started SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth SASL SSF: 0 '''dn: olcDatabase={0}config,cn=config''' '''add: olcRootPW''' '''olcRootPW: {MD5}d5axCh6gYGjhfK4PGs09us==''' modifying entry "olcDatabase={0}config,cn=config" root@easton2:/etc/ldap# '''_''' Note the following points: * we use the olcDatabase location as found with the previous ''ldapsearch'' command; * we input the MD5 password that we've generated previously; * as soon as you put in an empty line, the entry gets added; * you have to use CTRL-D to end this interactive mode; * if a password was already in place, we could still use the above, but we'd interactively feed the second line as '''replace: olcRootPW'''. We could also put the password in an ldif file, and feed that to the server. To this end, we'd create an ldif file with the following content: (@@@ test this later @@@) ===Adding or modifying configuration information=== The simple way of changing anything in the database goes like this: ===Adding schemas=== A major task in LDAP maintenance is the addition of LDAP schemas. By default, only 4 schemas will be present in your LDAP server: ''core'', ''cosine'', ''nis'' and ''inetorgperson''. Any other schema, -- say, for Samba -- would need to be added. To this end, you need a schema in LDIF format, which you can then add to the LDAP database using the ''ldapadd'' command. Suppose you have a schema file ''samba.schema'' which you've copied to the ''/etc/ldap/schema'' directory. You'd first convert this to an LDIF file using root@easton2:/etc/ldap/schema# '''slaptest -f samba.schema -F /etc/ldap/schema -s "cn=schema,cn=config"''' ldapadd -x -H ldap://<LDAP SERVER>/ -D "cn=config" -W -f <SCHEMA>.ldif Enter LDAP Password: adding new entry "cn=<SCHEMA>,cn=schema,cn=config" ==OpenLDAP finetuning== To finetune the OpenLDAP configuration, we make some changes to the main configuration file for the OpenLDAP server, ''/etc/ldap/slapd.conf''. Note: make SURE that the permissions on this file are rw-r----- (640) and the owner is ''root:openldap'', so that OpenLDAP can read the configuration, but only you can change it. When changing the configuration of your LDAP server, keep in mind that everything ''above'' the first ''backend hdb'' (or ''backend <something>'') should contain only global directives, and everything under it only backend directives that will apply to all databases that you're going to run under that backend type. In our examples, we're only going to run a single database of a single backend type, so all backend directives will apply to our single database. Nevertheless, you should put your global directives above the backend declaration, and the rest below. bd6bc733b31e563573452b0ea0884e5893aa248a 2696 2695 2011-06-14T17:32:25Z Saruman! 2 added passwordadditionldif wikitext text/x-wiki Note: if you need information on the OpenLDAP version from Debian 5.0, see this page: [[OpenLDAP 2.4.11]] == OpenLDAP installation== Note: we're going to install OpenLDAP on our server as [http://www.openldap.org/doc/admin24/config.html#Local%20Directory%20Service the local directory service], without replication, referrals or other advanced features. Under Debian Squeeze, this is OpenLDAP 2.4.23. ===Standard installation=== Installing OpenLDAP on your Debian server is ridiculously simple. Just make sure your server is up-to-date (''sudo apt-get update'' followed by ''sudo apt-get upgrade''), and then install the two main components for your OpenLDAP server. First off: the LDAP client and utilities sudo apt-get install ldap-utils This will result in the installation of as much as 8 different packages (''ldap-utils'', ''libgcrypt11'', ''libgnutls26'', ''libgpg-error0'', ''libldap-2.4-2'', ''libsasl2-2'', ''libsasl2-modules'', and ''libtasn1-3''). Next the main component of an LDAP server installation, the stand-alone LDAP daemon "slapd" sudo apt-get install slapd This may also install up to 8 packages (''slapd'', ''libltdl7'', ''libperl5.10'', ''libslp1'', ''odbcinst'', ''odbcinst1debian2'', ''psmisc'' and ''unixodbc''). The Debian configuration script will ask you for only one single thing: an administrator password. As always: generate a strong password! After you've provided the password, the LDAP database is created with the administrator name "admin" and as a base directory, something based on your DNS name. Suppose your internal domain is "amber.lan", then the script will generate ''suffix "dc=amber,dc=lan"''<ref>Should you see a third, empty, domain component (''dc='') then this is caused by a trailing dot in your particular DNS name: the DNS root. You might have specified your domain as "amber.lan.". You ''should'' change your domain name to a name without the DNS root, and you ''must'' regenerate your LDAP directory.</ref>. The above method of configuring yields you an LDAP database with only two objects in it. Suppose your DNS name is "easton2.amber.lan", then the two objects are: * a single Organization (o="amber.lan") with Distinguished Name dn="dc=amber,dc=lan" * a single administrator with Common Name cn="admin", and dn="cn=admin,dc=amber,dc=lan" Note, however, that there's ''also'' a second LDAP database, "cn=config", which on your server is located under ''/etc/ldap/slapd.d''. We'll cover what's in it further on. <references/> ===Testing the installation=== After installation of the package, it should automatically have been started, and should now be operational. This can be checked with a utility like ''nmap'': root@easton2:~# '''nmap -p 389 localhost''' Starting Nmap 5.00 ( <nowiki>http://nmap.org</nowiki> ) at 2011-04-13 21:19 CEST Interesting ports on localhost (127.0.0.1): PORT STATE SERVICE 389/tcp open ldap Nmap done: 1 IP address (1 host up) scanned in 0.40 seconds root@easton2:~#'''_''' Another way to test if the LDAP server is functional, is by querying it with the ''ldapsearch'' utility, part of the package ''ldap-utils''. Let's see if we can find the naming context of the LDAP server: root@easton2:~# '''ldapsearch -x -b <nowiki>''</nowiki> -s base '(objectclass=*)' namingContexts''' # extended LDIF # # LDAPv3 # base <> with scope baseObject # filter: (objectclass=*) # requesting: namingContexts # # dn: namingContexts: dc=amber,dc=lan # search result search: 2 result: 0 Success # numResponses: 2 # numEntries: 1 root@easton2:~# '''_''' With this command, we do a search using * basic authentication (instead of one encrypted with SASL), * searching within the LDAP tree from base <nowiki>''</nowiki> (meaning the absolute root of the tree), * looking for base object only (instead of a one-level search, a subtree search, or a children-search), * filtering for objects of any class, * asking for the naming context of the result. The output shows that the server responds; two objects have been considered, but none match the filter (that the object should have an objectClass). Let's now do the same but with authentication, to see if we can bind to the LDAP server. We'll first use an incorrect password, then the correct one: root@easton2:~# '''ldapsearch -W -D "cn=admin,dc=amber,dc=lan"''' Enter LDAP Password: ldap_bind: Invalid credentials (49) root@easton2:~# '''ldapsearch -W -D "cn=admin,dc=amber,dc=lan"''' Enter LDAP Password: # extended LDIF # # LDAPv3 # base <> (default) with scope subtree # filter: (objectclass=*) # requesting: ALL # # search result search: 2 result: 32 No such object # numResponses: 1 root@easton2:~# '''_''' Finally, you could simply install and run a graphical management tool for LDAP servers, like [http://directory.apache.org/studio/ Apache Directory Studio]. Note however that if this check fails, then this could also mean problems with firewalls, network connections et cetera. ===Post-install reconfiguration=== Since the default configuration with the server's DNS domain as LDAP base might not always be the most convenient configuration, you could run the configuration again using ''dpkg-reconfigure slapd''. However, following this procedure is '''only''' necessary if you want to change any of the default installation values like the backend database type or DNS domain name; things like the organization name can be edited with other means, as will be shown later on. To be able to reconfigure the LDAP service, you can run the reconfiguration command ''sudo dpkg-reconfigure slapd''. Contrary to some older versions of Debian, you do not need to manually stop the ''slapd'' daemon, and you don't need to manually remove the old configuration or database (in fact, if you do, then the ''slapd'' package will break, so you cannot easily remove it with APT tools). Interestingly enough, this reconfiguration asks you many ''more'' questions. The answers could look like this: omit OpenLDAP config: no DNS domain name: saruman.biz Organization name: Saruman Administrator passwd: wEt3udes Database backend: HDB DB remove after purge: yes Move old DB: yes Allow LDAPv2: no As you can see, the reconfiguration yields much more configuration options than plain installation - although really you'll probably answer most questions with their default values anyway. The above method of configuring yields you an LDAP database with only two objects in it: * a single Organization (o="Saruman") with Distinguished Name dn="dc=saruman,dc=biz" * a single administrator with Common Name cn="admin", and dn="cn=admin,dc=saruman,dc=biz" Also note that the reconfiguration creates a backup of the "old" LDAP database in a directory with a name like ''/var/backup/unknown-2.4.23-7.ldapdb''; if you just reconfigured after installation, then you probably don't need this backup, so you can remove it. The database that your OpenLDAP server uses is a standard Berkeley DB (BDB/HDB) database. Now we most likely will require some other databases as well in our server setup, something modern like PostgreSQL or MySQL - so why don't we configure our OpenLDAP to use this same database as well? For the answer, see [http://www.openldap.org/doc/admin24/intro.html#LDAP%20vs%20RDBMS here] - in short, the LDAP tree structure does not lend itself very well to inclusion in a modern relational database. Thus, we advise to stick with the Berkeley database provided with OpenLDAP. Now, for the database backend, we have the choice between two almost identical flavours: * the ''bdb'' backend used to be the recommended primary backend for a normal slapd database. It uses the Oracle Berkeley DB package, referred to as ''BDB'', to store data. It makes extensive use of indexing and caching to speed data access. * the ''hdb'' backend is a variant of the ''bdb'' backend that uses a hierarchical database layout which supports subtree renames. It is otherwise identical to the ''bdb'' behavior, and all the same configuration options apply. In Debian 6.0 "Squeeze" with OpenLDAP 2.4.23, HDB is the default backend. ==OpenLDAP configuration== <small>(text from http://www.rjsystems.nl/en/2100-d6-openldap-provider.php)</small> As of OpenLDAP 2.4.23-3, the ''slapd'' runtime configuration is fully LDAP-enabled. The default is to manage it using the standard LDAP operations with data in LDIF. The old ''slapd.conf'' format is still supported, but since that file must now be converted to the new ''slapd-config'' format to allow runtime changes to be saved, it seems likely that the developers will eventually phase it out. Therefore, we'll focus only on the new configuration method, the main advantage of which is that any changes made are immediately active, so it is no longer necessary to restart ''slapd'' after making configuration changes. The new configuration format uses a slapd backend database that is found in the ''/etc/ldap/slapd.d/'' directory. The configuration is stored as a special LDAP directory with a predefined schema and DIT, the root of which is called ''cn=config''. If you go look there, you'll find that most parts of this LDAP directory consist of editable flat files. ===Check the current LDAP configuration=== From the command line, there really are several ways to check the current LDAP configuration: * from the server itself, you can use the trusty ''ldapsearch'' command, running under root: this'll authenticate with user ID 0. Filtering only for distinguished names: root@easton2:/etc/ldap# '''ldapsearch -LLL -Y EXTERNAL -H ldapi:/// -b cn=config dn''' SASL/EXTERNAL authentication started SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth SASL SSF: 0 dn: cn=config dn: cn=module{0},cn=config dn: cn=schema,cn=config dn: cn={0}core,cn=schema,cn=config dn: cn={1}cosine,cn=schema,cn=config dn: cn={2}nis,cn=schema,cn=config dn: cn={3}inetorgperson,cn=schema,cn=config dn: olcBackend={0}hdb,cn=config dn: olcDatabase={-1}frontend,cn=config dn: olcDatabase={0}config,cn=config dn: olcDatabase={1}hdb,cn=config root@easton2:/etc/ldap# '''_''' * to get an idea of what the ''cn=config'' database looks like ''within LDAP itself'', you can run this command: root@easton2:/etc/ldap# '''slapcat -b cn=config''' dn: cn=config objectClass: olcGlobal cn: config olcArgsFile: /var/run/slapd/slapd.args olcLogLevel: none olcPidFile: /var/run/slapd/slapd.pid olcToolThreads: 1 '''''(more LDIF texts)''''' entryUUID: f2a8f568-fa40-102f-8b9d-5d4cbccf32a9 creatorsName: cn=admin,cn=config createTimestamp: 20110413174103Z entryCSN: 20110413174103.641065Z#000000#000#000000 modifiersName: cn=admin,cn=config modifyTimestamp: 20110413174103Z root@easton2:/etc/ldap# '''_''' : As you can see, this generates a pretty large LDIF dump of the contents of the ''cn=config'' directory. Much of it consists of schema information. The LDAP configuration directives are attributes of the directory entries (objects) and most them start with the prefix "olc" ('''O'''pen'''L'''DAP '''C'''onfiguration). Also, some of the objects have names with numbers between curly brackets. This is to compensate for the fact that LDAP databases do not store their contents in any particular order; they are inherently unordered. The numbers constitute a numeric index to ensure a consistent order in the configuration database and thereby preserve all ordering dependencies. The index numbers, however, are generated automatically in the order they are created and usually do not have to be provided. * you can see the configuration by browsing through all the plain-text flat files in ''/etc/ldap/slapd.d/'' and its subdirectories. Note that by default there is no way to do this remotely. If you'd like to browse this configuration using a GUI tool like [http://directory.apache.org/studio/ apache directory studio], don't bother. Debian sets the ''cn=config'' part of the database with a root user of ''cn=admin,cn=config'', but without a password, so you cannot bind to the ''cn=config'' database as anything else than the local root user. Thus you cannot access the ''cn=config'' database by GUI. ===Adding or modifying the cn=config admin password=== To add a password to the config RootDN, we first must generate one; for this we can use the ''slappasswd'' command. By default it'll create an SSHA password, but by specifying MD5 as hash (using '' -h {MD5}'') it will create an MD5 encrypted password. The command interactively asks you for the password, and won't show you what you've typed, so be precise: root@easton2:/etc/ldap# '''slappasswd -h {MD5}''' New password: Re-enter new password: {MD5}d5axCh6gYGjhfK4PGs09us== root@easton2:/etc/ldap# '''_''' Now we determine the DN (Distinguished Name) for the database that contains the RootDN password. We'll also check if there isn't a password in place already. To do this we used the following LDAP search command. root@easton2:/etc/ldap# '''ldapsearch -LLL -Y EXTERNAL -H ldapi:/// -b cn=config olcRootDN=cn=admin,cn=config dn olcRootDN olcRootPW''' SASL/EXTERNAL authentication started SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth SASL SSF: 0 dn: olcDatabase={0}config,cn=config olcRootDN: cn=admin,cn=config root@easton2:/etc/ldap# '''_''' Note the olcDatabase line, as it's the result we were looking for; it'll be needed for the ''ldapmodify'' command. Furthermore, note the absence of an olcRootPW entry; this is the starting point for a Debian OpenLDAP server.<br> Now we can stick in a new password. If no password is present, you can use this interactive procedure: root@easton2:/etc/ldap# '''ldapmodify -Y EXTERNAL -H ldapi:///''' SASL/EXTERNAL authentication started SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth SASL SSF: 0 '''dn: olcDatabase={0}config,cn=config''' '''add: olcRootPW''' '''olcRootPW: {MD5}d5axCh6gYGjhfK4PGs09us==''' modifying entry "olcDatabase={0}config,cn=config" root@easton2:/etc/ldap# '''_''' Note the following points: * we use the olcDatabase location as found with the previous ''ldapsearch'' command; * we input the MD5 password that we've generated previously; * as soon as you put in an empty line, the entry gets added; * you have to use CTRL-D to end this interactive mode; * if a password was already in place, we could still use the above, but we'd interactively feed the second line as '''replace: olcRootPW'''. We could also put the password in an ldif file, and feed that to the server. To this end, we'd create an ldif file with the following content: dn: olcDatabase={0}config,cn=config changetype: modify add: olcRootPW olcRootPW: {MD5}d5axCh6gYGjhfK4PGs09us== If this file is called ''addpassword.ldif'' and is created in ''/tmp'', then the addition can be executed using root@easton2:/etc/ldap# '''ldapmodify -Y EXTERNAL -H ldapi:/// -f /tmp/addpassword.ldif''' SASL/EXTERNAL authentication started SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth SASL SSF: 0 modifying entry "olcDatabase={0}config,cn=config" root@easton2:/tmp# '''_''' ===Adding or modifying configuration information=== The simple way of changing anything in the database goes like this: ===Adding schemas=== A major task in LDAP maintenance is the addition of LDAP schemas. By default, only 4 schemas will be present in your LDAP server: ''core'', ''cosine'', ''nis'' and ''inetorgperson''. Any other schema, -- say, for Samba -- would need to be added. To this end, you need a schema in LDIF format, which you can then add to the LDAP database using the ''ldapadd'' command. Suppose you have a schema file ''samba.schema'' which you've copied to the ''/etc/ldap/schema'' directory. You'd first convert this to an LDIF file using root@easton2:/etc/ldap/schema# '''slaptest -f samba.schema -F /etc/ldap/schema -s "cn=schema,cn=config"''' ldapadd -x -H ldap://<LDAP SERVER>/ -D "cn=config" -W -f <SCHEMA>.ldif Enter LDAP Password: adding new entry "cn=<SCHEMA>,cn=schema,cn=config" ==OpenLDAP finetuning== To finetune the OpenLDAP configuration, we make some changes to the main configuration file for the OpenLDAP server, ''/etc/ldap/slapd.conf''. Note: make SURE that the permissions on this file are rw-r----- (640) and the owner is ''root:openldap'', so that OpenLDAP can read the configuration, but only you can change it. When changing the configuration of your LDAP server, keep in mind that everything ''above'' the first ''backend hdb'' (or ''backend <something>'') should contain only global directives, and everything under it only backend directives that will apply to all databases that you're going to run under that backend type. In our examples, we're only going to run a single database of a single backend type, so all backend directives will apply to our single database. Nevertheless, you should put your global directives above the backend declaration, and the rest below. 0d3291ca51b924702aa46704a3e3619cde55292c 2697 2696 2011-06-18T20:24:26Z Saruman! 2 /* Adding schemas */ finding schemas wikitext text/x-wiki Note: if you need information on the OpenLDAP version from Debian 5.0, see this page: [[OpenLDAP 2.4.11]] == OpenLDAP installation== Note: we're going to install OpenLDAP on our server as [http://www.openldap.org/doc/admin24/config.html#Local%20Directory%20Service the local directory service], without replication, referrals or other advanced features. Under Debian Squeeze, this is OpenLDAP 2.4.23. ===Standard installation=== Installing OpenLDAP on your Debian server is ridiculously simple. Just make sure your server is up-to-date (''sudo apt-get update'' followed by ''sudo apt-get upgrade''), and then install the two main components for your OpenLDAP server. First off: the LDAP client and utilities sudo apt-get install ldap-utils This will result in the installation of as much as 8 different packages (''ldap-utils'', ''libgcrypt11'', ''libgnutls26'', ''libgpg-error0'', ''libldap-2.4-2'', ''libsasl2-2'', ''libsasl2-modules'', and ''libtasn1-3''). Next the main component of an LDAP server installation, the stand-alone LDAP daemon "slapd" sudo apt-get install slapd This may also install up to 8 packages (''slapd'', ''libltdl7'', ''libperl5.10'', ''libslp1'', ''odbcinst'', ''odbcinst1debian2'', ''psmisc'' and ''unixodbc''). The Debian configuration script will ask you for only one single thing: an administrator password. As always: generate a strong password! After you've provided the password, the LDAP database is created with the administrator name "admin" and as a base directory, something based on your DNS name. Suppose your internal domain is "amber.lan", then the script will generate ''suffix "dc=amber,dc=lan"''<ref>Should you see a third, empty, domain component (''dc='') then this is caused by a trailing dot in your particular DNS name: the DNS root. You might have specified your domain as "amber.lan.". You ''should'' change your domain name to a name without the DNS root, and you ''must'' regenerate your LDAP directory.</ref>. The above method of configuring yields you an LDAP database with only two objects in it. Suppose your DNS name is "easton2.amber.lan", then the two objects are: * a single Organization (o="amber.lan") with Distinguished Name dn="dc=amber,dc=lan" * a single administrator with Common Name cn="admin", and dn="cn=admin,dc=amber,dc=lan" Note, however, that there's ''also'' a second LDAP database, "cn=config", which on your server is located under ''/etc/ldap/slapd.d''. We'll cover what's in it further on. <references/> ===Testing the installation=== After installation of the package, it should automatically have been started, and should now be operational. This can be checked with a utility like ''nmap'': root@easton2:~# '''nmap -p 389 localhost''' Starting Nmap 5.00 ( <nowiki>http://nmap.org</nowiki> ) at 2011-04-13 21:19 CEST Interesting ports on localhost (127.0.0.1): PORT STATE SERVICE 389/tcp open ldap Nmap done: 1 IP address (1 host up) scanned in 0.40 seconds root@easton2:~#'''_''' Another way to test if the LDAP server is functional, is by querying it with the ''ldapsearch'' utility, part of the package ''ldap-utils''. Let's see if we can find the naming context of the LDAP server: root@easton2:~# '''ldapsearch -x -b <nowiki>''</nowiki> -s base '(objectclass=*)' namingContexts''' # extended LDIF # # LDAPv3 # base <> with scope baseObject # filter: (objectclass=*) # requesting: namingContexts # # dn: namingContexts: dc=amber,dc=lan # search result search: 2 result: 0 Success # numResponses: 2 # numEntries: 1 root@easton2:~# '''_''' With this command, we do a search using * basic authentication (instead of one encrypted with SASL), * searching within the LDAP tree from base <nowiki>''</nowiki> (meaning the absolute root of the tree), * looking for base object only (instead of a one-level search, a subtree search, or a children-search), * filtering for objects of any class, * asking for the naming context of the result. The output shows that the server responds; two objects have been considered, but none match the filter (that the object should have an objectClass). Let's now do the same but with authentication, to see if we can bind to the LDAP server. We'll first use an incorrect password, then the correct one: root@easton2:~# '''ldapsearch -W -D "cn=admin,dc=amber,dc=lan"''' Enter LDAP Password: ldap_bind: Invalid credentials (49) root@easton2:~# '''ldapsearch -W -D "cn=admin,dc=amber,dc=lan"''' Enter LDAP Password: # extended LDIF # # LDAPv3 # base <> (default) with scope subtree # filter: (objectclass=*) # requesting: ALL # # search result search: 2 result: 32 No such object # numResponses: 1 root@easton2:~# '''_''' Finally, you could simply install and run a graphical management tool for LDAP servers, like [http://directory.apache.org/studio/ Apache Directory Studio]. Note however that if this check fails, then this could also mean problems with firewalls, network connections et cetera. ===Post-install reconfiguration=== Since the default configuration with the server's DNS domain as LDAP base might not always be the most convenient configuration, you could run the configuration again using ''dpkg-reconfigure slapd''. However, following this procedure is '''only''' necessary if you want to change any of the default installation values like the backend database type or DNS domain name; things like the organization name can be edited with other means, as will be shown later on. To be able to reconfigure the LDAP service, you can run the reconfiguration command ''sudo dpkg-reconfigure slapd''. Contrary to some older versions of Debian, you do not need to manually stop the ''slapd'' daemon, and you don't need to manually remove the old configuration or database (in fact, if you do, then the ''slapd'' package will break, so you cannot easily remove it with APT tools). Interestingly enough, this reconfiguration asks you many ''more'' questions. The answers could look like this: omit OpenLDAP config: no DNS domain name: saruman.biz Organization name: Saruman Administrator passwd: wEt3udes Database backend: HDB DB remove after purge: yes Move old DB: yes Allow LDAPv2: no As you can see, the reconfiguration yields much more configuration options than plain installation - although really you'll probably answer most questions with their default values anyway. The above method of configuring yields you an LDAP database with only two objects in it: * a single Organization (o="Saruman") with Distinguished Name dn="dc=saruman,dc=biz" * a single administrator with Common Name cn="admin", and dn="cn=admin,dc=saruman,dc=biz" Also note that the reconfiguration creates a backup of the "old" LDAP database in a directory with a name like ''/var/backup/unknown-2.4.23-7.ldapdb''; if you just reconfigured after installation, then you probably don't need this backup, so you can remove it. The database that your OpenLDAP server uses is a standard Berkeley DB (BDB/HDB) database. Now we most likely will require some other databases as well in our server setup, something modern like PostgreSQL or MySQL - so why don't we configure our OpenLDAP to use this same database as well? For the answer, see [http://www.openldap.org/doc/admin24/intro.html#LDAP%20vs%20RDBMS here] - in short, the LDAP tree structure does not lend itself very well to inclusion in a modern relational database. Thus, we advise to stick with the Berkeley database provided with OpenLDAP. Now, for the database backend, we have the choice between two almost identical flavours: * the ''bdb'' backend used to be the recommended primary backend for a normal slapd database. It uses the Oracle Berkeley DB package, referred to as ''BDB'', to store data. It makes extensive use of indexing and caching to speed data access. * the ''hdb'' backend is a variant of the ''bdb'' backend that uses a hierarchical database layout which supports subtree renames. It is otherwise identical to the ''bdb'' behavior, and all the same configuration options apply. In Debian 6.0 "Squeeze" with OpenLDAP 2.4.23, HDB is the default backend. ==OpenLDAP configuration== <small>(text from http://www.rjsystems.nl/en/2100-d6-openldap-provider.php)</small> As of OpenLDAP 2.4.23-3, the ''slapd'' runtime configuration is fully LDAP-enabled. The default is to manage it using the standard LDAP operations with data in LDIF. The old ''slapd.conf'' format is still supported, but since that file must now be converted to the new ''slapd-config'' format to allow runtime changes to be saved, it seems likely that the developers will eventually phase it out. Therefore, we'll focus only on the new configuration method, the main advantage of which is that any changes made are immediately active, so it is no longer necessary to restart ''slapd'' after making configuration changes. The new configuration format uses a slapd backend database that is found in the ''/etc/ldap/slapd.d/'' directory. The configuration is stored as a special LDAP directory with a predefined schema and DIT, the root of which is called ''cn=config''. If you go look there, you'll find that most parts of this LDAP directory consist of editable flat files. ===Check the current LDAP configuration=== From the command line, there really are several ways to check the current LDAP configuration: * from the server itself, you can use the trusty ''ldapsearch'' command, running under root: this'll authenticate with user ID 0. Filtering only for distinguished names: root@easton2:/etc/ldap# '''ldapsearch -LLL -Y EXTERNAL -H ldapi:/// -b cn=config dn''' SASL/EXTERNAL authentication started SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth SASL SSF: 0 dn: cn=config dn: cn=module{0},cn=config dn: cn=schema,cn=config dn: cn={0}core,cn=schema,cn=config dn: cn={1}cosine,cn=schema,cn=config dn: cn={2}nis,cn=schema,cn=config dn: cn={3}inetorgperson,cn=schema,cn=config dn: olcBackend={0}hdb,cn=config dn: olcDatabase={-1}frontend,cn=config dn: olcDatabase={0}config,cn=config dn: olcDatabase={1}hdb,cn=config root@easton2:/etc/ldap# '''_''' * to get an idea of what the ''cn=config'' database looks like ''within LDAP itself'', you can run this command: root@easton2:/etc/ldap# '''slapcat -b cn=config''' dn: cn=config objectClass: olcGlobal cn: config olcArgsFile: /var/run/slapd/slapd.args olcLogLevel: none olcPidFile: /var/run/slapd/slapd.pid olcToolThreads: 1 '''''(more LDIF texts)''''' entryUUID: f2a8f568-fa40-102f-8b9d-5d4cbccf32a9 creatorsName: cn=admin,cn=config createTimestamp: 20110413174103Z entryCSN: 20110413174103.641065Z#000000#000#000000 modifiersName: cn=admin,cn=config modifyTimestamp: 20110413174103Z root@easton2:/etc/ldap# '''_''' : As you can see, this generates a pretty large LDIF dump of the contents of the ''cn=config'' directory. Much of it consists of schema information. The LDAP configuration directives are attributes of the directory entries (objects) and most them start with the prefix "olc" ('''O'''pen'''L'''DAP '''C'''onfiguration). Also, some of the objects have names with numbers between curly brackets. This is to compensate for the fact that LDAP databases do not store their contents in any particular order; they are inherently unordered. The numbers constitute a numeric index to ensure a consistent order in the configuration database and thereby preserve all ordering dependencies. The index numbers, however, are generated automatically in the order they are created and usually do not have to be provided. * you can see the configuration by browsing through all the plain-text flat files in ''/etc/ldap/slapd.d/'' and its subdirectories. Note that by default there is no way to do this remotely. If you'd like to browse this configuration using a GUI tool like [http://directory.apache.org/studio/ apache directory studio], don't bother. Debian sets the ''cn=config'' part of the database with a root user of ''cn=admin,cn=config'', but without a password, so you cannot bind to the ''cn=config'' database as anything else than the local root user. Thus you cannot access the ''cn=config'' database by GUI. ===Adding or modifying the cn=config admin password=== To add a password to the config RootDN, we first must generate one; for this we can use the ''slappasswd'' command. By default it'll create an SSHA password, but by specifying MD5 as hash (using '' -h {MD5}'') it will create an MD5 encrypted password. The command interactively asks you for the password, and won't show you what you've typed, so be precise: root@easton2:/etc/ldap# '''slappasswd -h {MD5}''' New password: Re-enter new password: {MD5}d5axCh6gYGjhfK4PGs09us== root@easton2:/etc/ldap# '''_''' Now we determine the DN (Distinguished Name) for the database that contains the RootDN password. We'll also check if there isn't a password in place already. To do this we used the following LDAP search command. root@easton2:/etc/ldap# '''ldapsearch -LLL -Y EXTERNAL -H ldapi:/// -b cn=config olcRootDN=cn=admin,cn=config dn olcRootDN olcRootPW''' SASL/EXTERNAL authentication started SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth SASL SSF: 0 dn: olcDatabase={0}config,cn=config olcRootDN: cn=admin,cn=config root@easton2:/etc/ldap# '''_''' Note the olcDatabase line, as it's the result we were looking for; it'll be needed for the ''ldapmodify'' command. Furthermore, note the absence of an olcRootPW entry; this is the starting point for a Debian OpenLDAP server.<br> Now we can stick in a new password. If no password is present, you can use this interactive procedure: root@easton2:/etc/ldap# '''ldapmodify -Y EXTERNAL -H ldapi:///''' SASL/EXTERNAL authentication started SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth SASL SSF: 0 '''dn: olcDatabase={0}config,cn=config''' '''add: olcRootPW''' '''olcRootPW: {MD5}d5axCh6gYGjhfK4PGs09us==''' modifying entry "olcDatabase={0}config,cn=config" root@easton2:/etc/ldap# '''_''' Note the following points: * we use the olcDatabase location as found with the previous ''ldapsearch'' command; * we input the MD5 password that we've generated previously; * as soon as you put in an empty line, the entry gets added; * you have to use CTRL-D to end this interactive mode; * if a password was already in place, we could still use the above, but we'd interactively feed the second line as '''replace: olcRootPW'''. We could also put the password in an ldif file, and feed that to the server. To this end, we'd create an ldif file with the following content: dn: olcDatabase={0}config,cn=config changetype: modify add: olcRootPW olcRootPW: {MD5}d5axCh6gYGjhfK4PGs09us== If this file is called ''addpassword.ldif'' and is created in ''/tmp'', then the addition can be executed using root@easton2:/etc/ldap# '''ldapmodify -Y EXTERNAL -H ldapi:/// -f /tmp/addpassword.ldif''' SASL/EXTERNAL authentication started SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth SASL SSF: 0 modifying entry "olcDatabase={0}config,cn=config" root@easton2:/tmp# '''_''' ===Adding or modifying configuration information=== The simple way of changing anything in the database goes like this: ===Adding schemas=== A major task in LDAP maintenance is the addition of LDAP schemas. By default, only 4 schemas will be present in your LDAP server: ''core'', ''cosine'', ''nis'' and ''inetorgperson''. Any other schema, -- say, for Samba -- would need to be added. However, let's first check which schemas are already installed. Let's try two different methods, and see what they'll show out of the box: root@easton2:/tmp# '''ldapsearch -LLLQY EXTERNAL -H ldapi:/// -b cn=schema,cn=config "(objectClass=olcSchemaConfig)" dn''' dn: cn=schema,cn=config dn: cn={0}core,cn=schema,cn=config dn: cn={1}cosine,cn=schema,cn=config dn: cn={2}nis,cn=schema,cn=config dn: cn={3}inetorgperson,cn=schema,cn=config root@easton2:/tmp# '''ls -l /etc/ldap/slapd.d/cn=config/cn=schema''' total 40 -rw------- 1 openldap openldap 15474 Jun 13 17:39 cn={0}core.ldif -rw------- 1 openldap openldap 11308 Jun 13 17:39 cn={1}cosine.ldif -rw------- 1 openldap openldap 6438 Jun 13 17:39 cn={2}nis.ldif -rw------- 1 openldap openldap 2802 Jun 13 17:39 cn={3}inetorgperson.ldif root@easton2:/tmp# '''_''' To add a schema, you need a schema in LDIF format, which you can then add to the LDAP database using the ''ldapadd'' command. Suppose you have a schema file ''samba.schema'' which you've copied to the ''/etc/ldap/schema'' directory. You'd first convert this to an LDIF file using root@easton2:/etc/ldap/schema# '''slaptest -f samba.schema -F /etc/ldap/schema -s "cn=schema,cn=config"''' ldapadd -x -H ldap://<LDAP SERVER>/ -D "cn=config" -W -f <SCHEMA>.ldif Enter LDAP Password: adding new entry "cn=<SCHEMA>,cn=schema,cn=config" ==OpenLDAP finetuning== To finetune the OpenLDAP configuration, we make some changes to the main configuration file for the OpenLDAP server, ''/etc/ldap/slapd.conf''. Note: make SURE that the permissions on this file are rw-r----- (640) and the owner is ''root:openldap'', so that OpenLDAP can read the configuration, but only you can change it. When changing the configuration of your LDAP server, keep in mind that everything ''above'' the first ''backend hdb'' (or ''backend <something>'') should contain only global directives, and everything under it only backend directives that will apply to all databases that you're going to run under that backend type. In our examples, we're only going to run a single database of a single backend type, so all backend directives will apply to our single database. Nevertheless, you should put your global directives above the backend declaration, and the rest below. 65f5609e52987604553fa6c331afadff82132615 2698 2697 2011-06-19T08:24:07Z Saruman! 2 restructure wikitext text/x-wiki Note: if you need information on the OpenLDAP version from Debian 5.0, see this page: [[OpenLDAP 2.4.11]] == OpenLDAP installation== Note: we're going to install OpenLDAP on our server as [http://www.openldap.org/doc/admin24/config.html#Local%20Directory%20Service the local directory service], without replication, referrals or other advanced features. Under Debian Squeeze, this is OpenLDAP 2.4.23. ===Standard installation=== Installing OpenLDAP on your Debian server is ridiculously simple. Just make sure your server is up-to-date (''sudo apt-get update'' followed by ''sudo apt-get upgrade''), and then install the two main components for your OpenLDAP server. First off: the LDAP client and utilities sudo apt-get install ldap-utils This will result in the installation of as much as 8 different packages (''ldap-utils'', ''libgcrypt11'', ''libgnutls26'', ''libgpg-error0'', ''libldap-2.4-2'', ''libsasl2-2'', ''libsasl2-modules'', and ''libtasn1-3''). Next the main component of an LDAP server installation, the stand-alone LDAP daemon "slapd" sudo apt-get install slapd This may also install up to 8 packages (''slapd'', ''libltdl7'', ''libperl5.10'', ''libslp1'', ''odbcinst'', ''odbcinst1debian2'', ''psmisc'' and ''unixodbc''). The Debian configuration script will ask you for only one single thing: an administrator password. As always: generate a strong password! After you've provided the password, the LDAP database is created with the administrator name "admin" and as a base directory, something based on your DNS name. Suppose your internal domain is "amber.lan", then the script will generate ''suffix "dc=amber,dc=lan"''<ref>Should you see a third, empty, domain component (''dc='') then this is caused by a trailing dot in your particular DNS name: the DNS root. You might have specified your domain as "amber.lan.". You ''should'' change your domain name to a name without the DNS root, and you ''must'' regenerate your LDAP directory.</ref>. The above method of configuring yields you an LDAP database with only two objects in it. Suppose your DNS name is "easton2.amber.lan", then the two objects are: * a single Organization (o="amber.lan") with Distinguished Name dn="dc=amber,dc=lan" * a single administrator with Common Name cn="admin", and dn="cn=admin,dc=amber,dc=lan" Note, however, that there's ''also'' a second LDAP database, "cn=config", which on your server is located under ''/etc/ldap/slapd.d''. We'll cover what's in it further on. <references/> ===Testing the installation=== After installation of the package, it should automatically have been started, and should now be operational. This can be checked with a utility like ''nmap'': root@easton2:~# '''nmap -p 389 localhost''' Starting Nmap 5.00 ( <nowiki>http://nmap.org</nowiki> ) at 2011-04-13 21:19 CEST Interesting ports on localhost (127.0.0.1): PORT STATE SERVICE 389/tcp open ldap Nmap done: 1 IP address (1 host up) scanned in 0.40 seconds root@easton2:~#'''_''' Another way to test if the LDAP server is functional, is by querying it with the ''ldapsearch'' utility, part of the package ''ldap-utils''. Let's see if we can find the naming context of the LDAP server: root@easton2:~# '''ldapsearch -x -b <nowiki>''</nowiki> -s base '(objectclass=*)' namingContexts''' # extended LDIF # # LDAPv3 # base <> with scope baseObject # filter: (objectclass=*) # requesting: namingContexts # # dn: namingContexts: dc=amber,dc=lan # search result search: 2 result: 0 Success # numResponses: 2 # numEntries: 1 root@easton2:~# '''_''' With this command, we do a search using * basic authentication (instead of one encrypted with SASL), * searching within the LDAP tree from base <nowiki>''</nowiki> (meaning the absolute root of the tree), * looking for base object only (instead of a one-level search, a subtree search, or a children-search), * filtering for objects of any class, * asking for the naming context of the result. The output shows that the server responds; two objects have been considered, but none match the filter (that the object should have an objectClass). Let's now do the same but with authentication, to see if we can bind to the LDAP server. We'll first use an incorrect password, then the correct one: root@easton2:~# '''ldapsearch -W -D "cn=admin,dc=amber,dc=lan"''' Enter LDAP Password: ldap_bind: Invalid credentials (49) root@easton2:~# '''ldapsearch -W -D "cn=admin,dc=amber,dc=lan"''' Enter LDAP Password: # extended LDIF # # LDAPv3 # base <> (default) with scope subtree # filter: (objectclass=*) # requesting: ALL # # search result search: 2 result: 32 No such object # numResponses: 1 root@easton2:~# '''_''' Finally, you could simply install and run a graphical management tool for LDAP servers, like [http://directory.apache.org/studio/ Apache Directory Studio]. Note however that if this check fails, then this could also mean problems with firewalls, network connections et cetera. ===Post-install reconfiguration=== Since the default configuration with the server's DNS domain as LDAP base might not always be the most convenient configuration, you could run the configuration again using ''dpkg-reconfigure slapd''. However, following this procedure is '''only''' necessary if you want to change any of the default installation values like the backend database type or DNS domain name; things like the organization name can be edited with other means, as will be shown later on. To be able to reconfigure the LDAP service, you can run the reconfiguration command ''sudo dpkg-reconfigure slapd''. Contrary to some older versions of Debian, you do not need to manually stop the ''slapd'' daemon, and you don't need to manually remove the old configuration or database (in fact, if you do, then the ''slapd'' package will break, so you cannot easily remove it with APT tools). Interestingly enough, this reconfiguration asks you many ''more'' questions. The answers could look like this: omit OpenLDAP config: no DNS domain name: saruman.biz Organization name: Saruman Administrator passwd: wEt3udes Database backend: HDB DB remove after purge: yes Move old DB: yes Allow LDAPv2: no As you can see, the reconfiguration yields much more configuration options than plain installation - although really you'll probably answer most questions with their default values anyway. The above method of configuring yields you an LDAP database with only two objects in it: * a single Organization (o="Saruman") with Distinguished Name dn="dc=saruman,dc=biz" * a single administrator with Common Name cn="admin", and dn="cn=admin,dc=saruman,dc=biz" Also note that the reconfiguration creates a backup of the "old" LDAP database in a directory with a name like ''/var/backup/unknown-2.4.23-7.ldapdb''; if you just reconfigured after installation, then you probably don't need this backup, so you can remove it. The database that your OpenLDAP server uses is a standard Berkeley DB (BDB/HDB) database. Now we most likely will require some other databases as well in our server setup, something modern like PostgreSQL or MySQL - so why don't we configure our OpenLDAP to use this same database as well? For the answer, see [http://www.openldap.org/doc/admin24/intro.html#LDAP%20vs%20RDBMS here] - in short, the LDAP tree structure does not lend itself very well to inclusion in a modern relational database. Thus, we advise to stick with the Berkeley database provided with OpenLDAP. Now, for the database backend, we have the choice between two almost identical flavours: * the ''bdb'' backend used to be the recommended primary backend for a normal slapd database. It uses the Oracle Berkeley DB package, referred to as ''BDB'', to store data. It makes extensive use of indexing and caching to speed data access. * the ''hdb'' backend is a variant of the ''bdb'' backend that uses a hierarchical database layout which supports subtree renames. It is otherwise identical to the ''bdb'' behavior, and all the same configuration options apply. In Debian 6.0 "Squeeze" with OpenLDAP 2.4.23, HDB is the default backend. ==OpenLDAP server configuration== <small>(text from http://www.rjsystems.nl/en/2100-d6-openldap-provider.php)</small> As of OpenLDAP 2.4.23-3, the ''slapd'' runtime configuration is fully LDAP-enabled. The default is to manage it using the standard LDAP operations with data in LDIF. The old ''slapd.conf'' format is still supported, but since that file must now be converted to the new ''slapd-config'' format to allow runtime changes to be saved, it seems likely that the developers will eventually phase it out. Therefore, we'll focus only on the new configuration method, the main advantage of which is that any changes made are immediately active, so it is no longer necessary to restart ''slapd'' after making configuration changes. The new configuration format uses a slapd backend database that is found in the ''/etc/ldap/slapd.d/'' directory. The configuration is stored as a special LDAP directory with a predefined schema and DIT, the root of which is called ''cn=config''. If you go look there, you'll find that most parts of this LDAP directory consist of editable flat files. ===Check the current LDAP configuration=== From the command line, there really are several ways to check the current LDAP configuration: * from the server itself, you can use the trusty ''ldapsearch'' command, running under root: this'll authenticate with user ID 0. Filtering only for distinguished names: root@easton2:/etc/ldap# '''ldapsearch -LLL -Y EXTERNAL -H ldapi:/// -b cn=config dn''' SASL/EXTERNAL authentication started SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth SASL SSF: 0 dn: cn=config dn: cn=module{0},cn=config dn: cn=schema,cn=config dn: cn={0}core,cn=schema,cn=config dn: cn={1}cosine,cn=schema,cn=config dn: cn={2}nis,cn=schema,cn=config dn: cn={3}inetorgperson,cn=schema,cn=config dn: olcBackend={0}hdb,cn=config dn: olcDatabase={-1}frontend,cn=config dn: olcDatabase={0}config,cn=config dn: olcDatabase={1}hdb,cn=config root@easton2:/etc/ldap# '''_''' * to get an idea of what the ''cn=config'' database looks like ''within LDAP itself'', you can run this command: root@easton2:/etc/ldap# '''slapcat -b cn=config''' dn: cn=config objectClass: olcGlobal cn: config olcArgsFile: /var/run/slapd/slapd.args olcLogLevel: none olcPidFile: /var/run/slapd/slapd.pid olcToolThreads: 1 '''''(more LDIF texts)''''' entryUUID: f2a8f568-fa40-102f-8b9d-5d4cbccf32a9 creatorsName: cn=admin,cn=config createTimestamp: 20110413174103Z entryCSN: 20110413174103.641065Z#000000#000#000000 modifiersName: cn=admin,cn=config modifyTimestamp: 20110413174103Z root@easton2:/etc/ldap# '''_''' : As you can see, this generates a pretty large LDIF dump of the contents of the ''cn=config'' directory. Much of it consists of schema information. The LDAP configuration directives are attributes of the directory entries (objects) and most them start with the prefix "olc" ('''O'''pen'''L'''DAP '''C'''onfiguration). Also, some of the objects have names with numbers between curly brackets. This is to compensate for the fact that LDAP databases do not store their contents in any particular order; they are inherently unordered. The numbers constitute a numeric index to ensure a consistent order in the configuration database and thereby preserve all ordering dependencies. The index numbers, however, are generated automatically in the order they are created and usually do not have to be provided. * you can see the configuration by browsing through all the plain-text flat files in ''/etc/ldap/slapd.d/'' and its subdirectories. Note that by default there is no way to do this remotely. If you'd like to browse this configuration using a GUI tool like [http://directory.apache.org/studio/ apache directory studio], don't bother. Debian sets the ''cn=config'' part of the database with a root user of ''cn=admin,cn=config'', but without a password, so you cannot bind to the ''cn=config'' database as anything else than the local root user. Thus you cannot access the ''cn=config'' database by GUI. ===Adding or modifying the cn=config admin password=== To add a password to the config RootDN, we first must generate one; for this we can use the ''slappasswd'' command. By default it'll create an SSHA password, but by specifying MD5 as hash (using '' -h {MD5}'') it will create an MD5 encrypted password. The command interactively asks you for the password, and won't show you what you've typed, so be precise: root@easton2:/etc/ldap# '''slappasswd -h {MD5}''' New password: Re-enter new password: {MD5}d5axCh6gYGjhfK4PGs09us== root@easton2:/etc/ldap# '''_''' Now we determine the DN (Distinguished Name) for the database that contains the RootDN password. We'll also check if there isn't a password in place already. To do this we used the following LDAP search command. root@easton2:/etc/ldap# '''ldapsearch -LLL -Y EXTERNAL -H ldapi:/// -b cn=config olcRootDN=cn=admin,cn=config dn olcRootDN olcRootPW''' SASL/EXTERNAL authentication started SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth SASL SSF: 0 dn: olcDatabase={0}config,cn=config olcRootDN: cn=admin,cn=config root@easton2:/etc/ldap# '''_''' Note the olcDatabase line, as it's the result we were looking for; it'll be needed for the ''ldapmodify'' command. Furthermore, note the absence of an olcRootPW entry; this is the starting point for a Debian OpenLDAP server.<br> Now we can stick in a new password. If no password is present, you can use this interactive procedure: root@easton2:/etc/ldap# '''ldapmodify -Y EXTERNAL -H ldapi:///''' SASL/EXTERNAL authentication started SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth SASL SSF: 0 '''dn: olcDatabase={0}config,cn=config''' '''add: olcRootPW''' '''olcRootPW: {MD5}d5axCh6gYGjhfK4PGs09us==''' modifying entry "olcDatabase={0}config,cn=config" root@easton2:/etc/ldap# '''_''' Note the following points: * we use the olcDatabase location as found with the previous ''ldapsearch'' command; * we input the MD5 password that we've generated previously; * as soon as you put in an empty line, the entry gets added; * you have to use CTRL-D to end this interactive mode; * if a password was already in place, we could still use the above, but we'd interactively feed the second line as '''replace: olcRootPW'''. We could also put the password in an ldif file, and feed that to the server. To this end, we'd create an ldif file with the following content: dn: olcDatabase={0}config,cn=config changetype: modify add: olcRootPW olcRootPW: {MD5}d5axCh6gYGjhfK4PGs09us== If this file is called ''addpassword.ldif'' and is created in ''/tmp'', then the addition can be executed using root@easton2:/etc/ldap# '''ldapmodify -Y EXTERNAL -H ldapi:/// -f /tmp/addpassword.ldif''' SASL/EXTERNAL authentication started SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth SASL SSF: 0 modifying entry "olcDatabase={0}config,cn=config" root@easton2:/tmp# '''_''' ==Adding or modifying (configuration) information== The simple way of changing anything in the database goes like this: ===Method 1: interactive CLI tool=== ===Method 2: use an ldif file=== ===Method 3: use an LDAP browser=== With this method, you just use your LDAP browser for the addition or modification, according to its specific usage instructions. In the back, the tool will communicate with the LDAP server as you would in the previous methods. Note however, that this method relies on a bind account in the configuration database, which is a serious security risk. ==Adding schemas== A major task in LDAP maintenance is the addition of LDAP schemas. By default, only 4 schemas will be present in your LDAP server: ''core'', ''cosine'', ''nis'' and ''inetorgperson''. Any other schema, -- say, for Samba -- would need to be added. However, let's first check which schemas are already installed. Let's try two different methods, and see what they'll show out of the box: root@easton2:/tmp# '''ldapsearch -LLLQY EXTERNAL -H ldapi:/// -b cn=schema,cn=config "(objectClass=olcSchemaConfig)" dn''' dn: cn=schema,cn=config dn: cn={0}core,cn=schema,cn=config dn: cn={1}cosine,cn=schema,cn=config dn: cn={2}nis,cn=schema,cn=config dn: cn={3}inetorgperson,cn=schema,cn=config root@easton2:/tmp# '''ls -l /etc/ldap/slapd.d/cn=config/cn=schema''' total 40 -rw------- 1 openldap openldap 15474 Jun 13 17:39 cn={0}core.ldif -rw------- 1 openldap openldap 11308 Jun 13 17:39 cn={1}cosine.ldif -rw------- 1 openldap openldap 6438 Jun 13 17:39 cn={2}nis.ldif -rw------- 1 openldap openldap 2802 Jun 13 17:39 cn={3}inetorgperson.ldif root@easton2:/tmp# '''_''' To add a schema, you need a schema in LDIF format, which you can then add to the LDAP database using the ''ldapadd'' command. Suppose you have a schema file ''samba.schema'' which you've copied to the ''/etc/ldap/schema'' directory. You'd first convert this to an LDIF file using root@easton2:/etc/ldap/schema# '''slaptest -f samba.schema -F /etc/ldap/schema -s "cn=schema,cn=config"''' ldapadd -x -H ldap://<LDAP SERVER>/ -D "cn=config" -W -f <SCHEMA>.ldif Enter LDAP Password: adding new entry "cn=<SCHEMA>,cn=schema,cn=config" 4cf02a79b19cbfe4133c1e0c32f0808c4138ded4 2699 2698 2011-06-19T11:21:30Z Saruman! 2 /* Adding or modifying (configuration) information */ addition wikitext text/x-wiki Note: if you need information on the OpenLDAP version from Debian 5.0, see this page: [[OpenLDAP 2.4.11]] == OpenLDAP installation== Note: we're going to install OpenLDAP on our server as [http://www.openldap.org/doc/admin24/config.html#Local%20Directory%20Service the local directory service], without replication, referrals or other advanced features. Under Debian Squeeze, this is OpenLDAP 2.4.23. ===Standard installation=== Installing OpenLDAP on your Debian server is ridiculously simple. Just make sure your server is up-to-date (''sudo apt-get update'' followed by ''sudo apt-get upgrade''), and then install the two main components for your OpenLDAP server. First off: the LDAP client and utilities sudo apt-get install ldap-utils This will result in the installation of as much as 8 different packages (''ldap-utils'', ''libgcrypt11'', ''libgnutls26'', ''libgpg-error0'', ''libldap-2.4-2'', ''libsasl2-2'', ''libsasl2-modules'', and ''libtasn1-3''). Next the main component of an LDAP server installation, the stand-alone LDAP daemon "slapd" sudo apt-get install slapd This may also install up to 8 packages (''slapd'', ''libltdl7'', ''libperl5.10'', ''libslp1'', ''odbcinst'', ''odbcinst1debian2'', ''psmisc'' and ''unixodbc''). The Debian configuration script will ask you for only one single thing: an administrator password. As always: generate a strong password! After you've provided the password, the LDAP database is created with the administrator name "admin" and as a base directory, something based on your DNS name. Suppose your internal domain is "amber.lan", then the script will generate ''suffix "dc=amber,dc=lan"''<ref>Should you see a third, empty, domain component (''dc='') then this is caused by a trailing dot in your particular DNS name: the DNS root. You might have specified your domain as "amber.lan.". You ''should'' change your domain name to a name without the DNS root, and you ''must'' regenerate your LDAP directory.</ref>. The above method of configuring yields you an LDAP database with only two objects in it. Suppose your DNS name is "easton2.amber.lan", then the two objects are: * a single Organization (o="amber.lan") with Distinguished Name dn="dc=amber,dc=lan" * a single administrator with Common Name cn="admin", and dn="cn=admin,dc=amber,dc=lan" Note, however, that there's ''also'' a second LDAP database, "cn=config", which on your server is located under ''/etc/ldap/slapd.d''. We'll cover what's in it further on. <references/> ===Testing the installation=== After installation of the package, it should automatically have been started, and should now be operational. This can be checked with a utility like ''nmap'': root@easton2:~# '''nmap -p 389 localhost''' Starting Nmap 5.00 ( <nowiki>http://nmap.org</nowiki> ) at 2011-04-13 21:19 CEST Interesting ports on localhost (127.0.0.1): PORT STATE SERVICE 389/tcp open ldap Nmap done: 1 IP address (1 host up) scanned in 0.40 seconds root@easton2:~#'''_''' Another way to test if the LDAP server is functional, is by querying it with the ''ldapsearch'' utility, part of the package ''ldap-utils''. Let's see if we can find the naming context of the LDAP server: root@easton2:~# '''ldapsearch -x -b <nowiki>''</nowiki> -s base '(objectclass=*)' namingContexts''' # extended LDIF # # LDAPv3 # base <> with scope baseObject # filter: (objectclass=*) # requesting: namingContexts # # dn: namingContexts: dc=amber,dc=lan # search result search: 2 result: 0 Success # numResponses: 2 # numEntries: 1 root@easton2:~# '''_''' With this command, we do a search using * basic authentication (instead of one encrypted with SASL), * searching within the LDAP tree from base <nowiki>''</nowiki> (meaning the absolute root of the tree), * looking for base object only (instead of a one-level search, a subtree search, or a children-search), * filtering for objects of any class, * asking for the naming context of the result. The output shows that the server responds; two objects have been considered, but none match the filter (that the object should have an objectClass). Let's now do the same but with authentication, to see if we can bind to the LDAP server. We'll first use an incorrect password, then the correct one: root@easton2:~# '''ldapsearch -W -D "cn=admin,dc=amber,dc=lan"''' Enter LDAP Password: ldap_bind: Invalid credentials (49) root@easton2:~# '''ldapsearch -W -D "cn=admin,dc=amber,dc=lan"''' Enter LDAP Password: # extended LDIF # # LDAPv3 # base <> (default) with scope subtree # filter: (objectclass=*) # requesting: ALL # # search result search: 2 result: 32 No such object # numResponses: 1 root@easton2:~# '''_''' Finally, you could simply install and run a graphical management tool for LDAP servers, like [http://directory.apache.org/studio/ Apache Directory Studio]. Note however that if this check fails, then this could also mean problems with firewalls, network connections et cetera. ===Post-install reconfiguration=== Since the default configuration with the server's DNS domain as LDAP base might not always be the most convenient configuration, you could run the configuration again using ''dpkg-reconfigure slapd''. However, following this procedure is '''only''' necessary if you want to change any of the default installation values like the backend database type or DNS domain name; things like the organization name can be edited with other means, as will be shown later on. To be able to reconfigure the LDAP service, you can run the reconfiguration command ''sudo dpkg-reconfigure slapd''. Contrary to some older versions of Debian, you do not need to manually stop the ''slapd'' daemon, and you don't need to manually remove the old configuration or database (in fact, if you do, then the ''slapd'' package will break, so you cannot easily remove it with APT tools). Interestingly enough, this reconfiguration asks you many ''more'' questions. The answers could look like this: omit OpenLDAP config: no DNS domain name: saruman.biz Organization name: Saruman Administrator passwd: wEt3udes Database backend: HDB DB remove after purge: yes Move old DB: yes Allow LDAPv2: no As you can see, the reconfiguration yields much more configuration options than plain installation - although really you'll probably answer most questions with their default values anyway. The above method of configuring yields you an LDAP database with only two objects in it: * a single Organization (o="Saruman") with Distinguished Name dn="dc=saruman,dc=biz" * a single administrator with Common Name cn="admin", and dn="cn=admin,dc=saruman,dc=biz" Also note that the reconfiguration creates a backup of the "old" LDAP database in a directory with a name like ''/var/backup/unknown-2.4.23-7.ldapdb''; if you just reconfigured after installation, then you probably don't need this backup, so you can remove it. The database that your OpenLDAP server uses is a standard Berkeley DB (BDB/HDB) database. Now we most likely will require some other databases as well in our server setup, something modern like PostgreSQL or MySQL - so why don't we configure our OpenLDAP to use this same database as well? For the answer, see [http://www.openldap.org/doc/admin24/intro.html#LDAP%20vs%20RDBMS here] - in short, the LDAP tree structure does not lend itself very well to inclusion in a modern relational database. Thus, we advise to stick with the Berkeley database provided with OpenLDAP. Now, for the database backend, we have the choice between two almost identical flavours: * the ''bdb'' backend used to be the recommended primary backend for a normal slapd database. It uses the Oracle Berkeley DB package, referred to as ''BDB'', to store data. It makes extensive use of indexing and caching to speed data access. * the ''hdb'' backend is a variant of the ''bdb'' backend that uses a hierarchical database layout which supports subtree renames. It is otherwise identical to the ''bdb'' behavior, and all the same configuration options apply. In Debian 6.0 "Squeeze" with OpenLDAP 2.4.23, HDB is the default backend. ==OpenLDAP server configuration== <small>(text from http://www.rjsystems.nl/en/2100-d6-openldap-provider.php)</small> As of OpenLDAP 2.4.23-3, the ''slapd'' runtime configuration is fully LDAP-enabled. The default is to manage it using the standard LDAP operations with data in LDIF. The old ''slapd.conf'' format is still supported, but since that file must now be converted to the new ''slapd-config'' format to allow runtime changes to be saved, it seems likely that the developers will eventually phase it out. Therefore, we'll focus only on the new configuration method, the main advantage of which is that any changes made are immediately active, so it is no longer necessary to restart ''slapd'' after making configuration changes. The new configuration format uses a slapd backend database that is found in the ''/etc/ldap/slapd.d/'' directory. The configuration is stored as a special LDAP directory with a predefined schema and DIT, the root of which is called ''cn=config''. If you go look there, you'll find that most parts of this LDAP directory consist of editable flat files. ===Check the current LDAP configuration=== From the command line, there really are several ways to check the current LDAP configuration: * from the server itself, you can use the trusty ''ldapsearch'' command, running under root: this'll authenticate with user ID 0. Filtering only for distinguished names: root@easton2:/etc/ldap# '''ldapsearch -LLL -Y EXTERNAL -H ldapi:/// -b cn=config dn''' SASL/EXTERNAL authentication started SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth SASL SSF: 0 dn: cn=config dn: cn=module{0},cn=config dn: cn=schema,cn=config dn: cn={0}core,cn=schema,cn=config dn: cn={1}cosine,cn=schema,cn=config dn: cn={2}nis,cn=schema,cn=config dn: cn={3}inetorgperson,cn=schema,cn=config dn: olcBackend={0}hdb,cn=config dn: olcDatabase={-1}frontend,cn=config dn: olcDatabase={0}config,cn=config dn: olcDatabase={1}hdb,cn=config root@easton2:/etc/ldap# '''_''' * to get an idea of what the ''cn=config'' database looks like ''within LDAP itself'', you can run this command: root@easton2:/etc/ldap# '''slapcat -b cn=config''' dn: cn=config objectClass: olcGlobal cn: config olcArgsFile: /var/run/slapd/slapd.args olcLogLevel: none olcPidFile: /var/run/slapd/slapd.pid olcToolThreads: 1 '''''(more LDIF texts)''''' entryUUID: f2a8f568-fa40-102f-8b9d-5d4cbccf32a9 creatorsName: cn=admin,cn=config createTimestamp: 20110413174103Z entryCSN: 20110413174103.641065Z#000000#000#000000 modifiersName: cn=admin,cn=config modifyTimestamp: 20110413174103Z root@easton2:/etc/ldap# '''_''' : As you can see, this generates a pretty large LDIF dump of the contents of the ''cn=config'' directory. Much of it consists of schema information. The LDAP configuration directives are attributes of the directory entries (objects) and most them start with the prefix "olc" ('''O'''pen'''L'''DAP '''C'''onfiguration). Also, some of the objects have names with numbers between curly brackets. This is to compensate for the fact that LDAP databases do not store their contents in any particular order; they are inherently unordered. The numbers constitute a numeric index to ensure a consistent order in the configuration database and thereby preserve all ordering dependencies. The index numbers, however, are generated automatically in the order they are created and usually do not have to be provided. * you can see the configuration by browsing through all the plain-text flat files in ''/etc/ldap/slapd.d/'' and its subdirectories. Note that by default there is no way to do this remotely. If you'd like to browse this configuration using a GUI tool like [http://directory.apache.org/studio/ apache directory studio], don't bother. Debian sets the ''cn=config'' part of the database with a root user of ''cn=admin,cn=config'', but without a password, so you cannot bind to the ''cn=config'' database as anything else than the local root user. Thus you cannot access the ''cn=config'' database by GUI. ===Adding or modifying the cn=config admin password=== To add a password to the config RootDN, we first must generate one; for this we can use the ''slappasswd'' command. By default it'll create an SSHA password, but by specifying MD5 as hash (using '' -h {MD5}'') it will create an MD5 encrypted password. The command interactively asks you for the password, and won't show you what you've typed, so be precise: root@easton2:/etc/ldap# '''slappasswd -h {MD5}''' New password: Re-enter new password: {MD5}d5axCh6gYGjhfK4PGs09us== root@easton2:/etc/ldap# '''_''' Now we determine the DN (Distinguished Name) for the database that contains the RootDN password. We'll also check if there isn't a password in place already. To do this we used the following LDAP search command. root@easton2:/etc/ldap# '''ldapsearch -LLL -Y EXTERNAL -H ldapi:/// -b cn=config olcRootDN=cn=admin,cn=config dn olcRootDN olcRootPW''' SASL/EXTERNAL authentication started SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth SASL SSF: 0 dn: olcDatabase={0}config,cn=config olcRootDN: cn=admin,cn=config root@easton2:/etc/ldap# '''_''' Note the olcDatabase line, as it's the result we were looking for; it'll be needed for the ''ldapmodify'' command. Furthermore, note the absence of an olcRootPW entry; this is the starting point for a Debian OpenLDAP server.<br> Now we can stick in a new password. If no password is present, you can use this interactive procedure: root@easton2:/etc/ldap# '''ldapmodify -Y EXTERNAL -H ldapi:///''' SASL/EXTERNAL authentication started SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth SASL SSF: 0 '''dn: olcDatabase={0}config,cn=config''' '''add: olcRootPW''' '''olcRootPW: {MD5}d5axCh6gYGjhfK4PGs09us==''' modifying entry "olcDatabase={0}config,cn=config" root@easton2:/etc/ldap# '''_''' Note the following points: * we use the olcDatabase location as found with the previous ''ldapsearch'' command; * we input the MD5 password that we've generated previously; * as soon as you put in an empty line, the entry gets added; * you have to use CTRL-D to end this interactive mode; * if a password was already in place, we could still use the above, but we'd interactively feed the second line as '''replace: olcRootPW'''. We could also put the password in an ldif file, and feed that to the server. To this end, we'd create an ldif file with the following content: dn: olcDatabase={0}config,cn=config changetype: modify add: olcRootPW olcRootPW: {MD5}d5axCh6gYGjhfK4PGs09us== If this file is called ''addpassword.ldif'' and is created in ''/tmp'', then the addition can be executed using root@easton2:/etc/ldap# '''ldapmodify -Y EXTERNAL -H ldapi:/// -f /tmp/addpassword.ldif''' SASL/EXTERNAL authentication started SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth SASL SSF: 0 modifying entry "olcDatabase={0}config,cn=config" root@easton2:/tmp# '''_''' ==Adding or modifying (configuration) information== The simple way of changing anything in the database goes like this: ===Method 1: interactive CLI tool=== As an example, let's add an index to the configuration. We'll start by seeing which indices already exist, then interactively add two indices. Finally, we check that the indices are there: root@easton2:/tmp# '''ldapsearch -LLLQY EXTERNAL -H ldapi:/// -b cn=config olcDatabase={1}hdb olcDbIndex''' dn: olcDatabase={1}hdb,cn=config olcDbIndex: objectClass eq root@easton2:/tmp# ldapmodify -Y EXTERNAL -H ldapi:/// SASL/EXTERNAL authentication started SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth SASL SSF: 0 dn: olcDatabase={1}hdb,cn=config add: olcDbIndex olcDbIndex: cn eq olcDbIndex: uid eq modifying entry "olcDatabase={1}hdb,cn=config" root@easton2:/tmp# ldapsearch -LLLQY EXTERNAL -H ldapi:/// -b cn=config olcDatabase={1}hdb olcDbIndex dn: olcDatabase={1}hdb,cn=config olcDbIndex: objectClass eq olcDbIndex: cn eq olcDbIndex: uid eq root@easton2:/tmp# '''_''' Modifying works almost the same; we only need keyword ''replace'' instead of ''add'': ===Method 2: use an ldif file=== ===Method 3: use an LDAP browser=== With this method, you just use your LDAP browser for the addition or modification, according to its specific usage instructions. In the back, the tool will communicate with the LDAP server as you would in the previous methods. Note however, that this method relies on a bind account in the configuration database, which is a serious security risk. ==Adding schemas== A major task in LDAP maintenance is the addition of LDAP schemas. By default, only 4 schemas will be present in your LDAP server: ''core'', ''cosine'', ''nis'' and ''inetorgperson''. Any other schema, -- say, for Samba -- would need to be added. However, let's first check which schemas are already installed. Let's try two different methods, and see what they'll show out of the box: root@easton2:/tmp# '''ldapsearch -LLLQY EXTERNAL -H ldapi:/// -b cn=schema,cn=config "(objectClass=olcSchemaConfig)" dn''' dn: cn=schema,cn=config dn: cn={0}core,cn=schema,cn=config dn: cn={1}cosine,cn=schema,cn=config dn: cn={2}nis,cn=schema,cn=config dn: cn={3}inetorgperson,cn=schema,cn=config root@easton2:/tmp# '''ls -l /etc/ldap/slapd.d/cn=config/cn=schema''' total 40 -rw------- 1 openldap openldap 15474 Jun 13 17:39 cn={0}core.ldif -rw------- 1 openldap openldap 11308 Jun 13 17:39 cn={1}cosine.ldif -rw------- 1 openldap openldap 6438 Jun 13 17:39 cn={2}nis.ldif -rw------- 1 openldap openldap 2802 Jun 13 17:39 cn={3}inetorgperson.ldif root@easton2:/tmp# '''_''' To add a schema, you need a schema in LDIF format, which you can then add to the LDAP database using the ''ldapadd'' command. Suppose you have a schema file ''samba.schema'' which you've copied to the ''/etc/ldap/schema'' directory. You'd first convert this to an LDIF file using root@easton2:/etc/ldap/schema# '''slaptest -f samba.schema -F /etc/ldap/schema -s "cn=schema,cn=config"''' ldapadd -x -H ldap://<LDAP SERVER>/ -D "cn=config" -W -f <SCHEMA>.ldif Enter LDAP Password: adding new entry "cn=<SCHEMA>,cn=schema,cn=config" c52c57b00f8bfa1801fd5a9ce7a09e1c2e228d19 2700 2699 2011-06-19T13:07:22Z Saruman! 2 /* Adding or modifying (configuration) information */ finished edits wikitext text/x-wiki Note: if you need information on the OpenLDAP version from Debian 5.0, see this page: [[OpenLDAP 2.4.11]] == OpenLDAP installation== Note: we're going to install OpenLDAP on our server as [http://www.openldap.org/doc/admin24/config.html#Local%20Directory%20Service the local directory service], without replication, referrals or other advanced features. Under Debian Squeeze, this is OpenLDAP 2.4.23. ===Standard installation=== Installing OpenLDAP on your Debian server is ridiculously simple. Just make sure your server is up-to-date (''sudo apt-get update'' followed by ''sudo apt-get upgrade''), and then install the two main components for your OpenLDAP server. First off: the LDAP client and utilities sudo apt-get install ldap-utils This will result in the installation of as much as 8 different packages (''ldap-utils'', ''libgcrypt11'', ''libgnutls26'', ''libgpg-error0'', ''libldap-2.4-2'', ''libsasl2-2'', ''libsasl2-modules'', and ''libtasn1-3''). Next the main component of an LDAP server installation, the stand-alone LDAP daemon "slapd" sudo apt-get install slapd This may also install up to 8 packages (''slapd'', ''libltdl7'', ''libperl5.10'', ''libslp1'', ''odbcinst'', ''odbcinst1debian2'', ''psmisc'' and ''unixodbc''). The Debian configuration script will ask you for only one single thing: an administrator password. As always: generate a strong password! After you've provided the password, the LDAP database is created with the administrator name "admin" and as a base directory, something based on your DNS name. Suppose your internal domain is "amber.lan", then the script will generate ''suffix "dc=amber,dc=lan"''<ref>Should you see a third, empty, domain component (''dc='') then this is caused by a trailing dot in your particular DNS name: the DNS root. You might have specified your domain as "amber.lan.". You ''should'' change your domain name to a name without the DNS root, and you ''must'' regenerate your LDAP directory.</ref>. The above method of configuring yields you an LDAP database with only two objects in it. Suppose your DNS name is "easton2.amber.lan", then the two objects are: * a single Organization (o="amber.lan") with Distinguished Name dn="dc=amber,dc=lan" * a single administrator with Common Name cn="admin", and dn="cn=admin,dc=amber,dc=lan" Note, however, that there's ''also'' a second LDAP database, "cn=config", which on your server is located under ''/etc/ldap/slapd.d''. We'll cover what's in it further on. <references/> ===Testing the installation=== After installation of the package, it should automatically have been started, and should now be operational. This can be checked with a utility like ''nmap'': root@easton2:~# '''nmap -p 389 localhost''' Starting Nmap 5.00 ( <nowiki>http://nmap.org</nowiki> ) at 2011-04-13 21:19 CEST Interesting ports on localhost (127.0.0.1): PORT STATE SERVICE 389/tcp open ldap Nmap done: 1 IP address (1 host up) scanned in 0.40 seconds root@easton2:~#'''_''' Another way to test if the LDAP server is functional, is by querying it with the ''ldapsearch'' utility, part of the package ''ldap-utils''. Let's see if we can find the naming context of the LDAP server: root@easton2:~# '''ldapsearch -x -b <nowiki>''</nowiki> -s base '(objectclass=*)' namingContexts''' # extended LDIF # # LDAPv3 # base <> with scope baseObject # filter: (objectclass=*) # requesting: namingContexts # # dn: namingContexts: dc=amber,dc=lan # search result search: 2 result: 0 Success # numResponses: 2 # numEntries: 1 root@easton2:~# '''_''' With this command, we do a search using * basic authentication (instead of one encrypted with SASL), * searching within the LDAP tree from base <nowiki>''</nowiki> (meaning the absolute root of the tree), * looking for base object only (instead of a one-level search, a subtree search, or a children-search), * filtering for objects of any class, * asking for the naming context of the result. The output shows that the server responds; two objects have been considered, but none match the filter (that the object should have an objectClass). Let's now do the same but with authentication, to see if we can bind to the LDAP server. We'll first use an incorrect password, then the correct one: root@easton2:~# '''ldapsearch -W -D "cn=admin,dc=amber,dc=lan"''' Enter LDAP Password: ldap_bind: Invalid credentials (49) root@easton2:~# '''ldapsearch -W -D "cn=admin,dc=amber,dc=lan"''' Enter LDAP Password: # extended LDIF # # LDAPv3 # base <> (default) with scope subtree # filter: (objectclass=*) # requesting: ALL # # search result search: 2 result: 32 No such object # numResponses: 1 root@easton2:~# '''_''' Finally, you could simply install and run a graphical management tool for LDAP servers, like [http://directory.apache.org/studio/ Apache Directory Studio]. Note however that if this check fails, then this could also mean problems with firewalls, network connections et cetera. ===Post-install reconfiguration=== Since the default configuration with the server's DNS domain as LDAP base might not always be the most convenient configuration, you could run the configuration again using ''dpkg-reconfigure slapd''. However, following this procedure is '''only''' necessary if you want to change any of the default installation values like the backend database type or DNS domain name; things like the organization name can be edited with other means, as will be shown later on. To be able to reconfigure the LDAP service, you can run the reconfiguration command ''sudo dpkg-reconfigure slapd''. Contrary to some older versions of Debian, you do not need to manually stop the ''slapd'' daemon, and you don't need to manually remove the old configuration or database (in fact, if you do, then the ''slapd'' package will break, so you cannot easily remove it with APT tools). Interestingly enough, this reconfiguration asks you many ''more'' questions. The answers could look like this: omit OpenLDAP config: no DNS domain name: saruman.biz Organization name: Saruman Administrator passwd: wEt3udes Database backend: HDB DB remove after purge: yes Move old DB: yes Allow LDAPv2: no As you can see, the reconfiguration yields much more configuration options than plain installation - although really you'll probably answer most questions with their default values anyway. The above method of configuring yields you an LDAP database with only two objects in it: * a single Organization (o="Saruman") with Distinguished Name dn="dc=saruman,dc=biz" * a single administrator with Common Name cn="admin", and dn="cn=admin,dc=saruman,dc=biz" Also note that the reconfiguration creates a backup of the "old" LDAP database in a directory with a name like ''/var/backup/unknown-2.4.23-7.ldapdb''; if you just reconfigured after installation, then you probably don't need this backup, so you can remove it. The database that your OpenLDAP server uses is a standard Berkeley DB (BDB/HDB) database. Now we most likely will require some other databases as well in our server setup, something modern like PostgreSQL or MySQL - so why don't we configure our OpenLDAP to use this same database as well? For the answer, see [http://www.openldap.org/doc/admin24/intro.html#LDAP%20vs%20RDBMS here] - in short, the LDAP tree structure does not lend itself very well to inclusion in a modern relational database. Thus, we advise to stick with the Berkeley database provided with OpenLDAP. Now, for the database backend, we have the choice between two almost identical flavours: * the ''bdb'' backend used to be the recommended primary backend for a normal slapd database. It uses the Oracle Berkeley DB package, referred to as ''BDB'', to store data. It makes extensive use of indexing and caching to speed data access. * the ''hdb'' backend is a variant of the ''bdb'' backend that uses a hierarchical database layout which supports subtree renames. It is otherwise identical to the ''bdb'' behavior, and all the same configuration options apply. In Debian 6.0 "Squeeze" with OpenLDAP 2.4.23, HDB is the default backend. ==OpenLDAP server configuration== <small>(text from http://www.rjsystems.nl/en/2100-d6-openldap-provider.php)</small> As of OpenLDAP 2.4.23-3, the ''slapd'' runtime configuration is fully LDAP-enabled. The default is to manage it using the standard LDAP operations with data in LDIF. The old ''slapd.conf'' format is still supported, but since that file must now be converted to the new ''slapd-config'' format to allow runtime changes to be saved, it seems likely that the developers will eventually phase it out. Therefore, we'll focus only on the new configuration method, the main advantage of which is that any changes made are immediately active, so it is no longer necessary to restart ''slapd'' after making configuration changes. The new configuration format uses a slapd backend database that is found in the ''/etc/ldap/slapd.d/'' directory. The configuration is stored as a special LDAP directory with a predefined schema and DIT, the root of which is called ''cn=config''. If you go look there, you'll find that most parts of this LDAP directory consist of editable flat files. ===Check the current LDAP configuration=== From the command line, there really are several ways to check the current LDAP configuration: * from the server itself, you can use the trusty ''ldapsearch'' command, running under root: this'll authenticate with user ID 0. Filtering only for distinguished names: root@easton2:/etc/ldap# '''ldapsearch -LLL -Y EXTERNAL -H ldapi:/// -b cn=config dn''' SASL/EXTERNAL authentication started SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth SASL SSF: 0 dn: cn=config dn: cn=module{0},cn=config dn: cn=schema,cn=config dn: cn={0}core,cn=schema,cn=config dn: cn={1}cosine,cn=schema,cn=config dn: cn={2}nis,cn=schema,cn=config dn: cn={3}inetorgperson,cn=schema,cn=config dn: olcBackend={0}hdb,cn=config dn: olcDatabase={-1}frontend,cn=config dn: olcDatabase={0}config,cn=config dn: olcDatabase={1}hdb,cn=config root@easton2:/etc/ldap# '''_''' * to get an idea of what the ''cn=config'' database looks like ''within LDAP itself'', you can run this command: root@easton2:/etc/ldap# '''slapcat -b cn=config''' dn: cn=config objectClass: olcGlobal cn: config olcArgsFile: /var/run/slapd/slapd.args olcLogLevel: none olcPidFile: /var/run/slapd/slapd.pid olcToolThreads: 1 '''''(more LDIF texts)''''' entryUUID: f2a8f568-fa40-102f-8b9d-5d4cbccf32a9 creatorsName: cn=admin,cn=config createTimestamp: 20110413174103Z entryCSN: 20110413174103.641065Z#000000#000#000000 modifiersName: cn=admin,cn=config modifyTimestamp: 20110413174103Z root@easton2:/etc/ldap# '''_''' : As you can see, this generates a pretty large LDIF dump of the contents of the ''cn=config'' directory. Much of it consists of schema information. The LDAP configuration directives are attributes of the directory entries (objects) and most them start with the prefix "olc" ('''O'''pen'''L'''DAP '''C'''onfiguration). Also, some of the objects have names with numbers between curly brackets. This is to compensate for the fact that LDAP databases do not store their contents in any particular order; they are inherently unordered. The numbers constitute a numeric index to ensure a consistent order in the configuration database and thereby preserve all ordering dependencies. The index numbers, however, are generated automatically in the order they are created and usually do not have to be provided. * you can see the configuration by browsing through all the plain-text flat files in ''/etc/ldap/slapd.d/'' and its subdirectories. Note that by default there is no way to do this remotely. If you'd like to browse this configuration using a GUI tool like [http://directory.apache.org/studio/ apache directory studio], don't bother. Debian sets the ''cn=config'' part of the database with a root user of ''cn=admin,cn=config'', but without a password, so you cannot bind to the ''cn=config'' database as anything else than the local root user. Thus you cannot access the ''cn=config'' database by GUI. ===Adding or modifying the cn=config admin password=== To add a password to the config RootDN, we first must generate one; for this we can use the ''slappasswd'' command. By default it'll create an SSHA password, but by specifying MD5 as hash (using '' -h {MD5}'') it will create an MD5 encrypted password. The command interactively asks you for the password, and won't show you what you've typed, so be precise: root@easton2:/etc/ldap# '''slappasswd -h {MD5}''' New password: Re-enter new password: {MD5}d5axCh6gYGjhfK4PGs09us== root@easton2:/etc/ldap# '''_''' Now we determine the DN (Distinguished Name) for the database that contains the RootDN password. We'll also check if there isn't a password in place already. To do this we used the following LDAP search command. root@easton2:/etc/ldap# '''ldapsearch -LLL -Y EXTERNAL -H ldapi:/// -b cn=config olcRootDN=cn=admin,cn=config dn olcRootDN olcRootPW''' SASL/EXTERNAL authentication started SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth SASL SSF: 0 dn: olcDatabase={0}config,cn=config olcRootDN: cn=admin,cn=config root@easton2:/etc/ldap# '''_''' Note the olcDatabase line, as it's the result we were looking for; it'll be needed for the ''ldapmodify'' command. Furthermore, note the absence of an olcRootPW entry; this is the starting point for a Debian OpenLDAP server.<br> Now we can stick in a new password. If no password is present, you can use this interactive procedure: root@easton2:/etc/ldap# '''ldapmodify -Y EXTERNAL -H ldapi:///''' SASL/EXTERNAL authentication started SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth SASL SSF: 0 '''dn: olcDatabase={0}config,cn=config''' '''add: olcRootPW''' '''olcRootPW: {MD5}d5axCh6gYGjhfK4PGs09us==''' modifying entry "olcDatabase={0}config,cn=config" root@easton2:/etc/ldap# '''_''' Note the following points: * we use the olcDatabase location as found with the previous ''ldapsearch'' command; * we input the MD5 password that we've generated previously; * as soon as you put in an empty line, the entry gets added; * you have to use CTRL-D to end this interactive mode; * if a password was already in place, we could still use the above, but we'd interactively feed the second line as '''replace: olcRootPW'''. We could also put the password in an ldif file, and feed that to the server. To this end, we'd create an ldif file with the following content: dn: olcDatabase={0}config,cn=config changetype: modify add: olcRootPW olcRootPW: {MD5}d5axCh6gYGjhfK4PGs09us== If this file is called ''addpassword.ldif'' and is created in ''/tmp'', then the addition can be executed using root@easton2:/etc/ldap# '''ldapmodify -Y EXTERNAL -H ldapi:/// -f /tmp/addpassword.ldif''' SASL/EXTERNAL authentication started SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth SASL SSF: 0 modifying entry "olcDatabase={0}config,cn=config" root@easton2:/tmp# '''_''' ==Adding or modifying (configuration) information== The simple way of changing anything in the database goes like this: ===Method 1: interactive CLI tool=== As an example, let's add an index to the configuration. We'll start by seeing which indices already exist, then interactively add two indices. Finally, we check that the indices are there: root@easton2:/tmp# '''ldapsearch -LLLQY EXTERNAL -H ldapi:/// -b cn=config olcDatabase={1}hdb olcDbIndex''' dn: olcDatabase={1}hdb,cn=config olcDbIndex: objectClass eq root@easton2:/tmp# ldapmodify -Y EXTERNAL -H ldapi:/// SASL/EXTERNAL authentication started SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth SASL SSF: 0 dn: olcDatabase={1}hdb,cn=config add: olcDbIndex olcDbIndex: cn eq olcDbIndex: uid eq modifying entry "olcDatabase={1}hdb,cn=config" root@easton2:/tmp# '''ldapsearch -LLLQY EXTERNAL -H ldapi:/// -b cn=config olcDatabase={1}hdb olcDbIndex''' dn: olcDatabase={1}hdb,cn=config olcDbIndex: objectClass eq olcDbIndex: cn eq olcDbIndex: uid eq root@easton2:/tmp# '''_''' (And ofcourse we press ctrl-D to end interactive mode).<br>Note: we can /modify multiple attributes in one stanza, but we can also add multiple objects/attributes in one ''ldapmodify'' session: * If you input an empty line, you can start another ''dn:'' line, and perform another action; * If you input a minus sign by itself on a line, then OpenLDAP will assume you'll be performing another action in/on the same object. Modifying works almost the same; we only need keyword ''replace'' instead of ''add'': root@easton2:/tmp# '''ldapsearch -LLLQY EXTERNAL -H ldapi:/// -b cn=config -s base olcLogLevel''' dn: cn=config olcLogLevel: none root@easton2:/tmp# '''ldapmodify -Y EXTERNAL -H ldapi:///''' SASL/EXTERNAL authentication started SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth SASL SSF: 0 '''dn: cn=config''' '''changetype: modify''' '''replace: olcLogLevel''' '''olcLogLevel: stats''' modifying entry "cn=config" root@easton2:/tmp# '''ldapsearch -LLLQY EXTERNAL -H ldapi:/// -b cn=config -s base olcLogLevel''' dn: cn=config olcLogLevel: stats root@easton2:/tmp# '''_''' Note the ''-s base'' option that limits the search for the ''olcLogLevel'' attribute to the ''cn=config'' container. Deleting information from an LDAP tree rarely ever happens, because once an attribute is used for anything, you aren't allowed to delete it, only modify it. However, if you want to delete anything, you can use the changetype "modify" with action "delete": root@easton2:/tmp# '''ldapmodify -Y EXTERNAL -H ldapi:///''' SASL/EXTERNAL authentication started SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth SASL SSF: 0 '''dn: olcDatabase={0}config,cn=config''' '''changetype: modify''' '''delete: olcRootPW''' modifying entry "olcDatabase={0}config,cn=config" root@easton2:/tmp# '''_''' ===Method 2: use an ldif file=== ===Method 3: use an LDAP browser=== With this method, you just use your LDAP browser for the addition or modification, according to its specific usage instructions. In the back, the tool will communicate with the LDAP server as you would in the previous methods. Note however, that this method relies on a bind account in the configuration database, which is a serious security risk. ==Adding schemas== A major task in LDAP maintenance is the addition of LDAP schemas. By default, only 4 schemas will be present in your LDAP server: ''core'', ''cosine'', ''nis'' and ''inetorgperson''. Any other schema, -- say, for Samba -- would need to be added. However, let's first check which schemas are already installed. Let's try two different methods, and see what they'll show out of the box: root@easton2:/tmp# '''ldapsearch -LLLQY EXTERNAL -H ldapi:/// -b cn=schema,cn=config "(objectClass=olcSchemaConfig)" dn''' dn: cn=schema,cn=config dn: cn={0}core,cn=schema,cn=config dn: cn={1}cosine,cn=schema,cn=config dn: cn={2}nis,cn=schema,cn=config dn: cn={3}inetorgperson,cn=schema,cn=config root@easton2:/tmp# '''ls -l /etc/ldap/slapd.d/cn=config/cn=schema''' total 40 -rw------- 1 openldap openldap 15474 Jun 13 17:39 cn={0}core.ldif -rw------- 1 openldap openldap 11308 Jun 13 17:39 cn={1}cosine.ldif -rw------- 1 openldap openldap 6438 Jun 13 17:39 cn={2}nis.ldif -rw------- 1 openldap openldap 2802 Jun 13 17:39 cn={3}inetorgperson.ldif root@easton2:/tmp# '''_''' To add a schema, you need a schema in LDIF format, which you can then add to the LDAP database using the ''ldapadd'' command. Suppose you have a schema file ''samba.schema'' which you've copied to the ''/etc/ldap/schema'' directory. You'd first convert this to an LDIF file using root@easton2:/etc/ldap/schema# '''slaptest -f samba.schema -F /etc/ldap/schema -s "cn=schema,cn=config"''' ldapadd -x -H ldap://<LDAP SERVER>/ -D "cn=config" -W -f <SCHEMA>.ldif Enter LDAP Password: adding new entry "cn=<SCHEMA>,cn=schema,cn=config" 8f075a1e89dd383ed298c1dc653e1c7f404c856c 2701 2700 2011-06-19T17:43:34Z Saruman! 2 /* Method 1: interactive CLI tool */ emphasis wikitext text/x-wiki Note: if you need information on the OpenLDAP version from Debian 5.0, see this page: [[OpenLDAP 2.4.11]] == OpenLDAP installation== Note: we're going to install OpenLDAP on our server as [http://www.openldap.org/doc/admin24/config.html#Local%20Directory%20Service the local directory service], without replication, referrals or other advanced features. Under Debian Squeeze, this is OpenLDAP 2.4.23. ===Standard installation=== Installing OpenLDAP on your Debian server is ridiculously simple. Just make sure your server is up-to-date (''sudo apt-get update'' followed by ''sudo apt-get upgrade''), and then install the two main components for your OpenLDAP server. First off: the LDAP client and utilities sudo apt-get install ldap-utils This will result in the installation of as much as 8 different packages (''ldap-utils'', ''libgcrypt11'', ''libgnutls26'', ''libgpg-error0'', ''libldap-2.4-2'', ''libsasl2-2'', ''libsasl2-modules'', and ''libtasn1-3''). Next the main component of an LDAP server installation, the stand-alone LDAP daemon "slapd" sudo apt-get install slapd This may also install up to 8 packages (''slapd'', ''libltdl7'', ''libperl5.10'', ''libslp1'', ''odbcinst'', ''odbcinst1debian2'', ''psmisc'' and ''unixodbc''). The Debian configuration script will ask you for only one single thing: an administrator password. As always: generate a strong password! After you've provided the password, the LDAP database is created with the administrator name "admin" and as a base directory, something based on your DNS name. Suppose your internal domain is "amber.lan", then the script will generate ''suffix "dc=amber,dc=lan"''<ref>Should you see a third, empty, domain component (''dc='') then this is caused by a trailing dot in your particular DNS name: the DNS root. You might have specified your domain as "amber.lan.". You ''should'' change your domain name to a name without the DNS root, and you ''must'' regenerate your LDAP directory.</ref>. The above method of configuring yields you an LDAP database with only two objects in it. Suppose your DNS name is "easton2.amber.lan", then the two objects are: * a single Organization (o="amber.lan") with Distinguished Name dn="dc=amber,dc=lan" * a single administrator with Common Name cn="admin", and dn="cn=admin,dc=amber,dc=lan" Note, however, that there's ''also'' a second LDAP database, "cn=config", which on your server is located under ''/etc/ldap/slapd.d''. We'll cover what's in it further on. <references/> ===Testing the installation=== After installation of the package, it should automatically have been started, and should now be operational. This can be checked with a utility like ''nmap'': root@easton2:~# '''nmap -p 389 localhost''' Starting Nmap 5.00 ( <nowiki>http://nmap.org</nowiki> ) at 2011-04-13 21:19 CEST Interesting ports on localhost (127.0.0.1): PORT STATE SERVICE 389/tcp open ldap Nmap done: 1 IP address (1 host up) scanned in 0.40 seconds root@easton2:~#'''_''' Another way to test if the LDAP server is functional, is by querying it with the ''ldapsearch'' utility, part of the package ''ldap-utils''. Let's see if we can find the naming context of the LDAP server: root@easton2:~# '''ldapsearch -x -b <nowiki>''</nowiki> -s base '(objectclass=*)' namingContexts''' # extended LDIF # # LDAPv3 # base <> with scope baseObject # filter: (objectclass=*) # requesting: namingContexts # # dn: namingContexts: dc=amber,dc=lan # search result search: 2 result: 0 Success # numResponses: 2 # numEntries: 1 root@easton2:~# '''_''' With this command, we do a search using * basic authentication (instead of one encrypted with SASL), * searching within the LDAP tree from base <nowiki>''</nowiki> (meaning the absolute root of the tree), * looking for base object only (instead of a one-level search, a subtree search, or a children-search), * filtering for objects of any class, * asking for the naming context of the result. The output shows that the server responds; two objects have been considered, but none match the filter (that the object should have an objectClass). Let's now do the same but with authentication, to see if we can bind to the LDAP server. We'll first use an incorrect password, then the correct one: root@easton2:~# '''ldapsearch -W -D "cn=admin,dc=amber,dc=lan"''' Enter LDAP Password: ldap_bind: Invalid credentials (49) root@easton2:~# '''ldapsearch -W -D "cn=admin,dc=amber,dc=lan"''' Enter LDAP Password: # extended LDIF # # LDAPv3 # base <> (default) with scope subtree # filter: (objectclass=*) # requesting: ALL # # search result search: 2 result: 32 No such object # numResponses: 1 root@easton2:~# '''_''' Finally, you could simply install and run a graphical management tool for LDAP servers, like [http://directory.apache.org/studio/ Apache Directory Studio]. Note however that if this check fails, then this could also mean problems with firewalls, network connections et cetera. ===Post-install reconfiguration=== Since the default configuration with the server's DNS domain as LDAP base might not always be the most convenient configuration, you could run the configuration again using ''dpkg-reconfigure slapd''. However, following this procedure is '''only''' necessary if you want to change any of the default installation values like the backend database type or DNS domain name; things like the organization name can be edited with other means, as will be shown later on. To be able to reconfigure the LDAP service, you can run the reconfiguration command ''sudo dpkg-reconfigure slapd''. Contrary to some older versions of Debian, you do not need to manually stop the ''slapd'' daemon, and you don't need to manually remove the old configuration or database (in fact, if you do, then the ''slapd'' package will break, so you cannot easily remove it with APT tools). Interestingly enough, this reconfiguration asks you many ''more'' questions. The answers could look like this: omit OpenLDAP config: no DNS domain name: saruman.biz Organization name: Saruman Administrator passwd: wEt3udes Database backend: HDB DB remove after purge: yes Move old DB: yes Allow LDAPv2: no As you can see, the reconfiguration yields much more configuration options than plain installation - although really you'll probably answer most questions with their default values anyway. The above method of configuring yields you an LDAP database with only two objects in it: * a single Organization (o="Saruman") with Distinguished Name dn="dc=saruman,dc=biz" * a single administrator with Common Name cn="admin", and dn="cn=admin,dc=saruman,dc=biz" Also note that the reconfiguration creates a backup of the "old" LDAP database in a directory with a name like ''/var/backup/unknown-2.4.23-7.ldapdb''; if you just reconfigured after installation, then you probably don't need this backup, so you can remove it. The database that your OpenLDAP server uses is a standard Berkeley DB (BDB/HDB) database. Now we most likely will require some other databases as well in our server setup, something modern like PostgreSQL or MySQL - so why don't we configure our OpenLDAP to use this same database as well? For the answer, see [http://www.openldap.org/doc/admin24/intro.html#LDAP%20vs%20RDBMS here] - in short, the LDAP tree structure does not lend itself very well to inclusion in a modern relational database. Thus, we advise to stick with the Berkeley database provided with OpenLDAP. Now, for the database backend, we have the choice between two almost identical flavours: * the ''bdb'' backend used to be the recommended primary backend for a normal slapd database. It uses the Oracle Berkeley DB package, referred to as ''BDB'', to store data. It makes extensive use of indexing and caching to speed data access. * the ''hdb'' backend is a variant of the ''bdb'' backend that uses a hierarchical database layout which supports subtree renames. It is otherwise identical to the ''bdb'' behavior, and all the same configuration options apply. In Debian 6.0 "Squeeze" with OpenLDAP 2.4.23, HDB is the default backend. ==OpenLDAP server configuration== <small>(text from http://www.rjsystems.nl/en/2100-d6-openldap-provider.php)</small> As of OpenLDAP 2.4.23-3, the ''slapd'' runtime configuration is fully LDAP-enabled. The default is to manage it using the standard LDAP operations with data in LDIF. The old ''slapd.conf'' format is still supported, but since that file must now be converted to the new ''slapd-config'' format to allow runtime changes to be saved, it seems likely that the developers will eventually phase it out. Therefore, we'll focus only on the new configuration method, the main advantage of which is that any changes made are immediately active, so it is no longer necessary to restart ''slapd'' after making configuration changes. The new configuration format uses a slapd backend database that is found in the ''/etc/ldap/slapd.d/'' directory. The configuration is stored as a special LDAP directory with a predefined schema and DIT, the root of which is called ''cn=config''. If you go look there, you'll find that most parts of this LDAP directory consist of editable flat files. ===Check the current LDAP configuration=== From the command line, there really are several ways to check the current LDAP configuration: * from the server itself, you can use the trusty ''ldapsearch'' command, running under root: this'll authenticate with user ID 0. Filtering only for distinguished names: root@easton2:/etc/ldap# '''ldapsearch -LLL -Y EXTERNAL -H ldapi:/// -b cn=config dn''' SASL/EXTERNAL authentication started SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth SASL SSF: 0 dn: cn=config dn: cn=module{0},cn=config dn: cn=schema,cn=config dn: cn={0}core,cn=schema,cn=config dn: cn={1}cosine,cn=schema,cn=config dn: cn={2}nis,cn=schema,cn=config dn: cn={3}inetorgperson,cn=schema,cn=config dn: olcBackend={0}hdb,cn=config dn: olcDatabase={-1}frontend,cn=config dn: olcDatabase={0}config,cn=config dn: olcDatabase={1}hdb,cn=config root@easton2:/etc/ldap# '''_''' * to get an idea of what the ''cn=config'' database looks like ''within LDAP itself'', you can run this command: root@easton2:/etc/ldap# '''slapcat -b cn=config''' dn: cn=config objectClass: olcGlobal cn: config olcArgsFile: /var/run/slapd/slapd.args olcLogLevel: none olcPidFile: /var/run/slapd/slapd.pid olcToolThreads: 1 '''''(more LDIF texts)''''' entryUUID: f2a8f568-fa40-102f-8b9d-5d4cbccf32a9 creatorsName: cn=admin,cn=config createTimestamp: 20110413174103Z entryCSN: 20110413174103.641065Z#000000#000#000000 modifiersName: cn=admin,cn=config modifyTimestamp: 20110413174103Z root@easton2:/etc/ldap# '''_''' : As you can see, this generates a pretty large LDIF dump of the contents of the ''cn=config'' directory. Much of it consists of schema information. The LDAP configuration directives are attributes of the directory entries (objects) and most them start with the prefix "olc" ('''O'''pen'''L'''DAP '''C'''onfiguration). Also, some of the objects have names with numbers between curly brackets. This is to compensate for the fact that LDAP databases do not store their contents in any particular order; they are inherently unordered. The numbers constitute a numeric index to ensure a consistent order in the configuration database and thereby preserve all ordering dependencies. The index numbers, however, are generated automatically in the order they are created and usually do not have to be provided. * you can see the configuration by browsing through all the plain-text flat files in ''/etc/ldap/slapd.d/'' and its subdirectories. Note that by default there is no way to do this remotely. If you'd like to browse this configuration using a GUI tool like [http://directory.apache.org/studio/ apache directory studio], don't bother. Debian sets the ''cn=config'' part of the database with a root user of ''cn=admin,cn=config'', but without a password, so you cannot bind to the ''cn=config'' database as anything else than the local root user. Thus you cannot access the ''cn=config'' database by GUI. ===Adding or modifying the cn=config admin password=== To add a password to the config RootDN, we first must generate one; for this we can use the ''slappasswd'' command. By default it'll create an SSHA password, but by specifying MD5 as hash (using '' -h {MD5}'') it will create an MD5 encrypted password. The command interactively asks you for the password, and won't show you what you've typed, so be precise: root@easton2:/etc/ldap# '''slappasswd -h {MD5}''' New password: Re-enter new password: {MD5}d5axCh6gYGjhfK4PGs09us== root@easton2:/etc/ldap# '''_''' Now we determine the DN (Distinguished Name) for the database that contains the RootDN password. We'll also check if there isn't a password in place already. To do this we used the following LDAP search command. root@easton2:/etc/ldap# '''ldapsearch -LLL -Y EXTERNAL -H ldapi:/// -b cn=config olcRootDN=cn=admin,cn=config dn olcRootDN olcRootPW''' SASL/EXTERNAL authentication started SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth SASL SSF: 0 dn: olcDatabase={0}config,cn=config olcRootDN: cn=admin,cn=config root@easton2:/etc/ldap# '''_''' Note the olcDatabase line, as it's the result we were looking for; it'll be needed for the ''ldapmodify'' command. Furthermore, note the absence of an olcRootPW entry; this is the starting point for a Debian OpenLDAP server.<br> Now we can stick in a new password. If no password is present, you can use this interactive procedure: root@easton2:/etc/ldap# '''ldapmodify -Y EXTERNAL -H ldapi:///''' SASL/EXTERNAL authentication started SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth SASL SSF: 0 '''dn: olcDatabase={0}config,cn=config''' '''add: olcRootPW''' '''olcRootPW: {MD5}d5axCh6gYGjhfK4PGs09us==''' modifying entry "olcDatabase={0}config,cn=config" root@easton2:/etc/ldap# '''_''' Note the following points: * we use the olcDatabase location as found with the previous ''ldapsearch'' command; * we input the MD5 password that we've generated previously; * as soon as you put in an empty line, the entry gets added; * you have to use CTRL-D to end this interactive mode; * if a password was already in place, we could still use the above, but we'd interactively feed the second line as '''replace: olcRootPW'''. We could also put the password in an ldif file, and feed that to the server. To this end, we'd create an ldif file with the following content: dn: olcDatabase={0}config,cn=config changetype: modify add: olcRootPW olcRootPW: {MD5}d5axCh6gYGjhfK4PGs09us== If this file is called ''addpassword.ldif'' and is created in ''/tmp'', then the addition can be executed using root@easton2:/etc/ldap# '''ldapmodify -Y EXTERNAL -H ldapi:/// -f /tmp/addpassword.ldif''' SASL/EXTERNAL authentication started SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth SASL SSF: 0 modifying entry "olcDatabase={0}config,cn=config" root@easton2:/tmp# '''_''' ==Adding or modifying (configuration) information== The simple way of changing anything in the database goes like this: ===Method 1: interactive CLI tool=== As an example, let's add an index to the configuration. We'll start by seeing which indices already exist, then interactively add two indices. Finally, we check that the indices are there: root@easton2:/tmp# '''ldapsearch -LLLQY EXTERNAL -H ldapi:/// -b cn=config olcDatabase={1}hdb olcDbIndex''' dn: olcDatabase={1}hdb,cn=config olcDbIndex: objectClass eq root@easton2:/tmp# '''ldapmodify -Y EXTERNAL -H ldapi:///''' SASL/EXTERNAL authentication started SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth SASL SSF: 0 '''dn: olcDatabase={1}hdb,cn=config''' '''add: olcDbIndex''' '''olcDbIndex: cn eq''' '''olcDbIndex: uid eq''' modifying entry "olcDatabase={1}hdb,cn=config" root@easton2:/tmp# '''ldapsearch -LLLQY EXTERNAL -H ldapi:/// -b cn=config olcDatabase={1}hdb olcDbIndex''' dn: olcDatabase={1}hdb,cn=config olcDbIndex: objectClass eq olcDbIndex: cn eq olcDbIndex: uid eq root@easton2:/tmp# '''_''' (And ofcourse we press ctrl-D to end interactive mode).<br>Note: we can /modify multiple attributes in one stanza, but we can also add multiple objects/attributes in one ''ldapmodify'' session: * If you input an empty line, you can start another ''dn:'' line, and perform another action; * If you input a minus sign by itself on a line, then OpenLDAP will assume you'll be performing another action in/on the same object. Modifying works almost the same; we only need keyword ''replace'' instead of ''add'': root@easton2:/tmp# '''ldapsearch -LLLQY EXTERNAL -H ldapi:/// -b cn=config -s base olcLogLevel''' dn: cn=config olcLogLevel: none root@easton2:/tmp# '''ldapmodify -Y EXTERNAL -H ldapi:///''' SASL/EXTERNAL authentication started SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth SASL SSF: 0 '''dn: cn=config''' '''changetype: modify''' '''replace: olcLogLevel''' '''olcLogLevel: stats''' modifying entry "cn=config" root@easton2:/tmp# '''ldapsearch -LLLQY EXTERNAL -H ldapi:/// -b cn=config -s base olcLogLevel''' dn: cn=config olcLogLevel: stats root@easton2:/tmp# '''_''' Note the ''-s base'' option that limits the search for the ''olcLogLevel'' attribute to the ''cn=config'' container. Deleting information from an LDAP tree rarely ever happens, because once an attribute is used for anything, you aren't allowed to delete it, only modify it. However, if you want to delete anything, you can use the changetype "modify" with action "delete": root@easton2:/tmp# '''ldapmodify -Y EXTERNAL -H ldapi:///''' SASL/EXTERNAL authentication started SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth SASL SSF: 0 '''dn: olcDatabase={0}config,cn=config''' '''changetype: modify''' '''delete: olcRootPW''' modifying entry "olcDatabase={0}config,cn=config" root@easton2:/tmp# '''_''' ===Method 2: use an ldif file=== ===Method 3: use an LDAP browser=== With this method, you just use your LDAP browser for the addition or modification, according to its specific usage instructions. In the back, the tool will communicate with the LDAP server as you would in the previous methods. Note however, that this method relies on a bind account in the configuration database, which is a serious security risk. ==Adding schemas== A major task in LDAP maintenance is the addition of LDAP schemas. By default, only 4 schemas will be present in your LDAP server: ''core'', ''cosine'', ''nis'' and ''inetorgperson''. Any other schema, -- say, for Samba -- would need to be added. However, let's first check which schemas are already installed. Let's try two different methods, and see what they'll show out of the box: root@easton2:/tmp# '''ldapsearch -LLLQY EXTERNAL -H ldapi:/// -b cn=schema,cn=config "(objectClass=olcSchemaConfig)" dn''' dn: cn=schema,cn=config dn: cn={0}core,cn=schema,cn=config dn: cn={1}cosine,cn=schema,cn=config dn: cn={2}nis,cn=schema,cn=config dn: cn={3}inetorgperson,cn=schema,cn=config root@easton2:/tmp# '''ls -l /etc/ldap/slapd.d/cn=config/cn=schema''' total 40 -rw------- 1 openldap openldap 15474 Jun 13 17:39 cn={0}core.ldif -rw------- 1 openldap openldap 11308 Jun 13 17:39 cn={1}cosine.ldif -rw------- 1 openldap openldap 6438 Jun 13 17:39 cn={2}nis.ldif -rw------- 1 openldap openldap 2802 Jun 13 17:39 cn={3}inetorgperson.ldif root@easton2:/tmp# '''_''' To add a schema, you need a schema in LDIF format, which you can then add to the LDAP database using the ''ldapadd'' command. Suppose you have a schema file ''samba.schema'' which you've copied to the ''/etc/ldap/schema'' directory. You'd first convert this to an LDIF file using root@easton2:/etc/ldap/schema# '''slaptest -f samba.schema -F /etc/ldap/schema -s "cn=schema,cn=config"''' ldapadd -x -H ldap://<LDAP SERVER>/ -D "cn=config" -W -f <SCHEMA>.ldif Enter LDAP Password: adding new entry "cn=<SCHEMA>,cn=schema,cn=config" 8ca7d15ac98acd3b1922dceba758f49ae4a3f214 0 1414 2702 2016 2011-07-03T08:35:24Z Saruman! 2 added rkhunter wikitext text/x-wiki ==Essential system software== The following packages we deem quite essential for any Debian (home) server: [[Big Bag'o'utilities]] (not "a" package, but a collection of essential tools like ''less'' and ''sudo'')<br> [[OpenSSH server]]<br> [[vim]] which stands for VI iMproved<br> [[Rootkithunter]]<br> [[Crontab]]<br> [[iproute2]]<br> [[Compilation software]]<br> [[IPtables and firewall]]<br> [[IPsec software]]<br> [[kerneloops]] 070866016212cf3fb0b5b138a2aa15ee3a5b0f1d 0 1621 2703 2011-07-03T08:36:51Z Saruman! 2 stub added wikitext text/x-wiki Rootkithunter guards your system against infection by many rootkits. Installation is of course trivial apt-get install rkhunter After installation, you might need some whitelisting as described in http://machine-cycle.blogspot.com/2011/03/getting-rid-of-rkhunters-false-warning.html a761ddcc749c831fe6259f21f298c32d7effeead 0 1561 2704 2392 2011-08-11T04:27:47Z Saruman! 2 /* General procedure to creat a wikifarm wiki instance */ updated external link wikitext text/x-wiki ==On Wikifarms== ===What is a Wikifarm?=== Wikifarm and the verb Wikifarming refer to the setup and operation of multiple wikis on a single server. This could be because on a single website you want to run multiple wikis (e.g. ''<nowiki>http://www.saruman.biz/linuxwiki</nowiki>'' and ''<nowiki>http://www.saruman.biz/bsdwiki</nowiki>''). Or it could be because you're running multiple websites on a single server (each behind its own IP, or all on the same IP number using virtual hosts), and more than one of these websites needs to have its own wiki. ===Types of Wikifarms=== There are multiple ways to set up a wikifarm; what is the most suitable way for you depends on how you want to use the farm. We can roughly distinguish the following type of farms: * Multiple wikis, each running '''their own code and their own database'''. This is simple to set up when you install the Wiki code base from source - funny enough, under Debian it's ''not'' easy. Also, it's not a recommendable solution from the perspective of maintenance: each wiki must be updated separately when e.g. a security patch is issued for the wiki software. * Multiple wikis, running on '''a shared code base, but each with their own database'''. This is a good solution for multiple wikis for multiple websites. * Multiple wikis, running on '''a shared code base, and on a shared database'''. This could be a good solution for multiple wikis for a single website, because a user can register on one wiki, and automatically have the same account in the other database as well. We're not going to go into the first type, since the shared codebase is more maintainable. Instead, we're going to show how you can share the Mediawiki code base under Debian, so that a Debian update to the Mediawiki package is automatically applied to all instances of your wikifarm. And we'll see that from there, the choice between separate databases or shared databases is quite trivial. ===Wikifarming under Debian=== As with most Linux-based software packages, the MediaWiki package ''mediawiki'' that Debian offers is modified to suit the Debian policies and needs. This means that it has moved all configuration files to reside under ''/etc/mediawiki'', but also that it offers a somewhat better way to include extensions. The downside of these modifications is that creating a wikifarm under Debian is somewhat more complicated than when you're using vanilla MediaWiki sources - mostly because there isn't much documentation on the Internet about it. In the following we'll be documenting one possible way to create a wikifarm. Note that our method is particularly well-suited to "small" wikifarms (a handful of wikis on a single server), and not exactly fit for "big" wikifarms (thousands of wikis on one or more servers). ==General procedure to creat a wikifarm wiki instance== Setting up a wiki under Debian is quite easy - as you might have seen from this wiki's description under entry [[Basic MediaWiki Installation]]. This is because the Debian customization includes specific changes to some MediaWiki files, and to the default configuration files. Thus, the usual methods of creating a wiki instance next to the default one run into an additional obstacle: the forementioned Debian customizations. The way around it is this: * We suppose you've already installed your first wiki. It'll probably be just as described in the [[Basic MediaWiki Installation]]. * Make sure you adapt this first wiki to support virtual hosts, as described in the section on [[Place_MediaWiki_inside_a_Virtual_Host|placing MediaWiki inside a Virtual Host]]. * If your first wiki is running OK, follow the instructions in the next set of sections to move the wiki from its default place to the wikifarm. As a result, your first wiki should still run OK, but the place where Debian expects your wiki to live is now "empty" again * Set up your second wiki as if it were the first one, and move it over to the wiki farm. * et cetera. Because of the manual work involved, this system is not very well suited to "big" wikifarms; for those instances you'd be better off with one of the scripts that creates the wikifarm instance, and populates it with a default database and default configuration file. Scripts and instructions can be found on the Internet, like this one [http://www.jirp.nl/2008/07/27/mediawiki-farm-administer-multiple-wiki-environments/ on jirp.nl].<br> However, the method is quite doable when you've only got a handful of wikis to create, and remains largely compatible with Debians mechanisms for updating packages. ==Debian Mediawiki wikifarm structure== ===The standard Debian MediaWiki structure=== After installation of the ''mediawiki'' package, your server will be expanded with the [[MediaWiki directory structure]]. Within this structure, there are four main branches (if you haven't installed the ''mediawiki-extensions'' package yet): * ''/etc/mediawiki'' contains the configuration files for MediaWiki. * ''/usr/share/doc/mediawiki'' contains the documentation files. * ''/usr/share/mediawiki'' contains the source code. It is not used directly, rather it is linked to from the ''/var/lib/mediawiki'' directory. * ''/var/lib/mediawiki'' contains the site, including links to the configuration files in ''/etc/mediawiki''. Within these branches, we should not delete or move any file or directory, since that will confuse our [[APT and aptitude|Debian package manager]] when an update to the ''mediawiki'' package becomes available, so we strive to minimize the changes to this structure. Furthermore, the default configuration files explicitly declare the wiki to "live" in ''/var/lib/mediawiki'', so we'll designate the wiki in that location as the "default wiki" as opposed by "wikifarm instances" that live e.g. under ''/var/wikifarm/<instancename>''.<br> Another important element of the MediaWiki structure is hidden in its use of the MySQL database: during setup, you either need to have a database user account, or a MySQL superuser account (e.g. 'root'@'localhost') so as to be able to create the wiki database and a database user account. ===Extending the structure for a wikifarm=== First we need a label <instancename>, which designates the name for each wikifarm instance, so that we can label them as we're creating them. Each name needs to be unique because we're going to create directories based on the labels. Note that this label need not be the Wiki name, as you fill it in when [[Basic_MediaWiki_Installation#Configuring_the_Wiki_instance|configuring the default wiki instance]], although you could of course use that name. In our example, we use the domain name of the website on which the wiki instance is running. Thus, this wiki named "SaruWiki" is instance "saruman.biz" in our little wikifarm. Furthermore, you need a database name for each wiki instance that gets its own database, and it should be different from the default database name "wikidb" (unless you ''want'' to put your wiki instance into this default database, together with the wiki or wikis that are already in there). You could use the label you've chosen, or different ones, or derived ones. Remember to observe the MySQL [http://dev.mysql.com/doc/refman/5.0/en/identifiers.html limits on database names] (no more than 64 characters, no slashes or dots in the name, not ending in a space et cetera).<br> In addition, you need a database user name and password. This should not be the same user name and password that you've used to set up any other wiki database, or you'd have a security risk. In the unfortunate case in which you'd feel compelled to reuse a database user name (e.g. the standard "wikiuser"), be sure to reuse the original password of "wikiuser", or risk losing access to the earlier wikis that use that same user. Thus, you could have labels, database names and database username/passwords like this: * saruman.biz and saruman-biz-wiki and saruwikiuser/Gp5Zmull01 * iceditch.nl and iceditchNLwiki and icewikiuser/Br3thReeka1 * ann.example.org and wiki-ann and ann/Tr4p7qqhl2 * bob.example.org and wiki-bob and bobwiki/Gnff3Prkks * charles.example.org and wikiCharles and charles/Pzmel55Fgzxm And remember, they are just labels. You could just as easily use user names, numbers or whatever. For maintainability though, we recommend a consistent scheme with recognizable labels. On the other hand, there are a number of labels you must avoid, because they will come to conflict with directories that already exist: most notably ''config'', ''extensions'' and ''images''. So before you begin, sit down and write out what your label and database name convention will be. This is trivial if you have just a handful of wikis, but can become very important should you ever grow to hundreds of instances. Each wikifarm will need its own set of configuration files, so for each new wiki instance we'll create directories under ''/etc/mediawiki'' using the chosen wiki labels: * ''/etc/mediawiki/saruman.biz'' * ''/etc/mediawiki/iceditch.nl'' * et cetera. Make each of these directories owned by the Apache2 user (''chmod www-data:www-data saruman.biz'' et cetera). Each wikifarm will need its own code base, so for each new wiki instance we'll create directories under ''/opt/mediawikifarm'' using the wiki labels: * ''/opt/mediawikifarm/saruman.biz'' * ''/opt/mediawikifarm/iceditch.nl'' * et cetera. The choice for ''/opt/mediawikifarm'' is quite arbitrary; one could make a case to use ''/var/www'' or ''/var/lib/mediawikifarm/'' or anything like this, but ''/opt'' is meant for optional software, which under Debian is software that's not in the standard repositories. And since the wikifarm isn't, it makes sense to create the links to the codebase there. Each wikifarm may have its own upload directory for images. This directory should not be placed under ''/opt'', but rather in a place where you expect data, e.g. ''/data'' if you have that, or ''/var/www'', or something like this. We have chosen for ''/data/wikifarm/<wikilabel>/images''. ==Linking to the shared code base== As you can see from the [[MediaWiki directory structure]], the code that is actually served in the webserver is in two separate trees: by default the webserver ''thinks'' the full tree is in ''/var/lib/mediawiki'', but a large part of what you find in that spot is actually symlinked to files and directories in ''/usr/share/mediawiki''. Actually, the tree ''/usr/share/mediawiki'' can be thought of as a source code library, and ''/var/lib/mediawiki'' as the instance that we're actually serving. Since an instance needs both source code and some files of its own, we find that ''/var/lib/mediawiki'' contains both links to that source code, as well as actual files and directories. Now we can create links to the code base for each wikifarm instance for themselves. You need to create symlinks in your chosen wiki directory (e.g. ''/opt/mediawikifarm/saruman.biz'') to all files and folders in ''/usr/share/mediawiki'', except the directory ''images'' and the files ''AdminSettings.php'' (if it even exists) and ''LocalSettings.php''. Such a thing can be done simplest with a little script like this: <source lang="bash"> WSRC='/usr/share/mediawiki' WDEST='/opt/mediawikifarm/saruman.biz' cd $WSRC for s in *; do ln -s $WSRC/$s $WDEST/$s done cd $WDEST unlink images unlink AdminSetings.php unlink LocalSettings.php </source> Either run this at the command prompt, or bake it into a little Bash script (it could take the destination directory as a parameter to make it reusable). ==Recreating (moving over) your first MediaWiki instance== We'll assume you've followed the other tips in this wiki. Most notably, you've taken all steps described in the article on "how to [[Place MediaWiki inside a Virtual Host]]". The steps are simple ===Move the Wiki configuration within /etc=== Your Wiki config file will be ''/etc/mediawiki/LocalSettings.php'', and the settings for Apache2 will be in ''/etc/mediawiki/apache.conf''. We'll create a subdirectory under ''/etc/mediawiki'' that hosts the configuration of your Wiki. Suppose we name the subdirectory after the Wiki we're handling, in this example the SaruWiki. Furthermore, suppose that you also have an ''AdminSettings.php'' file. If you don't: no worries! Just skip the steps involved with that file! cd /etc/mediawiki mkdir SaruWiki mv LocalSettings.php SaruWiki mv AdminSettings.php SaruWiki mv apache.conf Saruwiki Note: make sure that after moving the files, the owner and permissions are the same. Moving a file while you are ''root'' has the effect of changing ownership to ''root''. ''LocalSettings.php'' must be owned by user:group ''www-data:www-data'' in order for Apache2 to be able to read the file. The ''AdminSettings.php'' file, if it exists, must be owned by ''root:root'' and NOT be readable by world (permissions 600) because it should contain the MySQL "root" username and password, with which maintenance scripts can perform their tasks if you instruct them to (while you are root, of course). To keep the Wiki running, we're going to need to tell Apache2 where the two files went to. In this case: * change the path to ''apache.conf'' in the ''Include'' statement in the site declaration (e.g. in ''/etc/apache2/sites-available/000-saruman.biz'', change the ''Include'' line to Include /etc/mediawiki/SaruWiki/apache.conf * change the symlink in ''/var/lib/mediawiki'' that points to ''LocalSettings.php''; and if you have one, change the ''AdminSettings.php'' symlink as well: cd /var/lib/mediawiki unlink LocalSettings.php ln -s /etc/mediawiki/SaruWiki/LocalSettings.php unlink AdminSettings.php ln -s /etc/mediawiki/SaruWiki/AdminSettings.php If you now restart Apache2, your Wiki will still work - but the two primary configuration files have moved over to a dedicated spot. Also note that you're not yet using the new codebase - that comes later. ===Move the Wiki website=== So what we now need to do, is to tell the webserver that the full tree can be served from the codebase we prepared. To this end, we need to change the apache2 configuration file ''apache.conf'' of the Wiki, that we've previously copied over to the Mediawiki configuration directory ''/etc/mediawiki/SaruWiki'' and that's included in the Virtual Host file of the saruman.biz website. This file needs to point to the new shared code location; it will look something like this: Alias /wiki /opt/mediawikifarm/saruman.biz <Directory /opt/mediawikifarm/saruman.biz/> Options +FollowSymLinks AllowOverride All order allow,deny allow from all </Directory> # some directories must be protected <Directory /opt/mediawikifarm/saruman.biz/config> Options -FollowSymLinks AllowOverride None </Directory> <Directory /opt/mediawikifarm/saruman.biz/upload> Options -FollowSymLinks AllowOverride None </Directory> Note that we haven't created the upload directory (but we can if we ever need it). Also note that we haven't created the ''config'' directory; that is because we don't need that in this wikifarm instance, because this particular instance has already been configured. Furthermore, we now need to make sure Apache2 can find the (working) ''LocalSettings.php'' from the new wiki location ''/opt/mediawikifarm/saruman.biz'', '''AND''' we need to change a setting within ''LocalSettings.php'' to reflect the new wiki location. For the first bit, we make the correct link(s): cd /opt/mediawikifarm/saruman.biz ln -s /etc/mediawiki/SaruWiki/AdminSettings.php ln -s /etc/mediawiki/SaruWiki/LocalSettings.php (even if you don't have the ''AdminSettings.php'' file yet, you can still make that link). For the second bit, we edit # We define this to allow the configuration file to be explicitly # located in /etc/mediawiki. # Change this if you are setting up multisite wikis on your server. define('MW_INSTALL_PATH','/opt/mediawikifarm/saruman.biz'); This should be enough! Restart Apache2 and test the result invoke-rc.d apache2 restart ==Adding more MediaWiki instances to your farm== So how do you now prepare the next wiki in your farm? Quite simple. We're now going to set up the next wiki in the default place, being ''/var/lib/mediawiki'', after which we can return to the previous step of [[Create_a_Wikifarm#Linking_to_the_shared_code_base|creating another copy of the code base]] and again move the new wiki over from the default location to its location in our fresh wiki farm. So we need to set up the next website with access to the (now empty) default wiki location. We say "now empty" because the default location is lacking a ''LocalSettings.php'' file. In essence then, it is again an empty wiki, for which we'll have to run through the steps of basic configuration, as described in [[Basic_MediaWiki_Installation|basic MediaWiki installation]]. First off, we'll link the next virtual website to the default wiki location. Suppose the next virtual website is called "iceditch.nl", and our wiki database will be called IceditchWiki. We'll start off by creating a location for the IceditchWiki configuration files under the MediaWiki configuration directory: cd /etc/mediawiki mkdir iceditch.nl cp apache.conf iceditch.nl/apache.conf Next, we'll instruct our virtual host to load this new MediaWiki apache configuration file: cd /etc/apache2/sites-available vi 010-iceditch.nl Inside of this virtual host file, we include the MediaWiki configuration; the virtual host file then looks something like this: <VirtualHost *:80> ServerName www.iceditch.nl ServerAdmin webmaster@iceditch.nl DocumentRoot /var/www/iceditch.nl <Directory /> Options FollowSymLinks AllowOverride None </Directory> <Directory /var/www/iceditch.nl> Options Indexes FollowSymLinks MultiViews AllowOverride None Order allow,deny allow from all </Directory> Include /etc/mediawiki/iceditch.nl/apache.conf ScriptAlias /cgi-bin/ /usr/lib/cgi-bin/ <Directory "/usr/lib/cgi-bin"> AllowOverride None Options +ExecCGI -MultiViews +SymLinksIfOwnerMatch Order allow,deny Allow from all </Directory> ErrorLog /var/appslog/apache2/iceditch.nl-error.log # Possible values include: debug, info, notice, warn, error, crit, # alert, emerg. LogLevel notice CustomLog /var/appslog/apache2/iceditch.nl-access.log combined </VirtualHost> Now restart Apache2, and visit the link designated to the new wiki, in this case ''<nowiki>http://www.iceditch.nl/mediawiki</nowiki>''. You'll get the familiar "please set up the wiki first" message. Click it, and manually configure your new wiki. When you're done, move the created ''LocalSettings.php'' to ''/etc/mediawiki'' and you're set! Your new wiki is running in the default position, and as soon as you've moved it to the wikifarm, you can create yet another wiki! ==Debian extensions and your wiki farm== So how about those interesting MediaWiki extensions? Well, if you've [[Mediawiki-extensions_under_Debian|installed package ''mediawiki-extensions'']] then you've got a default structure for handling extensions, that's slightly more intelligent than the standard MediaWiki way, ''and'' helps us a long way towards different extension configurations for our wikis in the farm. In advance we offer you the following information: after installation of ''mediawiki-extensions'', the Debian version of MediaWiki allows you to enable and disable extensions by simply running the command ''mwenext <extension>'' or ''mwdisext <extension>'', e.g. mwenext ConfirmEdit.php It does this by having a directory with symlinks to all availabe extensions, and another directory where you can symlink those extensions that you want enabled. Now this mechanism can be extended to the wikifarm in two different ways: # Per wiki a different selection of all installed extensions is made available. Per wiki in the farm, a selection of those extensions ''that are available to THAT wiki instance'' can be enabled. # All extensions that are installed are available to all wikis in the wikifarm, but for each wiki a different selection can be enabled. We will not describe the first case, but rather the second one. 3c6d4c2f6ad251e4febce8e593d302dbf60436fb 0 1434 2705 2623 2012-01-16T07:16:47Z Saruman! 2 added debugging wikitext text/x-wiki ==Installation of MediaWiki== Here we have the [[Basic MediaWiki Installation|basic installation]] of [http://www.mediawiki.org/ MediaWiki] outlined for you. The default installation will create your wiki in subdirectory ''/mediawiki''. Should you wish to have another name, e.g. ''<nowiki>http://www.yourserver.com/wiki</nowiki>'', then you must make [[Change MediaWiki subpath|two changes]]. ==Extra configuration== After installation of MediaWiki, your Wiki is available on ''every'' Virtual Host you run - unless you follow the instructions to [[place MediaWiki inside a Virtual Host]]. An extra feature we added was support for iFrames by means of a little PHP script that we googled; the extension is called [[The websiteFrame PHP extension| websiteFrame.php]]. Furthermore, we [[wiki footer change |changed the Creative Commons picture]] in the footer from a remote one to a local one. For performance, the following tricks can be used (which we found on [http://mituzas.lt/2007/01/26/mediawiki-performance-tuning this site]): * <pre>apt-get install php-apc</pre> to install a PHP accelerator; * add ''$wgMainCacheType = CACHE_ACCEL;'' (instead of ''CACHE_NONE'') into ''LocalSettings.php'' to enable that installed APC PHP accelerator; * add ''$wgDisableCounters = true;'' into ''LocalSettings.php'' to disable the page counters. On the example site referenced, the cache reduced rendering of an (almost empty) main page from 217ms to 50ms; disabling the page view counter took off another 10ms. Should you wish to customize the look of your MediaWiki wiki, then you must [[MediaWiki skinning|edit the MediaWiki skins]]. ==Extensions== One of the nice things about using something as popular as MediaWiki is the availability of a great number of [http://www.mediawiki.org/wiki/Manual:Extensions extensions]. One of the first things to do, therefor, is to [[mediawiki-extensions under Debian| install the default Debian Mediawiki Extensions package]]. For user management, we added the extensions [[MediaWikiExtension_Password_Reset | Password Reset]] and [[MediaWiki_Extension_-_GroupPermissionsManager | Group Permissions Manager]]. A feature we needed to gain experience for another project was the [http://semantic-mediawiki.org/wiki/Semantic_MediaWiki Semantic MediaWiki (SMW)] extension; it also has a pretty [[Semantic MediaWiki under Debian | simple installation]]. ==Multiple Wiki's on a single server== Some people want to run multiple Wiki instances on one single server - especially so if that server runs multiple websites (the forementioned [[place MediaWiki inside a Virtual Host|Virtual Hosts]]). The answer to that is to [[Create a Wikifarm | create a Wikifarm]].<br> Note that we've set up a [http://www.mediawikifarm.nl/wiki/index.php/Main_Page separate site] for this problem - you're welcome there with any questions you might have on wikifarms on Debian. ==User Rights management== The MediaWiki documentation quite clearly documents [http://www.mediawiki.org/wiki/Manual:$wgGroupPermissions how to manage user rights], but here is a very quick recap: The following user rights are granted implicitly to non-logged-in users: // Implicit group for all visitors $wgGroupPermissions['*' ]['createaccount'] = true; // 1.5.0 $wgGroupPermissions['*' ]['read'] = true; // 1.5.0 $wgGroupPermissions['*' ]['edit'] = true; // 1.5.0 $wgGroupPermissions['*' ]['createpage'] = true; // 1.6.0 $wgGroupPermissions['*' ]['createtalk'] = true; // 1.6.0 So if you want to limit the rights of anonymous users, paste these lines into ''LocalSettings.php'' and change to false those rights that you want to take away. e.g. if you do not want anonymous users to edit pages, set the 'edit' permission to false. Setting 'read' to false requires users to log in before they can read your wiki (but they can still see the sidebar!) The following rights are implicitly granted to all logged-in users. // Implicit group for all logged-in accounts $wgGroupPermissions['user' ]['move'] = true; // 1.5.0 $wgGroupPermissions['user' ]['read'] = true; // 1.5.0 $wgGroupPermissions['user' ]['edit'] = true; // 1.5.0 $wgGroupPermissions['user' ]['createpage'] = true; // 1.6.0 $wgGroupPermissions['user' ]['createtalk'] = true; // 1.6.0 $wgGroupPermissions['user' ]['upload'] = true; // 1.5.0 $wgGroupPermissions['user' ]['reupload'] = true; // 1.6.0 $wgGroupPermissions['user' ]['reupload-shared'] = true; // 1.6.0 $wgGroupPermissions['user' ]['minoredit'] = true; // 1.6.0 $wgGroupPermissions['user' ]['purge'] = true; // 1.10.0 '''NOTE:''' you '''cannot''' let normal users keep a right like 'edit' and take it away for a special group that you create, like 'students'. You MUST grant the group 'user' the ''fewest'' rights that anyone should have, grant extra rights to other groups, and place the right users in these other groups. Examples: $wgGroupPermissions['student' ]['edit'] = false; // WILL NOT WORK The above will NOT "give everyone edit rights except for students". $wgGroupPermissions['*' ]['edit'] = false; // $wgGroupPermissions['user' ]['edit'] = false; // explicitly take away edit from all logged-in users $wgGroupPermissions['staff' ]['edit'] = true; // then give back edit to everyone except standard $wgGroupPermissions['visitingstaff' ]['edit'] = true; // users This WILL work: the edit right is taken away from everyone, including students, untill that right is explicitly restored. Just restore it to the necessary groups, taking care not to restore it to 'students'. So if you want to grant everyone 'edit' except for a particular account - sorry, don't know how that'd work. ==Debugging== Sometimes, stuff breaks. By default, MediaWiki will not show you a great deal of error codes. For debugging purposes, you can put the following lines directly at the top of ''LocalSettings.php'': error_reporting(E_ALL); ini_set("display_errors", 1); $wgShowExceptionDetails = true; $wgShowSQLErrors = true; $wgDebugComments = true; $wgLogQueries = true; $wgDebugDumpSql = true; $wgDevelopmentWarnings = true; $wgDebugProfiling = true; $wgDebugTimestamps = true; $wgDebugPrintHttpHeaders = false; $wgResourceLoaderDebug = true; error_reporting can also be put to E_STRICT. Do NOT forget to remove these lines (comment them out) after you've solved your problems. Having this much error reporting can be of value to hackers etc. ==Other interesting tricks== * [[Wiki news items|Creating news items in a semantic wiki]] * fixing access to a wiki when the sysop forgot his password (method 1, CLI access needed):<br>change directory: ''cd /path/to/mediawiki/maintenance''<br>run the following maintenance script: ''php changePassword.php --user="WikiSysop" --password="TheNewPassword"'' * fixing access to a wiki when the sysop forgot his password (method 2, MySQL access needed):<br>enter the MySQL client using an account with sufficient rights to alter the database of your wiki, then run these MySQL commands on the right database:<br>''UPDATE user SET user_password = MD5(CONCAT(user_id, '-', MD5('TheNewPassword'))) WHERE user_id = 1;'' bda1535c53ee6ae78b04d149d000f0f0c4becc20 10 1622 2706 2012-01-19T10:21:02Z Saruman! 2 Copied a fine multilanguage template wikitext text/x-wiki == Template == <onlyinclude><div class="LanguageLinks"> <table width="100%" style="clear: both; border: 1px solid #aaaaaa; border-collapse: collapse; padding: 0.2em; margin: 0; font-size: 85%; margin: 0 1px;"> <tr valign="top" style="background: #EEF3E2"> <td style="width: 25px; padding-left: 0.5em;">[[Image:Geographylogo.png|25|Languages]]</td> <td style="width: 10px; white-space: nowrap; padding: 4px 1em 0 0.5em; border-right: 1px solid #aaaaaa;">'''[[Project:Language policy|Languages]]:'''&nbsp;</td><td style="padding: 1px 1em 0; background: #F6F9ED;"> '''[[{{{1|:{{NAMESPACE}}:{{BASEPAGENAME}}}}}|English]]''' {{Languages/Lang|ar|{{{1|}}}}} {{Languages/Lang|br|{{{1|}}}}} {{Languages/Lang|ca|{{{1|}}}}} {{Languages/Lang|cs|{{{1|}}}}} {{Languages/Lang|de|{{{1|}}}}} {{Languages/Lang|es|{{{1|}}}}} {{Languages/Lang|fa|{{{1|}}}}} {{Languages/Lang|fi|{{{1|}}}}} {{Languages/Lang|fr|{{{1|}}}}} {{Languages/Lang|he|{{{1|}}}}} {{Languages/Lang|hu|{{{1|}}}}} {{Languages/Lang|id|{{{1|}}}}} {{Languages/Lang|it|{{{1|}}}}} {{Languages/Lang|ja|{{{1|}}}}} {{Languages/Lang|ko|{{{1|}}}}} {{Languages/Lang|mn|{{{1|}}}}} {{Languages/Lang|nl|{{{1|}}}}} {{Languages/Lang|no|{{{1|}}}}} {{Languages/Lang|oc|{{{1|}}}}} {{Languages/Lang|pl|{{{1|}}}}} {{Languages/Lang|pt|{{{1|}}}}} {{Languages/Lang|ro|{{{1|}}}}} {{Languages/Lang|ru|{{{1|}}}}} {{Languages/Lang|sq|{{{1|}}}}} {{Languages/Lang|sr|{{{1|}}}}} {{Languages/Lang|sv|{{{1|}}}}} {{Languages/Lang|vi|{{{1|}}}}} {{Languages/Lang|yue|{{{1|}}}}} {{Languages/Lang|zh|{{{1|}}}}} {{Languages/Lang|zh-hans|{{{1|}}}}} {{Languages/Lang|zh-hant|{{{1|}}}}} </td></tr></table></div></onlyinclude> == Syntax == <nowiki>{{{Languages|PageName}}}</nowiki> * '''PageName''' (optional) - the name of the page to display language links for. If omitted then the English version of the current page is used. This parameter can normally be omitted, as it is only required if you want to link to a page other than the one you place the template on, which is very uncommon. If this parameter is used on a sub-page make sure you supply the root name, not the full page name (e.g. on [[MediaWiki/fr]] you would need to use <code><nowiki>{{{Languages|MediaWiki}}}</nowiki></code> and not <code><nowiki>{{{Languages|MediaWiki/fr}}}</nowiki></code>). == Usage == The template should only be placed on pages that exist in more than one language, and it should be placed in the same location on each translation of the page. The English version of a page is always the main version, with all other languages as sub-pages, named using the appropriate language code (see below). For example, on the Main Page you would include the text <code><nowiki>{{{Languages}}}</nowiki></code>, both on [[Main Page]] itself, and on each of its language sub-pages. The template automatically creates links to any language sub-pages that exist, e.g. <tt>Main Page/ja<tt>, <tt>Main Page/fr</tt>, and ignores non-existant languages. See [[Project:Language policy]] for further details about translating pages. See [http://info.epiconcept.fr/mediawiki/index.php/Template:Languages Epiconcept.fr] for the original template. == Supported languages == This shows you the name of each language's sub-page (using ''Main Page'' as an example). Other languages may be added easily as necessary. Please use the appropriate [[meta:List of Wikipedias|prefix, as used on Wikipedia]] when adding a new language. Please do ''not'' add languages for which no pages exist yet, as this will increase the time needed to include the template without adding any benefit (languages are only displayed to the user when the relevant page exists). The link on the language names goes to the Wikipedia in that language. '''If no Wikipedia in your language exists, do not add pages in that language to MediaWiki.org!''' This wiki is not the place for language advocacy - please go through the correct channels, and once your language has a Wikipedia then please return to add content here. {| border="1" cellpadding="5" ! Page Name || Language |- | Main Page || [http://en.wikipedia.org/ English] |- | Main Page'''/ar''' || [http://ar.wikipedia.org/ Arabic] |- | Main Page'''/br''' || [http://br.wikipedia.org/ Breton] |- | Main Page'''/ca''' || [http://ca.wikipedia.org/ Catalan] |- | Main Page'''/cs''' || [http://cs.wikipedia.org/ Czech] |- | Main Page'''/de''' || [http://de.wikipedia.org/ German] |- | Main Page'''/es''' || [http://es.wikipedia.org/ Spanish] |- | Main Page'''/fa''' || [http://fa.wikipedia.org/ Persian] |- | Main Page'''/fi''' || [http://fi.wikipedia.org/ Finnish] |- | Main Page'''/fr''' || [http://fr.wikipedia.org/ French] |- | Main Page'''/he''' || [http://he.wikipedia.org/ Hebrew] |- | Main Page'''/hu''' || [http://hu.wikipedia.org/ Hungarian] |- | Main Page'''/id''' || [http://id.wikipedia.org/ Indonesian] |- | Main Page'''/it''' || [http://it.wikipedia.org/ Italian] |- | Main Page'''/ja''' || [http://ja.wikipedia.org/ Japanese] |- | Main Page'''/ko''' || [http://ko.wikipedia.org/ Korean] |- | Main Page'''/nl''' || [http://nl.wikipedia.org/ Nederlands] |- | Main Page'''/no''' || [http://no.wikipedia.org/ Norwegian] |- | Main Page'''/oc''' || [http://oc.wikipedia.org/ Occitan] |- | Main Page'''/pl''' || [http://pl.wikipedia.org/ Polish] |- | Main Page'''/pt''' || [http://pt.wikipedia.org/ Portugese] |- | Main Page'''/ro''' || [http://ro.wikipedia.org/ Romanian] |- | Main Page'''/ru''' || [http://ru.wikipedia.org/ Russian] |- | Main Page'''/sq''' || [http://sq.wikipedia.org/ Albanian] |- | Main Page'''/sr''' || [http://sr.wikipedia.org/ Serbian] |- | Main Page'''/sv''' || [http://sv.wikipedia.org/ Swedish] |- | Main Page'''/vi''' || [http://vi.wikipedia.org/ Vietnamese] |- | Main Page'''/yue''' || [http://yue.wikipedia.org/ Cantonese] |- | Main Page'''/zh''' || [http://zh.wikipedia.org/ Chinese] |- | Main Page'''/zh-hans''' || [http://zh-hans.wikipedia.org/ Chinese (Simplified)] |- | Main Page'''/zh-hant''' || [http://zh-hant.wikipedia.org/ Chinese (Traditional)] |} == Example == Here is how the language bar looks on the [[MediaWiki]] page: {{Languages|MediaWiki}} [[Category:Language templates]] 2af1c2892cdb8f16c85ca77404ccdb68f43b1bc0 10 1623 2707 2012-01-19T10:22:27Z Saruman! 2 Copied a fine multilanguage template wikitext text/x-wiki <includeonly>{{#ifexist: {{#if: {{{2|}}} | {{{2}}} | {{#if: {{NAMESPACE}} | {{NAMESPACE}}:}}{{BASEPAGENAME}}}}/{{{1}}} | &nbsp;&bull;&nbsp;<span lang="{{{1}}}">{{#if: {{{2|}}}|[[{{{2}}}/{{{1}}}|{{#language:{{{1}}}}}]]| [[:{{NAMESPACE}}:{{BASEPAGENAME}}/{{{1}}}|{{#language:{{{1}}}}}]]}}</span>|<span></span>}}</includeonly><noinclude> == Template == ''This sub-template doesn't display properly when not included. Please see [[Template:Languages]] for the complete version.'' == Usage == This template is designed to simplify [[Template:Languages]], by allowing a simpler syntax for adding new languages. Each language is included by calling this template with the following parameters: * '''Language code''' (e.g. fr) * (optional) '''Page name''' - if not supplied the page is automatically worked out based on where the language template is included. This template should not be used anywhere except in the Languages template. [[Category:Language templates]] </noinclude> a62467e9ffea947d5fc439ced16954e21153a2e5 6 1624 2708 2012-01-19T10:33:29Z Saruman! 2 wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 4 1625 2709 2012-01-19T10:39:14Z Saruman! 2 explanation in short wikitext text/x-wiki How do I add just a multilingual page? * Create a page name ''pagename'' (This page contains the reference language, on this site English); * Set <nowiki> {{Languages​​}} </nowiki> at the top of the page ''pagename''; * To add a page in Dutch, create the page ''pagename/nl'' (''/es'' for Spanish etc); * Go to the tab to edit and copy the contents of the page; * Return to the base page that has been changed to a redirect and make a paste; * Set <nowiki> {{Languages ​​| </nowiki>''pagename''<nowiki>}} </nowiki> at the top of the page ''pagename/nl''. Thanks to [http://info.epiconcept.fr/mediawiki/index.php/NGO_Epiconcept:Language_policy epiconcept.fr] for the templates that make this work. 573d3575cd64fb9cd36aea126318c4e180ca8e05 10 1626 2710 2012-01-19T10:40:09Z Saruman! 2 added, mainly as an example wikitext text/x-wiki == Modèle == {{Languages|Template:Languages}} == Syntaxe == <nowiki>{{{Languages|PageName}}}</nowiki> * '''PageName''' (facultatif) - le nom de la page pour laquelle on veut afficher les liens vers différents langages. Si cette option n'est pas précisée, le nom de la page en anglais est utilisé. Normalement ce paramètre n'est pas nécessaire, il n'est utile que lorsqu'on veut mettre un lien vers une page autre que celle dans laquelle le modèle se trouve (ce qui se produit assez rarement). Si ce paramètre est utilisé dans une sous-page, il faut utiliser le nom de la ''page mère'' et pas le nom complet de la sous-page (par exemple, dans la sous-page [[MediaWiki/fr]] on doit utiliser <code><nowiki>{{{Languages|MediaWiki}}}</nowiki></code> et pas <code><nowiki>{{{Languages|MediaWiki/fr}}}</nowiki></code>). === Note === Sur cette page, pour que la barre de langues s'affiche correctement, il a fallu utiliser l'option PageName, autrement seul le lien vers la version anglaise s'affichait. == Utilisation == Le modèle ne devrait être utilisé que sur des pages qui existent dans plusieurs langues et, pour des raisons évidentes de clarté et d'ergonomie, il devrait être placé au même endroit dans la page pour chacune de ces traductions (par exemple, il faut éviter de mettre le <nowiki>{{{Languages}}}</nowiki> en haut sur la page en anglais et en bas sur la page en français) . La version anglaise d'une page est toujours la version principale (page mère) et les autres langages n'en sont que des sous-pages, nommée en utilisant le code de langue approprié (voir ci-dessous). Par exemple, sur la page d'accueil, on peut trouver <code><nowiki>{{{Languages}}}</nowiki></code> à la fois sur [[Mediawiki]] et sur chacune des sous-pages de langue ([[Mediawiki/fr]] pour le français). Le modèle crée automatiquement les liens vers les pages de langues qui existent (<tt>Main Page/ja<tt>, <tt>Main Page/fr</tt>) et ignore les langages pour lesquels une traduction n'est pas disponible. Voir [[Project:Language policy/fr]] pour plus de détails à propos de la traduction des pages. == Langages supportés == Voici la liste des langages supportés (en utilisant la page d'accueil comme exemple). D'autres langues peuvent être ajoutées si nécessaire (faire la demande sur la [[Template_talk:Languages|page de discussion anglaise de ce modèle]]). Pour l'instant, il semble qu'un langage ne puisse être ajouté que s'il existe une Wikipédia dans cette langue (à ce sujet, voir la version anglaise de cette page) {| border="1" cellpadding="5" ! Page Name || Language |- | Main Page || [http://en.wikipedia.org/ Anglais] |- | Main Page'''/ar''' || [http://ar.wikipedia.org/ Arabe] |- | Main Page'''/br''' || [http://br.wikipedia.org/ Breton] |- | Main Page'''/ca''' || [http://ca.wikipedia.org/ Catalan] |- | Main Page'''/cs''' || [http://cs.wikipedia.org/ Tchèque] |- | Main Page'''/de''' || [http://de.wikipedia.org/ Allemand] |- | Main Page'''/es''' || [http://es.wikipedia.org/ Espagnol] |- | Main Page'''/fa''' || [http://fa.wikipedia.org/ Persan] |- | Main Page'''/fi''' || [http://fi.wikipedia.org/ Finnois] |- | Main Page'''/fr''' || [http://fr.wikipedia.org/ Français] |- | Main Page'''/he''' || [http://he.wikipedia.org/ Hébreu] |- | Main Page'''/hu''' || [http://hu.wikipedia.org/ Hongrois] |- | Main Page'''/id''' || [http://id.wikipedia.org/ Indonésien] |- | Main Page'''/it''' || [http://it.wikipedia.org/ Italien] |- | Main Page'''/ja''' || [http://ja.wikipedia.org/ Japonais] |- | Main Page'''/ko''' || [http://ko.wikipedia.org/ Coréen] |- | Main Page'''/nl''' || [http://nl.wikipedia.org/ Néerlandais] |- | Main Page'''/no''' || [http://no.wikipedia.org/ Norvégien] |- | Main Page'''/pl''' || [http://pl.wikipedia.org/ Polonais] |- | Main Page'''/pt''' || [http://pt.wikipedia.org/ Portugais] |- | Main Page'''/ro''' || [http://ro.wikipedia.org/ Roumain] |- | Main Page'''/ru''' || [http://ru.wikipedia.org/ Russe] |- | Main Page'''/sq''' || [http://sq.wikipedia.org/ Albanais] |- | Main Page'''/sv''' || [http://sv.wikipedia.org/ Suédois] |- | Main Page'''/vi''' || [http://vi.wikipedia.org/ Vietnamien] |- | Main Page'''/yue''' || [http://yue.wikipedia.org/ Cantonnais] |- | Main Page'''/zh''' || [http://zh.wikipedia.org/ Chinois] |- | Main Page'''/zh-hans''' || [http://zh-hans.wikipedia.org/ Chinois (Simplifié)] |- | Main Page'''/zh-hant''' || [http://zh-hant.wikipedia.org/ Chinois (Traditionnel)] |} == Exemple == Voici ce à quoi la barre de langues ressemble sur la page [[MediaWiki]] : {{Languages|MediaWiki}} aae21873ae7a92fdecb24ffdacc8ca940170e3d1 0 1466 2711 2622 2012-02-29T07:28:08Z Saruman! 2 /* MySQL commands */ user rights mgmt wikitext text/x-wiki == MySQL installation == As with any package to be installed: use aptitude, update your APT, then make sure all your (other) software is up-to-date. Then find package ''mysql-server'' - under Debian 5.0 "Lenny" it'll be version 5.0.51a-something. Installing it will also automatically install some dependent packages, like mysql-common, mysql-client etcetera. So after downloading some 40MiB of files, MySQL is installed. The installation script under Debian Lenny asks you for a password for the MySQL root user. Think up a strong password for the MySQL root user; something like ''waYacUbaT2uW''. DON'T use this example password, [http://www.pctools.com/guides/password/ generate your own one!]. DO NOT use the password of the Linux ''root'' user. Should you consult [http://dev.mysql.com/doc/refman/5.0/en/unix-post-installation.html the official MySQL documentation], you might see mention of the ''mysql_install_db'' script - do not worry about that, since Debian has run it for you when it was setting up the database. The standard user accounts that have been created by the installation script are: * 'root'@'localhost' * 'root'@'<hostname>' * 'root'@'127.0.0.1' All three root accounts are secured with the same password, the one you specified when installing the package ''mysql-server''. ---- '''NOTE for Debian 4.0 "Etch"''' When you install MySQL under Etch, there are two root accounts with empty passwords, and two anonymous accounts. NOT safe! You'll want to rectify this in order to secure your MySQL server. Please take the following steps. Start the MySQL client from the command line: mysql -u root Then, from the mysql client prompt, set the password for the MySQL root users. They can be treated as two different accounts, but we don't recommend that. We thus give both accounts the same password: mysql> SET PASSWORD FOR 'root'@'localhost' = PASSWORD('waYacUbaT2uW'); mysql> SET PASSWORD FOR 'root'@'<hostname>' = PASSWORD('waYacUbaT2uW'); Furthermore, there are two anonymous accounts created. These also have no password, and get full permission on the ''test'' database, as well as on any database who's name begins with ''test_''. These accounts can be fitted with a password (like we did for root - just use two quotes with nothing in between them, instead of two quotes with ''root'' in between), or they can be removed - which we recommend. The (single) command for this is: <pre>mysql> DROP USER '';</pre> '''End of NOTE''' ---- To verify the installation you might want to take some of the following steps: * run ''mysqlshow -u root -p'', and see if that command outputs at least two databases (''information_schema'' and ''mysql''); * check out the settings of your MySQL server by running ''mysqladmin -u root -p variables'' (piping the output to ''less'' or a file, if necessary); * have a peek in ''/var/lib/mysql''; the database data files should be there; * check ''/var/log'' for two logfiles ''mysql.err'' and ''mysql.log''. ==Moving the MySQL databases== By default the location of your Debian MySQL databases is ''/var/lib/mysql/<database>''. However, sometimes you wish your databases to be in a different location. E.g. ''/data/mysql'', where ''/data'' is a mounted dedicated RAID array. Or perhaps even ''/data/mysql'' is its own array. Whatever the reason, to move ''all'' MySQL databases from ''/var/lib/mysql'' to another location, you can follow these steps: * Create the new directory, e.g. ''/data/mysql'' * Make this directory owned by user/group ''mysql'' cd /data mkdir mysql chown mysql:mysql mysql * Shut down the database server with one of the following commands: mysqladmin -u root -p shutdown invoke-rc.d mysql stop * Make a backup copy of ''/etc/mysql/my.cnf'', then edit this file. Find the section ''[mysqld]'' and change the line ''datadir = /var/lib/mysql'' to datadir = /data/mysql * As root, move (or better yet: copy) ''all'' of the content of ''/var/lib/mysql'' over to ''/data/mysql''. Make sure you don't accidentally change the ownership or permissions of the files and folders in the ''/var/lib/mysql'' folder. We expect each and every file and folder to be owned by ''mysql:mysql''. Copy command would be (as root): cp -p -r /var/lib/mysql/* /data/mysql * Check and doublecheck your ''my.cnf'' settings and your database file owners, attributes and size. After the next step, there ''may'' be no way back! * Start up your database server: invoke-rc.d mysql start * Check the working of your MySQL server: ** issue the following command to get status information (to see if MySQL is running after your start command): invoke-rc.d mysql status ** look under ''/var/log'' for the default MySQL log files ''mysql.log'' and ''mysql.err'' ** check your SysLog (standard: ''/var/log/syslog'') for MySQL error messages, since the default Debian configuration is to log MySQL errors there, rather than in the previously mentioned MySQL logfiles. == MySQL commands == The following are examples of the most common MySQL commands <pre><nowiki> SELECT User,Host from mysql.user; SHOW GRANTS FOR '<user>'@'<host>'; GRANT <right>, <right2> ON <database>.* TO '<user>'@'<host>'; REVOKE <right>, <right2> ON <database>.* FROM '<user>'@'<host>'; SHOW DATABASES; USE <database>; SHOW TABLES; DESCRIBE <table>; SELECT <col1>,<col2>...<col_i> FROM <table> WHERE <column> = '<value>'; INSERT INTO <table> (<col1>,<col2>...<col_i>) VALUES ('<val1>','<val2>'...'<val_i>'); UPDATE <table> set <col1> = '<value1>' WHERE <column> = '<value>'; DELETE FROM <table> WHERE <column> = '<value>'; </nowiki></pre> Ofcourse there are more useful commands, see the MySQL website. 6aa72fffb07f1535d48f41d53571df767ee5e170 1 1627 2712 2012-02-29T15:46:26Z 212.238.151.172 0 test wikitext text/x-wiki hurray, anonymous talk enabled 364808efd38c3bb72018f70197cf8e45824b9e77 0 1628 2713 2012-03-12T14:16:55Z Saruman! 2 page copied wikitext text/x-wiki <big>'''Debian Wheezy Base Server setup'''</big> ==Getting the hardware== {| class="wikitable" border="1" |- |Note: in the following we're assuming you'll be assembling an x86 or x64 type of machine, as it has about the best price/performance ratio you could wish. Hardware costs for other platforms, e.g. IBM's Series p or HP 9000, can be much higher, while platforms like ARM are energy efficient, but just not very powerful. Also, the availability of components and of help can be less than with the ubiquitous x86/x64 platforms. |} Naturally, before we can begin to install the operating system, we need to obtain the necessary hardware. Which hardware you require depends on what you want the server for; a test server on which you will test only a single feature for a short while does not need the same quality of hardware as does a server that's supposed to act as a home server for many tasks for a long time. We'll assume your server will be like ours: a home server that must perform many tasks with sufficient performance for a few users, that's reliable and will last for a couple of years. So build or obtain a server with at least the following hardware: * a spacious casing with big, quiet cooling fans, like the [http://www.coolermaster.com/products/product.php?act=detail&id=317 one we have]; * an efficient, heavy-duty power supply that's rated high enough for your devices, and has a decent efficiency. For example, a [http://www.corsair.com/products/power_supplies.aspx Corsair HX520] power supply; * a server class motherboard, e.g. an [http://www.intel.com/content/www/us/en/motherboards/server-motherboards/server-board.html Intel] or [http://uk.asus.com/Server_Workstation/Server_Motherboards/AMD_Dual_Processor AMD] based motherboard. DO NOT go for the cheapest motherboard you can find: if you pay peanuts, that's what you'll get. Server class motherboards have the quality, stability and durability you'll need from it, and usually also most of the needed peripherals, like multiple ethernet network cards on-board. Usually a Linux server does not require much in the way of video performance (and the screen will be used rarely, if ever), so any old integrated graphics will do. * a matching CPU - or multiple, if you think you need the power and the selected motherboard has the sockets. Furthermore, it pays to think about the energy use of your server CPU. For instance, you could choose an AMD Athlon X2 5600+, running at 2,8 Ghz and 89W maximum, but you can also go for an AMD Athlon X2 4850E, which is dualcore at 2,5GHz, but uses only 45W maximum - almost half of the former! And over a one year period, this choice can save up to 385 kWH. With electricity costing close to €0,25 per kWH (at least for some of us), that could save you €96,- a year (assuming your CPU is running at top speed all the time - which it won't). All I'm saying is: think about power use. * a CD-ROM- or DVD-player - although you might not need it any more after installation. Thus, you may opt to use an external USB DVD-player, if your system allows for booting from it. * ''multiple'' hard disks - you'll want redundancy, because every hard disk fails at some time. The drive with your data on it will fail fatally when it is most inconvenient to you, and any data on it that you consider valuable will likely be lost forever. To make Murphy's work somewhat harder for him, we're going to store our data redundantly, so that if any drive in the server fails, we'll not lose our data or our server. Thus, get yourself at least two hard disks for your operating system, at least 40GiB in size (don't think you'll be able to buy smaller ones nowadays), and spanking new (NEVER use old hard disks for your production server, new ones are just too cheap to run that risk!). You may also consider using 2.5" "notebook" hard disks, since they also consume less power than do 3.5" hard disks. However, you should investigate before buying SSDs for your Linux server, as there are some caveats there. We're not going into that subject here. * (multipe) network card(s) (NICs) if your motherboard does not have enough NICs integrated on-board. You'll want a NIC for your network, and another one for your Internet connection; and possible a third one for the wireless segment of your network. Now build a machine out of the above, or have someone build it for you. ==Preparation of the hardware== (Note: in the following we're again assuming you're running an x86/x64 type of machine. Hardware requirements and preparation for other platforms, e.g. IBM's Series p or HP 9000, can differ significantly) Next, check the assembled hardware: * is the configuration complete? If it does not have a CD/DVDplayer from which it can boot, then installing the software gets more difficult - at least get an USB external DVDdrive or something like that. * are all components connected properly (memory modules seated correctly in their sockets, AGP card inserted correctly into the AGP slot, et cetera) and are all cable connections made (multiple power cables to the motherboard, one power cable plus one data cable to each hard disk, etcetera)? Following this, you may hook up the machine. It's going to need power, and you will need at least a keyboard and a monitor attached. And if you want to use a Graphic User Interface to install, a mouse is required also. When you've ensured that everything is safe, you can turn on the machine, and continue to check it: * do all fans start to run when you turn on the machine? (if not, then '''quickly''' turn off your machine and correct the problem!) * does/do the hard disk(s) spin up? * do the power button and reset button operate correctly? * are the power led, HDD led and other display gadgetry functional? * when you let the machine power up, does it emit a single beep? And does it then show a Power-On Self Test screen (POST)? * Does it show the correct amount of memory in the POST screen? The correct number & speed of the CPU(s)? * Does the machine recognise all controller cards (SCSI, S-ATA etc)? And all attached DVD-drives and hard disks? * are all BIOSes/firmwares up to date? * If you have a hardware RAID controller, are your RAID arrays built already? * does the machine attempt to boot from at least the hard disk? ...et cetera. If there is any problem, or you want to update the BIOS or firmwares, it's best to do it before the operating system is installed. This Wiki, however, is not the place to get the information on how to accomplish these type of tasks. The last steps in the preparation of the hardware, are * to ensure that the machine can boot from CD/DVD, so that you can start installing Debian from it. It is possible to install Debian over the network, but that requires setting up a [http://www.debian-administration.org/articles/478 PXE Boot server] which is (currently) outside the scope of this wiki. * to connect the hardware to the Internet, so that it can get all required updates etcetera; please do ''not'' connect the box ''straight'' to the Internet, but make sure that it's safely behind a firewall, or failing that, a NAT router. By now the system should be almost ready to receive it's Operating System. But first we have an issue to tackle: that of redundancy. ==Software or hardware RAID== Your hard disks will fail. They absolutely will. It is never a question of "if", only of "when". So what will you do when the hard disk containing your complete operating system fails (besides pulling your hair out, that is)? What we propose is this: hard disks are pretty cheap nowadays, so let's use [http://en.wikipedia.org/wiki/Redundant_array_of_independent_disks RAID technology] to make our hard drive space resilient against failure of a whole drive. So first make sure that you have ''two'' disks of equal size instead of only one. Had you already been planning to use multiple disks already, then make sure you have at least ''one'' disk more than your space requirements prescribe; the space on that extra drive will provide the needed redundancy. Next, [[RAID fundamentals under Linux | click here]] to learn a bit more about RAID, to make the decision to use hardware-based and/or software-based RAID, and to plan your RAID arrays. In this example, we'll assume you're using hardware RAID on a RAID controller that's supported by the Debian installation software. This means that the installation software will "see" your RAID array(s) and present them as usable drives. ==Planning your network names== If your machine must become a part of an existing network, then it's almost certain that you already have a DNS domain in place; in that case: obtain the DNS suffix your machine will get (the DNS domain your machine will "belong" to). However, it's also possible that this machine is going to be the first machine in your new network, in which case the whole issue of DNS suffixes is wide open. If you need more information on DNS, go [[http://www.isc.org/sw/bind/arm95/Bv9ARM-all.html#id2564824 here]]. For now we'll assume you have (or will quickly obtain) a working knowledge of the DNS system. Here is our tip on choosing a DNS domain for your home network: * do '''not''' use a publicly registered domain name (e.g. "cocacola.com") for any machine that's not primarily intended to serve the public on the Internet; * for machines serving a private network, we urge you to use Top Level Domain name "lan" (to signify your machine is on a Local Area Network or LAN) * for the Domain Name itself, we suggest you use a level 2 name, like "saruman.lan", and not a level 3 name, like "mister.saruman.lan". This is only a short section on DNS, but remember that once a proper DNS system is in place, it's pretty much work to change it. At any rate, this section has most likely showed you that you need to put some thought into the DNS Domain Name design of your home network. OK, with this out of the way, we can get to installing the OS. ==Operating System installation== To install an Operating System (OS), it's kinda instrumental that you have one. Here, we're going to use [http://www.debian.org/intro/about Debian], the biggest [http://www.debian.org/intro/about#free Free] OS that we know of. Free stands for Freedom, but incidentally that Freedom also means it's gratis, an appealing aspect of Free. To get your own copy of Debian, go to their [http://www.debian.org/distrib/ download site] and obtain the latest [http://www.debian.org/releases/ Stable] image - in this wiki it's Debian 6.0, or "Squeeze" as it's also known. Besides the choice which release of Debian you want to run, you also have to know for which platform you're downloading (in our case: either ''amd64'' or ''i386'' depending on your hardware platform) and what kind of install you wish - if you have a working, fast Internet connection available at the time of install, then we recommend getting the [[http://www.debian.org/CD/netinst/ netinst] CD image; it's a relatively small CD, that'll be able to get you going, but gets most of the software you'll need straight from the 'net at install time. In the example at hand we're installing on an AMD Athlon x2-based server, on which we wish to install 64-bits software. We'll download [http://cdimage.debian.org/debian-cd/6.0.1a/amd64/iso-cd/debian-6.0.1a-amd64-CD-1.iso debian-6.0.1a-amd64-CD-1.iso], which is Squeeze after its first update. Burn this to a CD-recordable and boot your prepared hardware platform from this CD. After booting from the CD, a friendly graphic screen shows you the Installer boot menu. Your choices are * Install, the default non-graphical installation; * Graphical install, so you can click things; * Advanced options, where you can select expert options like the rescue mode; * Help; this drops you to a non-graphical screen where you can select help texts by using function keys. The screens explain how you can start the installation with extra parameters to instruct Debian to handle your hardware in a non-standard way, e.g. on an old machine with a problematic videocard you could run "install vga=771" (for some laptops) or "install vga=normal fb=false" (to disable the screen framebuffer). We're going to use the standard Command Line installation, so we choose "Install" and hit &lt;enter&gt;. {| class="wikitable" border="1" |- |We could easily use "Graphic install", in which case we'd have a nice fresh Graphical User Interface for our installation. ''We're'' not going to, because we're real men, and [http://isg.ee.ethz.ch/tools/realmen/ Real Men Don't Click]. Also, we've found that from the GUI it's hard to switch to a second console and then back. We could also go to the Advanced options, and opt for "Expert install" or "Graphical expert install" as installation method, because it gives a much finer grain of control; however we usually don't need that control, and can do without the barrage of extra questions that the "expert" installation method pose. |} After the Linux kernel finishes initializing the machine, a simple text-based installer appears that immediately starts asking questions. Answer them according to your needs. Our example system uses the following choices: * Language: English * country: other &gt; Europe &gt; Netherlands * locale (since there's no default locale for the combination Netherlands/English): United States - en_US.UTF-8 * keymap: American English (since we have a keyboard with US layout) Some installation software loads, and we get to the next phase: if you have multiple NICs in your machine (which we believe you ''should'' have!!), and if they're detected properly, then you're required to indicate which of the detected network interface cards (NIC) is going to be the "primary" NIC. {| class="wikitable" border="1" |- |Here, trouble could begin. If your machine has only network cards that are '''not''' supported, then you'll see '''no''' cards here - but then how are you going to do a NetInstall? A solution would be to (temporarily) install a NIC that ''is'' supported, like a cheap Realtek card, or an old 3Com 905 card. Then, when the whole system is installed, up and running, you could compile a new kernel that contains support for your actual NICs, and when these work, remove the temporary NIC. For now, we'll assume that at least one of your NICs is recognised properly by the Debian installation routine. |} Select the card that's connected and has (indirect) access to Internet (again: it should ''not'' be connected straight to the wild wild web, but sit safely behind a firewall, at least until we've installed our own firewall); if at all possible, let it be the NIC that'll be connected to your home network itself, on the ''inside'' of your server. Let's assume that this NIC is designated ''eth0'' by the Debian installation. This card will now be configured using DHCP, so if you're on a network with a DHCP-server, the network will work straight away. If it's not, you can either configure the network manually or fix your DHCP-server and connection between it and ''eth0''. Next is one of the hardest questions that any OS installation is going to ask you: what will be the host name of the system? You could easily change it at any time in the future, but possibly with lots of hassle, so you better choose wisely. Here are our tips: * do '''not''' name your machine after the user that's going to use it, e.g. "bernie-pc" (at some time in the future, Bernie's machine will be moved to Alice, so then Alice is working on "bernie-pc" which makes the situation quite unclear); * do '''not''' name your machine after the department or workgroup that's using it most, e.g. "accounting-srv" (same reasoning); * do '''not''' name your machine after it's main function, e.g. "printserver" (at some time in the future, the main function is moved to another machine, and/or an alternative function will become the main function of the machine); * do '''not''' name your machine after it's location, e.g. "srv-boston" (at some time in the future, the box will be moved to another location); * do '''not''' name your machine after it's hardware configuration, e.g. "ibmx346" (at some time in the future, either another xSeries x346 will be wheeled in, or the machine will be upgraded to accomodate increased use or overcome hardware problems - your "ibmx346" could suddenly be running on an xSeries x3650). What we feel are safe names for ''any'' machine in your network are true names, perhaps linked to a common theme: names of European cities, names of movie characters, names of countries or holiday destinations et cetera. Less imaginative would be coded names like "server0001". Immediately following comes the question of the Domain Name. This is about a DNS domain, so effectively the installation program is asking which DNS suffix the host name should have; if the DHCP-server already provided something it'll be suggested, but you can override it if need be. In the preparatory phase, you'll have decided on continuation of your current DNS schema, or starting a new one. Either way, put the chosen DNS suffix in and press &lt;enter&gt;. Next comes one '''VERY''' important question: what to use as root password? We cannot stress this enough: choose a SAFE password! Do NOT go for an easy-to-remember one, go for STRONG and SAFE. There are tools to help you generate strong passwords, like [http://www.pctools.com/guides/password/ this page]: use them! We strongly suggest 10 characters or more, including letters, mixed case, and numbers, so something like ''SuCRe4hecH'' (do NOT use this, generate your own!). Next, give the full name of the principal user of this server (your own, we assume), give the login-name (your given name, we assume), and a corresponding password. Again, use a SAFE password. As long as you don't make your principal user equivalent to root, you might go for a slightly weaker password (8 characters instead of 10), but we rather suggest you make the password just as strong (and different from!) the root password. After entering the details of these two users "root" and "you", we get to the server hardware. ==Partitioning== Now comes the question of partitioning, or how to divide the available disk space into chunks for the server to use. This is a tricky subject, because if you put all storage space into one partition, then some day a runaway process will fill up the entire disk with useless logs, and the system will crash. On the other hand, if you divvy up all space into little chunks, then some application is going to need space in one of those partitions where there is none, even though there may be plenty in other partitions. To minimize the chance of either problem occurring, we're going to use [http://tldp.org/HOWTO/LVM-HOWTO/whatisvolman.html Logical Volume Management (LVM2)] so that we can provision enough space to start our server, but keep some space in reserve to apply when needed, where it'll be needed. So, we at Saruman.biz have put together a recommended standard partitioning scheme. The basis (in accordance with the standard [[Debian directory structure]] is this: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Partition !style="background:#ffdead;"|MD !style="background:#ffdead;"|LVG !style="background:#ffdead;"|LV-name !style="background:#ffdead;"|Size <br> (physical machine) !style="background:#ffdead;"|Size (VM) !style="background:#ffdead;"|File System !style="background:#ffdead;"|Mount point |- | 1 | /dev/md0 | &nbsp; | &nbsp; | 100MiB | 100MiB | ext3 | /boot |- | 2 | /dev/md1 | &nbsp; | &nbsp; | 3GiB | 1GiB | ext3 | / |- | rowspan="8" valign="top" | 3 | rowspan="8" valign="top" | /dev/md2 | rowspan="8" valign="top" style="background:lightgrey"| system | style="background:lightgrey" | swap | 1GiB<ref name="swap">Rule of thumb: twice the size of the machine's RAM, but no less than 256MiB and no more than 2GiB</ref> | 256MiB<ref name="swap"/> | swap | &nbsp; |- | style="background:lightgrey" | var | 1GiB | 512MiB | ext3 | /var |- | style="background:lightgrey" | varlog | 1GiB | 512MiB | ext3 | /var/log |- | style="background:lightgrey" | appslog | 3GiB | -<ref>Yes, we think a separate ''appslog'' is a very good idea, but when creating a minimal VM, we have to save disk space ''somewhere''...</ref> | ext3 | /var/appslog |- | style="background:lightgrey" | home | 1GiB<ref name="home">Note that this heavily depends on the purpose of the machine; if it is not to house any users, then (almost) no space is needed for /home. But on the other hand if e.g. a virtual user is to be used for keeping mailstores, or other service users need home space, then /home needs to be big enough for that.</ref> | 512MiB<ref name="home"/> | ext3 | /home |- | style="background:lightgrey" | usr | 3GiB | 3GiB | ext3 | /usr |- | style="background:lightgrey" | tmp | 1GiB | 512MiB | ext3 | /tmp |- | style="background:lightgrey" | opt | 1GiB | - | ext3 | /opt |- ! colspan="4" style="text-align:right"| Total ! 18.1GiB ! 6.9GiB ! colspan="2" | |- |} As you can see, the partition table works as follows: we assume that we wind up with 3 partitions, either on three separate software RAID arrays (''md0'' through ''md2'') or on one single hardware RAID array (in which case the 2nd column ''MD'' does not apply). The size of the partitions depends on your machine's make: for standard physical machines the 5th column does sensible suggestions, even though you could choose to have different sizes and of course different divisions altogether. If your machine happens to be a virtual one, running inside a [http://www.vmware.com/products/server/ VMware Server] or [http://www.vmware.com/products/vi/esx/ VMware ESX host], or the like, then you might want to start out with more modest partitions. The same holds for small servers that must run off Flash drives. Anyways, we're now at the Debian installation screen that lets us partition our disks. We're ''not'' going to use any of the "guided" partitioning options, we go for "manual". Choosing that brings us to a screen showing all drives that the installation routine has detected, and all partitions on those drives that the installer can "see". We're going to do some assuming here once more: let's assume the drive(s) on which you want to install are visible, and are empty (containing no other partitions). <references/> ===Software RAID partitioning=== If you're to use software RAID, you now have to select the free space on the first drive, press &lt;enter&gt;, and then tell what you want to do with the free space: create a new partition, tell which size you want it to be (see table above), give the type of partition (primary), and give where on the disk it'll sit (the beginning). Next, a screen comes up that details how the partition you're requesting will be created. Here we make some changes: under "use as" we're going to select "physical volume for RAID". This clears all the other options in this screen, except for the "bootable" flag, which must be "on" for the first partition that we'll mount as ''/boot''. Now select "Done setting up the partition". Next, go to the free space on the second disk, and do ''exactly'' the same, to create an identical physical volume for RAID - if it's the first partition, select the "bootable" flag as well (we'll want to be able to boot from this second disk if the first disk fails, right?). Then go back to the rest of the free space on the first disk, make the second physical volume for RAID, duplicate it on the second disk. Then, go back to the rest of the free space on the first disk, make the third physical volume for RAID, and again duplicate it on the second disk. If you now go back to the "partition disks" overview, you'll see all the partitions you've specified listed on their respective disks. But at the top an extra option has appeared, called "configure software RAID". When you now select this option, the installer will ask if it may write the changes you've made to disk. This actually creates the partition tables on the disks. Now you can create RAID devices. The RAID levels that Debian 6.0 offer are 0 (striping), 1 (mirroring), 5 (distributed redundancy), 6 (double distributed redundancy) ant 10 (striped mirrors). For your operating system disk pair, level 1 is the only sane choice. When selecting RAID 1, the installer asks how many active devices to use (2), how many spares (0), and then offers a selection screen where you can mark all members of the array. Select the first partition of both disks (presumably ''/dev/sda1'' and ''/dev/sdb1'') which should correspond to the 100MiB partitions you've created. Then create the other MD devices. Finally, choose &lt;finish&gt;. You'll drop back to the partitioner, but now the three created devices are available in the partitioner as "RAID1 device #0" etc. ===Hardware RAID partitioning=== Now, if you have hardware RAID, then on your first (boot) disk just make 3 partitions, in the following manner: Select the free space on the intended boot disk, press &lt;enter&gt;, select "create a new partition", and fill out the desired size (100MB). Type is primary, location is beginning of the disk, and in the details of the partition, we only need to change the Mount point to "/boot", and set the Bootable flag to "On". Then we're "Done setting up this partition". The second partition is made the same way, but the desired size is 3GB, the Mount point is "/", and the Bootable flag remains off. Again, we're "Done setting up this partition". The third partition is again a primary partition, it takes up the entire rest of the disk, but the type is not ext3, but "physical volume for LVM". Again, we're "Done setting up this partition". But now from the main partitioner screen, we can access "Configure the Logical Volume Manager". The installer asks if it can write out the choices made to the disk, and then enters the LVM setup screen, which begins with a summary explaining that you have one Free Physical Volume, and nothing more. ==Logical Volume creation== We now create a Volume Group (VG), which (in accordance to our partitioning standard) we'll call "system". In this VG, we'll add all Physical Volumes (being the one partition we've designated so in the previous step) using the space bar. To this end, in the volume group creation dialogue, we select that partition (''/dev/md2''). Note that all other selection choices are either unusable (unusable free space) or assigned to other purposes (/boot and /). Now we repeat the following process seven times: * select "Create Logical Volume" * select Volume Group "System" * give the LV Name (from the table, e.g. swap, var etc) * give the LV size (from the table, e.g. 1GB for swap etc) After this, we can select "Finish", the partitioner creates the seven LVs, and we're back at the partitioner screen, where there are now 7 extra "disks", with names such as ''LVM VG system, LV appslog - 3.0GB Linux device mapper (linear)''. Each of these "disks" has one block of empty space, which we now assign: seven times we repeat the following process: * select the unassigned chunk of empty space of an LV (e.g. ''appslog'') and press &lt;enter&gt;; * Change "Use as: do not use" into the desired filesystem (ext3 - only the LV "swap" gets as filesystem type "swap area"); * Change the mount point from "none" to the one corresponding with the name of the LV (note: the swap LV has no mountpoint; the appslog mountpoint must be entered manually as "/var/appslog" and varlog as "/var/log"); * If so desired, a label can be assigned to the partition (we usually don't); * select "Done setting up the partition". Note that sometimes, after creating and assigning the logical volumes, the installer has forgotten to mount the md0 and md1 partitions as /boot and /. In that case you'll have to reassign these partitions to these points in the filesystem. Once all this is done, we can look over the configuration once more, and then select "Finish partitioning and write changes to disk". A summary configuration screen will show, and we'll affirm with "yes" that these partitions can indeed be formatted. After some formatting screens flashing by (unless your partitions are particularly big, your system is particularly slow, or something goes wrong) the installation procedure continues. ==Base system setup== Now the Debian installer loads a base system. It will scan your installation CD/DVD, and ask if it should scan more CD/DVDs. We're going with "no" here. Then it will ask you how it can contact the Debian archives, in the dialogue "configure the package manager". For the NetInstall version of Debian, this is as good as mandatory. So here, we say "yes, use a Network Mirror", and in the following list select the country in which we are (in our case: the Netherlands), so the installer can present us with a number of network mirrors "close by". We select ftp.nl.debian.org. Next screen: should you be behind a proxy server, then it's possible to specify that here. And then the test: the system will say "scanning the mirror..." and try to contact the specified mirror. If it does not succeed, then there is either a network problem, a problem with this box's network card, or you've not specified the mirror or proxy correctly - so fix it. You'll know the network mirror has successfully been contacted when it's saying "Retrieving file 1 of 5". A number of files are retrieved, and the base system is set up. Somewhere early in this setup, the next dialogue appears - currently "configuring popularity-contest". Answer this question as you please. And then one of the last "big" questions: Software Selection. In this dialogue, you can easily select bundles of software to be installed. The choices are currently: * Graphical desktop environment * Web server * Print server * DNS server * File server * Mail server * SQL database * SSH server * Laptop * Standard system utilities (selected by default) We have to make a little confession here: we've never before used this option in the installer. In fact, we even deselect the Standard System, so as to minimize the number of software packages that the base installation of our server contains. This makes it more work to manually add packages later, but we feel it gives us more control and understanding of our systems. So if you're like us: deselect the "Standard system utilities" entry, and select Continue. The next dialogue handles the installation of the [http://www.gnu.org/software/grub/ ''grub'' bootloader]. Unless your disks weren't empty and you're attempting to make this system multiboot, you'll most likely get a question if you'll allow the installer to install ''grub'' into the boot sector of the first hard disk. We'll confirm with "Yes". After the installation of grub is completed, the CD-ROM is ejected, and the system is ready to reboot into Debian Squeeze. Remove the CD and select "Continue" ==Finishing up the installation== The system should reboot into Debian. This means you should see the following boot sequence: * your machine's standard POST messages * briefly a '''welcome to GRUB''' message * then, a blue grub menu on a black screen, with two entries: ** Debian GNU/Linux, with Linux 2.6.32-5-686 ** Debian GNU/Linux, with Linux 2.6.32-5-686 (recovery mode) * then, after a default (short!) time-out, the first grub option will go into effect, and the Linux kernel is started. Lots of cryptic messages in grey-on-black will scroll by, until the last few lines read: Debian GNU/Linux 6.0 easton2 tty1 easton2 login: '''_''' If your system does not reach this login, and/or some horrible error messages appear anywhere in this boot sequence, then you've got some extra work ahead. For now we'll assume you've reached the login prompt without problem. Log in as the principal user (try to avoid logging in as root! That's BAD practice!). Once logged in, save a copy of the boot messages using ''sudo dmesg > boot.txt'' or whatever you like. Then look through the boot messages, e.g. with ''vi -R boot.txt''. Furthermore, [[APT_and_aptitude | use Aptitude]] to make sure ''all'' your software is updated to the latest version. Done! Your base system is ready. You probably now want to [[essential system software | install essential software]], [[roll your own kernel]] and [[connect your server to the Internet]]. Furthermore, you might want to create a couple of [[aliases in every profile]] so that your favourite commands are always available. 4dca8692189c4539c28985ec2e797100fec5de86 2714 2713 2012-03-12T14:44:06Z Saruman! 2 update wikitext text/x-wiki <big>'''Debian Wheezy Base Server setup'''</big> ==Getting the hardware== {| class="wikitable" border="1" |- |Note: in the following we're assuming you'll be assembling an x86 or x64 type of machine, as it has about the best price/performance ratio you could wish. Hardware costs for other platforms, e.g. IBM's Series p or HP 9000, can be much higher, while platforms like ARM are energy efficient, but just not very powerful. Also, the availability of components and of help can be less than with the ubiquitous x86/x64 platforms. |} Naturally, before we can begin to install the operating system, we need to obtain the necessary hardware. Which hardware you require depends on what you want the server for; a test server on which you will test only a single feature for a short while does not need the same quality of hardware as does a server that's supposed to act as a home server for many tasks for a long time. We'll assume your server will be like ours: a home server that must perform many tasks with sufficient performance for a few users, that's reliable and will last for a couple of years. So build or obtain a server with at least the following hardware: * a spacious casing with big, quiet cooling fans, like the [http://www.coolermaster.com/products/product.php?act=detail&id=317 one we have]; * an efficient, heavy-duty power supply that's rated high enough for your devices, and has a decent efficiency. For example, a [http://www.corsair.com/products/power_supplies.aspx Corsair HX520] power supply; * a server class motherboard, e.g. an [http://www.intel.com/content/www/us/en/motherboards/server-motherboards/server-board.html Intel] or [http://uk.asus.com/Server_Workstation/Server_Motherboards/AMD_Dual_Processor AMD] based motherboard. DO NOT go for the cheapest motherboard you can find: if you pay peanuts, that's what you'll get. Server class motherboards have the quality, stability and durability you'll need from it, and usually also most of the needed peripherals, like multiple ethernet network cards on-board. Usually a Linux server does not require much in the way of video performance (and the screen will be used rarely, if ever), so any old integrated graphics will do. * a matching CPU - or multiple, if you think you need the power and the selected motherboard has the sockets. Furthermore, it pays to think about the energy use of your server CPU. For instance, you could choose an AMD Athlon X2 5600+, running at 2,8 Ghz and 89W maximum, but you can also go for an AMD Athlon X2 4850E, which is dualcore at 2,5GHz, but uses only 45W maximum - almost half of the former! And over a one year period, this choice can save up to 385 kWH. With electricity costing close to €0,25 per kWH (at least for some of us), that could save you €96,- a year (assuming your CPU is running at top speed all the time - which it won't). All I'm saying is: think about power use. * a CD-ROM- or DVD-player - although you might not need it any more after installation. Thus, you may opt to use an external USB DVD-player, if your system allows for booting from it. * ''multiple'' hard disks - you'll want redundancy, because every hard disk fails at some time. The drive with your data on it will fail fatally when it is most inconvenient to you, and any data on it that you consider valuable will likely be lost forever. To make Murphy's work somewhat harder for him, we're going to store our data redundantly, so that if any drive in the server fails, we'll not lose our data or our server. Thus, get yourself at least two hard disks for your operating system, at least 40GiB in size (don't think you'll be able to buy smaller ones nowadays), and spanking new (NEVER use old hard disks for your production server, new ones are just too cheap to run that risk!). You may also consider using 2.5" "notebook" hard disks, since they also consume less power than do 3.5" hard disks. However, you should investigate before buying SSDs for your Linux server, as there are some caveats there. We're not going into that subject here. * (multipe) network card(s) (NICs) if your motherboard does not have enough NICs integrated on-board. You'll want a NIC for your network, and another one for your Internet connection; and possible a third one for the wireless segment of your network. Now build a machine out of the above, or have someone build it for you. ==Preparation of the hardware== (Note: in the following we're again assuming you're running an x86/x64 type of machine. Hardware requirements and preparation for other platforms, e.g. IBM's Series p or HP 9000, can differ significantly) Next, check the assembled hardware: * is the configuration complete? If it does not have a CD/DVDplayer from which it can boot, then installing the software gets more difficult - at least get an USB external DVDdrive or something like that. * are all components connected properly (memory modules seated correctly in their sockets, AGP card inserted correctly into the AGP slot, et cetera) and are all cable connections made (multiple power cables to the motherboard, one power cable plus one data cable to each hard disk, etcetera)? Following this, you may hook up the machine. It's going to need power, and you will need at least a keyboard and a monitor attached. And if you want to use a Graphic User Interface to install, a mouse is required also. When you've ensured that everything is safe, you can turn on the machine, and continue to check it: * do all fans start to run when you turn on the machine? (if not, then '''quickly''' turn off your machine and correct the problem!) * does/do the hard disk(s) spin up? * do the power button and reset button operate correctly? * are the power led, HDD led and other display gadgetry functional? * when you let the machine power up, does it emit a single beep? And does it then show a Power-On Self Test screen (POST)? * Does it show the correct amount of memory in the POST screen? The correct number & speed of the CPU(s)? * Does the machine recognise all controller cards (SCSI, S-ATA etc)? And all attached DVD-drives and hard disks? * are all BIOSes/firmwares up to date? * If you have a hardware RAID controller, are your RAID arrays built already? * does the machine attempt to boot from at least the hard disk? ...et cetera. If there is any problem, or you want to update the BIOS or firmwares, it's best to do it before the operating system is installed. This Wiki, however, is not the place to get the information on how to accomplish these type of tasks. The last steps in the preparation of the hardware, are * to ensure that the machine can boot from CD/DVD, so that you can start installing Debian from it. It is possible to install Debian over the network, but that requires setting up a [http://www.debian-administration.org/articles/478 PXE Boot server] which is (currently) outside the scope of this wiki. * to connect the hardware to the Internet, so that it can get all required updates etcetera; please do ''not'' connect the box ''straight'' to the Internet, but make sure that it's safely behind a firewall, or failing that, a NAT router. By now the system should be almost ready to receive it's Operating System. But first we have an issue to tackle: that of redundancy. ==Software or hardware RAID== Your hard disks will fail. They absolutely will. It is never a question of "if", only of "when". So what will you do when the hard disk containing your complete operating system fails (besides pulling your hair out, that is)? What we propose is this: hard disks are pretty cheap nowadays, so let's use [http://en.wikipedia.org/wiki/Redundant_array_of_independent_disks RAID technology] to make our hard drive space resilient against failure of a whole drive. So first make sure that you have ''two'' disks of equal size instead of only one. Had you already been planning to use multiple disks already, then make sure you have at least ''one'' disk more than your space requirements prescribe; the space on that extra drive will provide the needed redundancy. Next, [[RAID fundamentals under Linux | click here]] to learn a bit more about RAID, to make the decision to use hardware-based and/or software-based RAID, and to plan your RAID arrays. In this example, we'll assume you're using hardware RAID on a RAID controller that's supported by the Debian installation software. This means that the installation software will "see" your RAID array(s) and present them as usable drives. ==Planning your network names== If your machine must become a part of an existing network, then it's almost certain that you already have a DNS domain in place; in that case: obtain the DNS suffix your machine will get (the DNS domain your machine will "belong" to). However, it's also possible that this machine is going to be the first machine in your new network, in which case the whole issue of DNS suffixes is wide open. If you need more information on DNS, go [[http://www.isc.org/sw/bind/arm95/Bv9ARM-all.html#id2564824 here]]. For now we'll assume you have (or will quickly obtain) a working knowledge of the DNS system. Here is our tip on choosing a DNS domain for your home network: * do '''not''' use a publicly registered domain name (e.g. "cocacola.com") for any machine that's not primarily intended to serve the public on the Internet; * for machines serving a private network, we urge you to use Top Level Domain name "lan" (to signify your machine is on a Local Area Network or LAN) * for the Domain Name itself, we suggest you use a level 2 name, like "saruman.lan", and not a level 3 name, like "mister.saruman.lan". This is only a short section on DNS, but remember that once a proper DNS system is in place, it takes some work to change it. At any rate, this section has most likely showed you that you need to put some thought into the DNS Domain Name design of your home network. OK, with this out of the way, we can get to installing the OS. ==Operating System installation== To install an Operating System (OS), it's kinda instrumental that you have one. Here, we're going to use [http://www.debian.org/intro/about Debian], the biggest [http://www.debian.org/intro/about#free Free] OS that we know of. Free stands for Freedom, but incidentally that Freedom also means it's gratis, an appealing aspect of Free. To get your own copy of Debian, go to their [http://www.debian.org/distrib/ download site] and obtain a [http://www.debian.org/releases/ release] image - you can opt for the current stable version, but unless Debian has released a new stable version fairly recently, it's also possible to use the current testing version. In this example we're going to use the Testing version, Debian 7.0, or "Wheezy" as it's also known. (some pages of this wiki were written in the time of Debian 6.0 Squeeze or 5.0 Lenny, and haven't been updated yet). Besides the choice which release of Debian you want to run, you also have to know for which platform you're downloading (in our case: either ''amd64'' or ''i386'' depending on your hardware platform) and what kind of install you wish - if you have a working, fast Internet connection available at the time of install, then we recommend getting the [[http://www.debian.org/CD/netinst/ netinst] CD image; it's a relatively small CD, that'll be able to get you going, but gets most of the software you'll need straight from the 'net at install time. In the example at hand we're installing on an AMD Athlon x2-based server, on which we wish to install 64-bits software. We'll download [http://cdimage.debian.org/cdimage/weekly-builds/amd64/iso-cd/debian-testing-amd64-CD-1.iso debian-testing-amd64-CD-1.iso], which is a pre-release candidate of Wheezy. Burn this to a CD-recordable and boot your prepared hardware platform from this CD. After booting from the CD, a friendly graphic screen shows you the Installer boot menu. Your choices are * Install, the default non-graphical installation; * Graphical install, so you can click things; * Advanced options, where you can select expert options like the rescue mode; * Help; this drops you to a non-graphical screen where you can select help texts by using function keys. The screens explain how you can start the installation with extra parameters to instruct Debian to handle your hardware in a non-standard way, e.g. on an old machine with a problematic videocard you could run "install vga=771" (for some laptops) or "install vga=normal fb=false" (to disable the screen framebuffer); * Install with speech synthesis (sorry, no experience with this yet). We're going to use the standard Command Line installation, so we choose "Install" and hit &lt;enter&gt;. {| class="wikitable" border="1" |- |We could simply use "Graphic install", in which case we'd have a nice fresh Graphical User Interface for our installation. ''We're'' not going to, because we're real men, and [http://isg.ee.ethz.ch/tools/realmen/ Real Men Don't Click]. Also, we've found that from the GUI it's hard to switch to a second console and then back. We could also go to the Advanced options, and opt for "Expert install" or "Graphical expert install" as installation method, because it gives a much finer grain of control; however we usually don't need that control, and can do without the barrage of extra questions that the "expert" installation method pose. |} After the Linux kernel finishes initializing the machine, a simple text-based installer appears that immediately starts asking questions. Answer them according to your needs. Our example system uses the following choices: * Language: English * country: other &gt; Europe &gt; Netherlands * locale (since there's no default locale for the combination Netherlands/English): United States - en_US.UTF-8 * keymap: American English (since we have a keyboard with US layout) Some installation software loads, and we get to the next phase: if you have multiple NICs in your machine (which we believe you ''should'' have!!), and if they're detected properly, then you're required to indicate which of the detected network interface cards (NIC) is going to be the "primary" NIC. {| class="wikitable" border="1" |- |Here, trouble could begin. If your machine has only network cards that are '''not''' supported, then you'll see '''no''' cards here - but then how are you going to do a NetInstall? A solution would be to (temporarily) install a NIC that ''is'' supported, like a cheap Realtek card, or an old 3Com 905 card. Then, when the whole system is installed, up and running, you could compile a new kernel that contains support for your actual NICs, and when these work, remove the temporary NIC. For now, we'll assume that at least one of your NICs is recognised properly by the Debian installation routine. |} Select the card that's connected and has (indirect) access to Internet (again: it should ''not'' be connected straight to the wild wild web, but sit safely behind a firewall, at least until we've installed our own firewall); if at all possible, let it be the NIC that'll be connected to your home network itself, on the ''inside'' of your server. Let's assume that this NIC is designated ''eth0'' by the Debian installation. This card will now be configured using DHCP, so if you're on a network with a DHCP-server, the network will work straight away. If it's not, you can either configure the network manually or fix your DHCP-server and connection between it and ''eth0''. Next is one of the hardest questions that any OS installation is going to ask you: what will be the host name of the system? You could easily change it at any time in the future, but possibly with lots of hassle, so you better choose wisely. Here are our tips: * do '''not''' name your machine after the user that's going to use it, e.g. "bernie-pc" (at some time in the future, Bernie's machine will be moved to Alice, so then Alice is working on "bernie-pc" which makes the situation quite unclear); * do '''not''' name your machine after the department or workgroup that's using it most, e.g. "accounting-srv" (same reasoning); * do '''not''' name your machine after it's main function, e.g. "printserver" (at some time in the future, the main function is moved to another machine, and/or an alternative function will become the main function of the machine); * do '''not''' name your machine after it's location, e.g. "srv-boston" (at some time in the future, the box will be moved to another location); * do '''not''' name your machine after it's hardware configuration, e.g. "ibmx346" (at some time in the future, either another xSeries x346 will be wheeled in, or the machine will be upgraded to accomodate increased use or overcome hardware problems - your "ibmx346" could suddenly be running on an xSeries x3650). What we feel are safe names for ''any'' machine in your network are true names, perhaps linked to a common theme: names of European cities, names of movie characters, names of countries or holiday destinations et cetera. Less imaginative would be coded names like "server0001". Immediately following comes the question of the Domain Name. This is about a DNS domain, so effectively the installation program is asking which DNS suffix the host name should have; if the DHCP-server already provided something it'll be suggested, but you can override it if need be. In the preparatory phase, you'll have decided on continuation of your current DNS schema, or starting a new one. Either way, put the chosen DNS suffix in and press &lt;enter&gt;. Next comes one '''VERY''' important question: what to use as root password? We cannot stress this enough: choose a SAFE password! Do NOT go for an easy-to-remember one, go for STRONG and SAFE. There are tools to help you generate strong passwords, like [http://www.pctools.com/guides/password/ this page]: use them! We strongly suggest 10 characters or more, including letters, mixed case, and numbers, so something like ''SuCRe4hecH'' (do NOT use this, generate your own!). Next, give the full name of the principal user of this server (your own, we assume), give the login-name (your given name, we assume), and a corresponding password. Again, use a SAFE password. As long as you don't make your principal user equivalent to root, you might go for a slightly weaker password (8 characters instead of 10), but we rather suggest you make the password just as strong (and different from!) the root password. After entering the details of these two users "root" and "you", we get to the server hardware. ==Partitioning== Now comes the question of partitioning, or how to divide the available disk space into chunks for the server to use. This is a tricky subject, because if you put all storage space into one partition, then some day a runaway process will fill up the entire disk with useless logs, and the system will crash. On the other hand, if you divvy up all space into little chunks, then some application is going to need space in one of those partitions where there is none, even though there may be plenty in other partitions. To minimize the chance of either problem occurring, we're going to use [http://tldp.org/HOWTO/LVM-HOWTO/whatisvolman.html Logical Volume Management (LVM2)] so that we can provision enough space to start our server, but keep some space in reserve to apply when needed, where it'll be needed. So, we at Saruman.biz have put together a recommended standard partitioning scheme. The basis (in accordance with the standard [[Debian directory structure]] is this: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Partition !style="background:#ffdead;"|MD !style="background:#ffdead;"|LVG !style="background:#ffdead;"|LV-name !style="background:#ffdead;"|Size <br> (physical machine) !style="background:#ffdead;"|Size (VM) !style="background:#ffdead;"|File System !style="background:#ffdead;"|Mount point |- | 1 | /dev/md0 | &nbsp; | &nbsp; | 100MiB | 100MiB | ext3 | /boot |- | 2 | /dev/md1 | &nbsp; | &nbsp; | 3GiB | 1GiB | ext3 | / |- | rowspan="8" valign="top" | 3 | rowspan="8" valign="top" | /dev/md2 | rowspan="8" valign="top" style="background:lightgrey"| system | style="background:lightgrey" | swap | 1GiB<ref name="swap">Rule of thumb: twice the size of the machine's RAM, but no less than 256MiB and no more than 2GiB</ref> | 256MiB<ref name="swap"/> | swap | &nbsp; |- | style="background:lightgrey" | var | 1GiB | 512MiB | ext3 | /var |- | style="background:lightgrey" | varlog | 1GiB | 512MiB | ext3 | /var/log |- | style="background:lightgrey" | appslog | 3GiB | -<ref>Yes, we think a separate ''appslog'' is a very good idea, but when creating a minimal VM, we have to save disk space ''somewhere''...</ref> | ext3 | /var/appslog |- | style="background:lightgrey" | home | 1GiB<ref name="home">Note that this heavily depends on the purpose of the machine; if it is not to house any users, then (almost) no space is needed for /home. But on the other hand if e.g. a virtual user is to be used for keeping mailstores, or other service users need home space, then /home needs to be big enough for that.</ref> | 512MiB<ref name="home"/> | ext3 | /home |- | style="background:lightgrey" | usr | 3GiB | 3GiB | ext3 | /usr |- | style="background:lightgrey" | tmp | 1GiB | 512MiB | ext3 | /tmp |- | style="background:lightgrey" | opt | 1GiB | - | ext3 | /opt |- ! colspan="4" style="text-align:right"| Total ! 18.1GiB ! 6.9GiB ! colspan="2" | |- |} As you can see, the partition table works as follows: we assume that we wind up with 3 partitions, either on three separate software RAID arrays (''md0'' through ''md2'') or on one single hardware RAID array (in which case the 2nd column ''MD'' does not apply). The size of the partitions depends on your machine's make: for standard physical machines the 5th column does sensible suggestions, even though you could choose to have different sizes and of course different divisions altogether. If your machine happens to be a virtual one, running inside a [http://www.vmware.com/products/server/ VMware Server] or [http://www.vmware.com/products/vi/esx/ VMware ESX host], or the like, then you might want to start out with more modest partitions. The same holds for small servers that must run off Flash drives. Anyways, we're now at the Debian installation screen that lets us partition our disks. We're ''not'' going to use any of the "guided" partitioning options, we go for "manual". Choosing that brings us to a screen showing all drives that the installation routine has detected, and all partitions on those drives that the installer can "see". We're going to do some assuming here once more: let's assume the drive(s) on which you want to install are visible, and are empty (containing no other partitions). <references/> ===Software RAID partitioning=== If you're to use software RAID, you now have to select the free space on the first drive, press &lt;enter&gt;, and then tell what you want to do with the free space: create a new partition, tell which size you want it to be (see table above), give the type of partition (primary), and give where on the disk it'll sit (the beginning). Next, a screen comes up that details how the partition you're requesting will be created. Here we make some changes: under "use as" we're going to select "physical volume for RAID". This clears all the other options in this screen, except for the "bootable" flag, which must be "on" for the first partition that we'll mount as ''/boot''. Now select "Done setting up the partition". Next, go to the free space on the second disk, and do ''exactly'' the same, to create an identical physical volume for RAID - if it's the first partition, select the "bootable" flag as well (we'll want to be able to boot from this second disk if the first disk fails, right?). Then go back to the rest of the free space on the first disk, make the second physical volume for RAID, duplicate it on the second disk. Then, go back to the rest of the free space on the first disk, make the third physical volume for RAID, and again duplicate it on the second disk. If you now go back to the "partition disks" overview, you'll see all the partitions you've specified listed on their respective disks. But at the top an extra option has appeared, called "configure software RAID". When you now select this option, the installer will ask if it may write the changes you've made to disk. This actually creates the partition tables on the disks. Now you can create RAID devices. The RAID levels that Debian 6.0 offer are 0 (striping), 1 (mirroring), 5 (distributed redundancy), 6 (double distributed redundancy) ant 10 (striped mirrors). For your operating system disk pair, level 1 is the only sane choice. When selecting RAID 1, the installer asks how many active devices to use (2), how many spares (0), and then offers a selection screen where you can mark all members of the array. Select the first partition of both disks (presumably ''/dev/sda1'' and ''/dev/sdb1'') which should correspond to the 100MiB partitions you've created. Then create the other MD devices. Finally, choose &lt;finish&gt;. You'll drop back to the partitioner, but now the three created devices are available in the partitioner as "RAID1 device #0" etc. ===Hardware RAID partitioning=== Now, if you have hardware RAID, then on your first (boot) disk just make 3 partitions, in the following manner: Select the free space on the intended boot disk, press &lt;enter&gt;, select "create a new partition", and fill out the desired size (100MB). Type is primary, location is beginning of the disk, and in the details of the partition, we only need to change the Mount point to "/boot", and set the Bootable flag to "On". Then we're "Done setting up this partition". The second partition is made the same way, but the desired size is 3GB, the Mount point is "/", and the Bootable flag remains off. Again, we're "Done setting up this partition". The third partition is again a primary partition, it takes up the entire rest of the disk, but the type is not ext3, but "physical volume for LVM". Again, we're "Done setting up this partition". But now from the main partitioner screen, we can access "Configure the Logical Volume Manager". The installer asks if it can write out the choices made to the disk, and then enters the LVM setup screen, which begins with a summary explaining that you have one Free Physical Volume, and nothing more. ==Logical Volume creation== We now create a Volume Group (VG), which (in accordance to our partitioning standard) we'll call "system". In this VG, we'll add all Physical Volumes (being the one partition we've designated so in the previous step) using the space bar. To this end, in the volume group creation dialogue, we select that partition (''/dev/md2''). Note that all other selection choices are either unusable (unusable free space) or assigned to other purposes (/boot and /). Now we repeat the following process seven times: * select "Create Logical Volume" * select Volume Group "System" * give the LV Name (from the table, e.g. swap, var etc) * give the LV size (from the table, e.g. 1GB for swap etc) After this, we can select "Finish", the partitioner creates the seven LVs, and we're back at the partitioner screen, where there are now 7 extra "disks", with names such as ''LVM VG system, LV appslog - 3.0GB Linux device mapper (linear)''. Each of these "disks" has one block of empty space, which we now assign: seven times we repeat the following process: * select the unassigned chunk of empty space of an LV (e.g. ''appslog'') and press &lt;enter&gt;; * Change "Use as: do not use" into the desired filesystem (ext3 - only the LV "swap" gets as filesystem type "swap area"); * Change the mount point from "none" to the one corresponding with the name of the LV (note: the swap LV has no mountpoint; the appslog mountpoint must be entered manually as "/var/appslog" and varlog as "/var/log"); * If so desired, a label can be assigned to the partition (we usually don't); * select "Done setting up the partition". Note that sometimes, after creating and assigning the logical volumes, the installer has forgotten to mount the md0 and md1 partitions as /boot and /. In that case you'll have to reassign these partitions to these points in the filesystem. Once all this is done, we can look over the configuration once more, and then select "Finish partitioning and write changes to disk". A summary configuration screen will show, and we'll affirm with "yes" that these partitions can indeed be formatted. After some formatting screens flashing by (unless your partitions are particularly big, your system is particularly slow, or something goes wrong) the installation procedure continues. ==Base system setup== Now the Debian installer loads a base system. It will scan your installation CD/DVD, and ask if it should scan more CD/DVDs. We're going with "no" here. Then it will ask you how it can contact the Debian archives, in the dialogue "configure the package manager". For the NetInstall version of Debian, this is as good as mandatory. So here, we say "yes, use a Network Mirror", and in the following list select the country in which we are (in our case: the Netherlands), so the installer can present us with a number of network mirrors "close by". We select ftp.nl.debian.org. Next screen: should you be behind a proxy server, then it's possible to specify that here. And then the test: the system will say "scanning the mirror..." and try to contact the specified mirror. If it does not succeed, then there is either a network problem, a problem with this box's network card, or you've not specified the mirror or proxy correctly - so fix it. You'll know the network mirror has successfully been contacted when it's saying "Retrieving file 1 of 5". A number of files are retrieved, and the base system is set up. Somewhere early in this setup, the next dialogue appears - currently "configuring popularity-contest". Answer this question as you please. And then one of the last "big" questions: Software Selection. In this dialogue, you can easily select bundles of software to be installed. The choices are currently: * Graphical desktop environment * Web server * Print server * DNS server * File server * Mail server * SQL database * SSH server * Laptop * Standard system utilities (selected by default) We have to make a little confession here: we've never before used this option in the installer. In fact, we even deselect the Standard System, so as to minimize the number of software packages that the base installation of our server contains. This makes it more work to manually add packages later, but we feel it gives us more control and understanding of our systems. So if you're like us: deselect the "Standard system utilities" entry, and select Continue. The next dialogue handles the installation of the [http://www.gnu.org/software/grub/ ''grub'' bootloader]. Unless your disks weren't empty and you're attempting to make this system multiboot, you'll most likely get a question if you'll allow the installer to install ''grub'' into the boot sector of the first hard disk. We'll confirm with "Yes". After the installation of grub is completed, the CD-ROM is ejected, and the system is ready to reboot into Debian Squeeze. Remove the CD and select "Continue" ==Finishing up the installation== The system should reboot into Debian. This means you should see the following boot sequence: * your machine's standard POST messages * briefly a '''welcome to GRUB''' message * then, a blue grub menu on a black screen, with two entries: ** Debian GNU/Linux, with Linux 2.6.32-5-686 ** Debian GNU/Linux, with Linux 2.6.32-5-686 (recovery mode) * then, after a default (short!) time-out, the first grub option will go into effect, and the Linux kernel is started. Lots of cryptic messages in grey-on-black will scroll by, until the last few lines read: Debian GNU/Linux 6.0 easton2 tty1 easton2 login: '''_''' If your system does not reach this login, and/or some horrible error messages appear anywhere in this boot sequence, then you've got some extra work ahead. For now we'll assume you've reached the login prompt without problem. Log in as the principal user (try to avoid logging in as root! That's BAD practice!). Once logged in, save a copy of the boot messages using ''sudo dmesg > boot.txt'' or whatever you like. Then look through the boot messages, e.g. with ''vi -R boot.txt''. Furthermore, [[APT_and_aptitude | use Aptitude]] to make sure ''all'' your software is updated to the latest version. Done! Your base system is ready. You probably now want to [[essential system software | install essential software]], [[roll your own kernel]] and [[connect your server to the Internet]]. Furthermore, you might want to create a couple of [[aliases in every profile]] so that your favourite commands are always available. 08031c003fae3adf0a9c6b642a5b6bed4a9e5830 2715 2714 2012-03-12T14:46:03Z Saruman! 2 /* Operating System installation */ typos wikitext text/x-wiki <big>'''Debian Wheezy Base Server setup'''</big> ==Getting the hardware== {| class="wikitable" border="1" |- |Note: in the following we're assuming you'll be assembling an x86 or x64 type of machine, as it has about the best price/performance ratio you could wish. Hardware costs for other platforms, e.g. IBM's Series p or HP 9000, can be much higher, while platforms like ARM are energy efficient, but just not very powerful. Also, the availability of components and of help can be less than with the ubiquitous x86/x64 platforms. |} Naturally, before we can begin to install the operating system, we need to obtain the necessary hardware. Which hardware you require depends on what you want the server for; a test server on which you will test only a single feature for a short while does not need the same quality of hardware as does a server that's supposed to act as a home server for many tasks for a long time. We'll assume your server will be like ours: a home server that must perform many tasks with sufficient performance for a few users, that's reliable and will last for a couple of years. So build or obtain a server with at least the following hardware: * a spacious casing with big, quiet cooling fans, like the [http://www.coolermaster.com/products/product.php?act=detail&id=317 one we have]; * an efficient, heavy-duty power supply that's rated high enough for your devices, and has a decent efficiency. For example, a [http://www.corsair.com/products/power_supplies.aspx Corsair HX520] power supply; * a server class motherboard, e.g. an [http://www.intel.com/content/www/us/en/motherboards/server-motherboards/server-board.html Intel] or [http://uk.asus.com/Server_Workstation/Server_Motherboards/AMD_Dual_Processor AMD] based motherboard. DO NOT go for the cheapest motherboard you can find: if you pay peanuts, that's what you'll get. Server class motherboards have the quality, stability and durability you'll need from it, and usually also most of the needed peripherals, like multiple ethernet network cards on-board. Usually a Linux server does not require much in the way of video performance (and the screen will be used rarely, if ever), so any old integrated graphics will do. * a matching CPU - or multiple, if you think you need the power and the selected motherboard has the sockets. Furthermore, it pays to think about the energy use of your server CPU. For instance, you could choose an AMD Athlon X2 5600+, running at 2,8 Ghz and 89W maximum, but you can also go for an AMD Athlon X2 4850E, which is dualcore at 2,5GHz, but uses only 45W maximum - almost half of the former! And over a one year period, this choice can save up to 385 kWH. With electricity costing close to €0,25 per kWH (at least for some of us), that could save you €96,- a year (assuming your CPU is running at top speed all the time - which it won't). All I'm saying is: think about power use. * a CD-ROM- or DVD-player - although you might not need it any more after installation. Thus, you may opt to use an external USB DVD-player, if your system allows for booting from it. * ''multiple'' hard disks - you'll want redundancy, because every hard disk fails at some time. The drive with your data on it will fail fatally when it is most inconvenient to you, and any data on it that you consider valuable will likely be lost forever. To make Murphy's work somewhat harder for him, we're going to store our data redundantly, so that if any drive in the server fails, we'll not lose our data or our server. Thus, get yourself at least two hard disks for your operating system, at least 40GiB in size (don't think you'll be able to buy smaller ones nowadays), and spanking new (NEVER use old hard disks for your production server, new ones are just too cheap to run that risk!). You may also consider using 2.5" "notebook" hard disks, since they also consume less power than do 3.5" hard disks. However, you should investigate before buying SSDs for your Linux server, as there are some caveats there. We're not going into that subject here. * (multipe) network card(s) (NICs) if your motherboard does not have enough NICs integrated on-board. You'll want a NIC for your network, and another one for your Internet connection; and possible a third one for the wireless segment of your network. Now build a machine out of the above, or have someone build it for you. ==Preparation of the hardware== (Note: in the following we're again assuming you're running an x86/x64 type of machine. Hardware requirements and preparation for other platforms, e.g. IBM's Series p or HP 9000, can differ significantly) Next, check the assembled hardware: * is the configuration complete? If it does not have a CD/DVDplayer from which it can boot, then installing the software gets more difficult - at least get an USB external DVDdrive or something like that. * are all components connected properly (memory modules seated correctly in their sockets, AGP card inserted correctly into the AGP slot, et cetera) and are all cable connections made (multiple power cables to the motherboard, one power cable plus one data cable to each hard disk, etcetera)? Following this, you may hook up the machine. It's going to need power, and you will need at least a keyboard and a monitor attached. And if you want to use a Graphic User Interface to install, a mouse is required also. When you've ensured that everything is safe, you can turn on the machine, and continue to check it: * do all fans start to run when you turn on the machine? (if not, then '''quickly''' turn off your machine and correct the problem!) * does/do the hard disk(s) spin up? * do the power button and reset button operate correctly? * are the power led, HDD led and other display gadgetry functional? * when you let the machine power up, does it emit a single beep? And does it then show a Power-On Self Test screen (POST)? * Does it show the correct amount of memory in the POST screen? The correct number & speed of the CPU(s)? * Does the machine recognise all controller cards (SCSI, S-ATA etc)? And all attached DVD-drives and hard disks? * are all BIOSes/firmwares up to date? * If you have a hardware RAID controller, are your RAID arrays built already? * does the machine attempt to boot from at least the hard disk? ...et cetera. If there is any problem, or you want to update the BIOS or firmwares, it's best to do it before the operating system is installed. This Wiki, however, is not the place to get the information on how to accomplish these type of tasks. The last steps in the preparation of the hardware, are * to ensure that the machine can boot from CD/DVD, so that you can start installing Debian from it. It is possible to install Debian over the network, but that requires setting up a [http://www.debian-administration.org/articles/478 PXE Boot server] which is (currently) outside the scope of this wiki. * to connect the hardware to the Internet, so that it can get all required updates etcetera; please do ''not'' connect the box ''straight'' to the Internet, but make sure that it's safely behind a firewall, or failing that, a NAT router. By now the system should be almost ready to receive it's Operating System. But first we have an issue to tackle: that of redundancy. ==Software or hardware RAID== Your hard disks will fail. They absolutely will. It is never a question of "if", only of "when". So what will you do when the hard disk containing your complete operating system fails (besides pulling your hair out, that is)? What we propose is this: hard disks are pretty cheap nowadays, so let's use [http://en.wikipedia.org/wiki/Redundant_array_of_independent_disks RAID technology] to make our hard drive space resilient against failure of a whole drive. So first make sure that you have ''two'' disks of equal size instead of only one. Had you already been planning to use multiple disks already, then make sure you have at least ''one'' disk more than your space requirements prescribe; the space on that extra drive will provide the needed redundancy. Next, [[RAID fundamentals under Linux | click here]] to learn a bit more about RAID, to make the decision to use hardware-based and/or software-based RAID, and to plan your RAID arrays. In this example, we'll assume you're using hardware RAID on a RAID controller that's supported by the Debian installation software. This means that the installation software will "see" your RAID array(s) and present them as usable drives. ==Planning your network names== If your machine must become a part of an existing network, then it's almost certain that you already have a DNS domain in place; in that case: obtain the DNS suffix your machine will get (the DNS domain your machine will "belong" to). However, it's also possible that this machine is going to be the first machine in your new network, in which case the whole issue of DNS suffixes is wide open. If you need more information on DNS, go [[http://www.isc.org/sw/bind/arm95/Bv9ARM-all.html#id2564824 here]]. For now we'll assume you have (or will quickly obtain) a working knowledge of the DNS system. Here is our tip on choosing a DNS domain for your home network: * do '''not''' use a publicly registered domain name (e.g. "cocacola.com") for any machine that's not primarily intended to serve the public on the Internet; * for machines serving a private network, we urge you to use Top Level Domain name "lan" (to signify your machine is on a Local Area Network or LAN) * for the Domain Name itself, we suggest you use a level 2 name, like "saruman.lan", and not a level 3 name, like "mister.saruman.lan". This is only a short section on DNS, but remember that once a proper DNS system is in place, it takes some work to change it. At any rate, this section has most likely showed you that you need to put some thought into the DNS Domain Name design of your home network. OK, with this out of the way, we can get to installing the OS. ==Operating System installation== To install an Operating System (OS), it's kinda instrumental that you have one. Here, we're going to use [http://www.debian.org/intro/about Debian], the biggest [http://www.debian.org/intro/about#free Free] OS that we know of. Free stands for Freedom, but incidentally that Freedom also means it's gratis, an appealing aspect of Free. To get your own copy of Debian, go to their [http://www.debian.org/distrib/ download site] and obtain a [http://www.debian.org/releases/ release] image - you can opt for the current stable version, but unless Debian has released a new stable version fairly recently, it's also reasonably safe to use the current testing version. In this example we're going to use the Testing version, Debian 7.0, or "Wheezy" as it's also known. (some pages of this wiki were written in the time of Debian 6.0 Squeeze or 5.0 Lenny, and haven't been updated yet). Besides the choice which release of Debian you want to run, you also have to know for which platform you're downloading (in our case: either ''amd64'' or ''i386'' depending on your hardware platform) and what kind of install you wish - if you have a working, fast Internet connection available at the time of install, then we recommend getting the [http://www.debian.org/CD/netinst/ netinst] CD image; it's a relatively small CD, that'll be able to get you going, but gets most of the software you'll need straight from the 'net at install time. In the example at hand we're installing on an AMD Athlon x2-based server, on which we wish to install 64-bits software. We'll download [http://cdimage.debian.org/cdimage/weekly-builds/amd64/iso-cd/debian-testing-amd64-CD-1.iso debian-testing-amd64-CD-1.iso], which is a pre-release candidate of Wheezy. Burn this to a CD-recordable and boot your prepared hardware platform from this CD. After booting from the CD, a friendly graphic screen shows you the Installer boot menu. Your choices are * Install, the default non-graphical installation; * Graphical install, so you can click things; * Advanced options, where you can select expert options like the rescue mode; * Help; this drops you to a non-graphical screen where you can select help texts by using function keys. The screens explain how you can start the installation with extra parameters to instruct Debian to handle your hardware in a non-standard way, e.g. on an old machine with a problematic videocard you could run "install vga=771" (for some laptops) or "install vga=normal fb=false" (to disable the screen framebuffer); * Install with speech synthesis (sorry, no experience with this yet). We're going to use the standard Command Line installation, so we choose "Install" and hit &lt;enter&gt;. {| class="wikitable" border="1" |- |We could simply use "Graphic install", in which case we'd have a nice fresh Graphical User Interface for our installation. ''We're'' not going to, because we're real men, and [http://isg.ee.ethz.ch/tools/realmen/ Real Men Don't Click]. Also, we've found that from the GUI it's hard to switch to a second console and then back. We could also go to the Advanced options, and opt for "Expert install" or "Graphical expert install" as installation method, because it gives a much finer grain of control; however we usually don't need that control, and can do without the barrage of extra questions that the "expert" installation method pose. |} After the Linux kernel finishes initializing the machine, a simple text-based installer appears that immediately starts asking questions. Answer them according to your needs. Our example system uses the following choices: * Language: English * country: other &gt; Europe &gt; Netherlands * locale (since there's no default locale for the combination Netherlands/English): United States - en_US.UTF-8 * keymap: American English (since we have a keyboard with US layout) Some installation software loads, and we get to the next phase: if you have multiple NICs in your machine (which we believe you ''should'' have!!), and if they're detected properly, then you're required to indicate which of the detected network interface cards (NIC) is going to be the "primary" NIC. {| class="wikitable" border="1" |- |Here, trouble could begin. If your machine has only network cards that are '''not''' supported, then you'll see '''no''' cards here - but then how are you going to do a NetInstall? A solution would be to (temporarily) install a NIC that ''is'' supported, like a cheap Realtek card, or an old 3Com 905 card. Then, when the whole system is installed, up and running, you could compile a new kernel that contains support for your actual NICs, and when these work, remove the temporary NIC. For now, we'll assume that at least one of your NICs is recognised properly by the Debian installation routine. |} Select the card that's connected and has (indirect) access to Internet (again: it should ''not'' be connected straight to the wild wild web, but sit safely behind a firewall, at least until we've installed our own firewall); if at all possible, let it be the NIC that'll be connected to your home network itself, on the ''inside'' of your server. Let's assume that this NIC is designated ''eth0'' by the Debian installation. This card will now be configured using DHCP, so if you're on a network with a DHCP-server, the network will work straight away. If it's not, you can either configure the network manually or fix your DHCP-server and connection between it and ''eth0''. Next is one of the hardest questions that any OS installation is going to ask you: what will be the host name of the system? You could easily change it at any time in the future, but possibly with lots of hassle, so you better choose wisely. Here are our tips: * do '''not''' name your machine after the user that's going to use it, e.g. "bernie-pc" (at some time in the future, Bernie's machine will be moved to Alice, so then Alice is working on "bernie-pc" which makes the situation quite unclear); * do '''not''' name your machine after the department or workgroup that's using it most, e.g. "accounting-srv" (same reasoning); * do '''not''' name your machine after it's main function, e.g. "printserver" (at some time in the future, the main function is moved to another machine, and/or an alternative function will become the main function of the machine); * do '''not''' name your machine after it's location, e.g. "srv-boston" (at some time in the future, the box will be moved to another location); * do '''not''' name your machine after it's hardware configuration, e.g. "ibmx346" (at some time in the future, either another xSeries x346 will be wheeled in, or the machine will be upgraded to accomodate increased use or overcome hardware problems - your "ibmx346" could suddenly be running on an xSeries x3650). What we feel are safe names for ''any'' machine in your network are true names, perhaps linked to a common theme: names of European cities, names of movie characters, names of countries or holiday destinations et cetera. Less imaginative would be coded names like "server0001". Immediately following comes the question of the Domain Name. This is about a DNS domain, so effectively the installation program is asking which DNS suffix the host name should have; if the DHCP-server already provided something it'll be suggested, but you can override it if need be. In the preparatory phase, you'll have decided on continuation of your current DNS schema, or starting a new one. Either way, put the chosen DNS suffix in and press &lt;enter&gt;. Next comes one '''VERY''' important question: what to use as root password? We cannot stress this enough: choose a SAFE password! Do NOT go for an easy-to-remember one, go for STRONG and SAFE. There are tools to help you generate strong passwords, like [http://www.pctools.com/guides/password/ this page]: use them! We strongly suggest 10 characters or more, including letters, mixed case, and numbers, so something like ''SuCRe4hecH'' (do NOT use this, generate your own!). Next, give the full name of the principal user of this server (your own, we assume), give the login-name (your given name, we assume), and a corresponding password. Again, use a SAFE password. As long as you don't make your principal user equivalent to root, you might go for a slightly weaker password (8 characters instead of 10), but we rather suggest you make the password just as strong (and different from!) the root password. After entering the details of these two users "root" and "you", we get to the server hardware. ==Partitioning== Now comes the question of partitioning, or how to divide the available disk space into chunks for the server to use. This is a tricky subject, because if you put all storage space into one partition, then some day a runaway process will fill up the entire disk with useless logs, and the system will crash. On the other hand, if you divvy up all space into little chunks, then some application is going to need space in one of those partitions where there is none, even though there may be plenty in other partitions. To minimize the chance of either problem occurring, we're going to use [http://tldp.org/HOWTO/LVM-HOWTO/whatisvolman.html Logical Volume Management (LVM2)] so that we can provision enough space to start our server, but keep some space in reserve to apply when needed, where it'll be needed. So, we at Saruman.biz have put together a recommended standard partitioning scheme. The basis (in accordance with the standard [[Debian directory structure]] is this: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Partition !style="background:#ffdead;"|MD !style="background:#ffdead;"|LVG !style="background:#ffdead;"|LV-name !style="background:#ffdead;"|Size <br> (physical machine) !style="background:#ffdead;"|Size (VM) !style="background:#ffdead;"|File System !style="background:#ffdead;"|Mount point |- | 1 | /dev/md0 | &nbsp; | &nbsp; | 100MiB | 100MiB | ext3 | /boot |- | 2 | /dev/md1 | &nbsp; | &nbsp; | 3GiB | 1GiB | ext3 | / |- | rowspan="8" valign="top" | 3 | rowspan="8" valign="top" | /dev/md2 | rowspan="8" valign="top" style="background:lightgrey"| system | style="background:lightgrey" | swap | 1GiB<ref name="swap">Rule of thumb: twice the size of the machine's RAM, but no less than 256MiB and no more than 2GiB</ref> | 256MiB<ref name="swap"/> | swap | &nbsp; |- | style="background:lightgrey" | var | 1GiB | 512MiB | ext3 | /var |- | style="background:lightgrey" | varlog | 1GiB | 512MiB | ext3 | /var/log |- | style="background:lightgrey" | appslog | 3GiB | -<ref>Yes, we think a separate ''appslog'' is a very good idea, but when creating a minimal VM, we have to save disk space ''somewhere''...</ref> | ext3 | /var/appslog |- | style="background:lightgrey" | home | 1GiB<ref name="home">Note that this heavily depends on the purpose of the machine; if it is not to house any users, then (almost) no space is needed for /home. But on the other hand if e.g. a virtual user is to be used for keeping mailstores, or other service users need home space, then /home needs to be big enough for that.</ref> | 512MiB<ref name="home"/> | ext3 | /home |- | style="background:lightgrey" | usr | 3GiB | 3GiB | ext3 | /usr |- | style="background:lightgrey" | tmp | 1GiB | 512MiB | ext3 | /tmp |- | style="background:lightgrey" | opt | 1GiB | - | ext3 | /opt |- ! colspan="4" style="text-align:right"| Total ! 18.1GiB ! 6.9GiB ! colspan="2" | |- |} As you can see, the partition table works as follows: we assume that we wind up with 3 partitions, either on three separate software RAID arrays (''md0'' through ''md2'') or on one single hardware RAID array (in which case the 2nd column ''MD'' does not apply). The size of the partitions depends on your machine's make: for standard physical machines the 5th column does sensible suggestions, even though you could choose to have different sizes and of course different divisions altogether. If your machine happens to be a virtual one, running inside a [http://www.vmware.com/products/server/ VMware Server] or [http://www.vmware.com/products/vi/esx/ VMware ESX host], or the like, then you might want to start out with more modest partitions. The same holds for small servers that must run off Flash drives. Anyways, we're now at the Debian installation screen that lets us partition our disks. We're ''not'' going to use any of the "guided" partitioning options, we go for "manual". Choosing that brings us to a screen showing all drives that the installation routine has detected, and all partitions on those drives that the installer can "see". We're going to do some assuming here once more: let's assume the drive(s) on which you want to install are visible, and are empty (containing no other partitions). <references/> ===Software RAID partitioning=== If you're to use software RAID, you now have to select the free space on the first drive, press &lt;enter&gt;, and then tell what you want to do with the free space: create a new partition, tell which size you want it to be (see table above), give the type of partition (primary), and give where on the disk it'll sit (the beginning). Next, a screen comes up that details how the partition you're requesting will be created. Here we make some changes: under "use as" we're going to select "physical volume for RAID". This clears all the other options in this screen, except for the "bootable" flag, which must be "on" for the first partition that we'll mount as ''/boot''. Now select "Done setting up the partition". Next, go to the free space on the second disk, and do ''exactly'' the same, to create an identical physical volume for RAID - if it's the first partition, select the "bootable" flag as well (we'll want to be able to boot from this second disk if the first disk fails, right?). Then go back to the rest of the free space on the first disk, make the second physical volume for RAID, duplicate it on the second disk. Then, go back to the rest of the free space on the first disk, make the third physical volume for RAID, and again duplicate it on the second disk. If you now go back to the "partition disks" overview, you'll see all the partitions you've specified listed on their respective disks. But at the top an extra option has appeared, called "configure software RAID". When you now select this option, the installer will ask if it may write the changes you've made to disk. This actually creates the partition tables on the disks. Now you can create RAID devices. The RAID levels that Debian 6.0 offer are 0 (striping), 1 (mirroring), 5 (distributed redundancy), 6 (double distributed redundancy) ant 10 (striped mirrors). For your operating system disk pair, level 1 is the only sane choice. When selecting RAID 1, the installer asks how many active devices to use (2), how many spares (0), and then offers a selection screen where you can mark all members of the array. Select the first partition of both disks (presumably ''/dev/sda1'' and ''/dev/sdb1'') which should correspond to the 100MiB partitions you've created. Then create the other MD devices. Finally, choose &lt;finish&gt;. You'll drop back to the partitioner, but now the three created devices are available in the partitioner as "RAID1 device #0" etc. ===Hardware RAID partitioning=== Now, if you have hardware RAID, then on your first (boot) disk just make 3 partitions, in the following manner: Select the free space on the intended boot disk, press &lt;enter&gt;, select "create a new partition", and fill out the desired size (100MB). Type is primary, location is beginning of the disk, and in the details of the partition, we only need to change the Mount point to "/boot", and set the Bootable flag to "On". Then we're "Done setting up this partition". The second partition is made the same way, but the desired size is 3GB, the Mount point is "/", and the Bootable flag remains off. Again, we're "Done setting up this partition". The third partition is again a primary partition, it takes up the entire rest of the disk, but the type is not ext3, but "physical volume for LVM". Again, we're "Done setting up this partition". But now from the main partitioner screen, we can access "Configure the Logical Volume Manager". The installer asks if it can write out the choices made to the disk, and then enters the LVM setup screen, which begins with a summary explaining that you have one Free Physical Volume, and nothing more. ==Logical Volume creation== We now create a Volume Group (VG), which (in accordance to our partitioning standard) we'll call "system". In this VG, we'll add all Physical Volumes (being the one partition we've designated so in the previous step) using the space bar. To this end, in the volume group creation dialogue, we select that partition (''/dev/md2''). Note that all other selection choices are either unusable (unusable free space) or assigned to other purposes (/boot and /). Now we repeat the following process seven times: * select "Create Logical Volume" * select Volume Group "System" * give the LV Name (from the table, e.g. swap, var etc) * give the LV size (from the table, e.g. 1GB for swap etc) After this, we can select "Finish", the partitioner creates the seven LVs, and we're back at the partitioner screen, where there are now 7 extra "disks", with names such as ''LVM VG system, LV appslog - 3.0GB Linux device mapper (linear)''. Each of these "disks" has one block of empty space, which we now assign: seven times we repeat the following process: * select the unassigned chunk of empty space of an LV (e.g. ''appslog'') and press &lt;enter&gt;; * Change "Use as: do not use" into the desired filesystem (ext3 - only the LV "swap" gets as filesystem type "swap area"); * Change the mount point from "none" to the one corresponding with the name of the LV (note: the swap LV has no mountpoint; the appslog mountpoint must be entered manually as "/var/appslog" and varlog as "/var/log"); * If so desired, a label can be assigned to the partition (we usually don't); * select "Done setting up the partition". Note that sometimes, after creating and assigning the logical volumes, the installer has forgotten to mount the md0 and md1 partitions as /boot and /. In that case you'll have to reassign these partitions to these points in the filesystem. Once all this is done, we can look over the configuration once more, and then select "Finish partitioning and write changes to disk". A summary configuration screen will show, and we'll affirm with "yes" that these partitions can indeed be formatted. After some formatting screens flashing by (unless your partitions are particularly big, your system is particularly slow, or something goes wrong) the installation procedure continues. ==Base system setup== Now the Debian installer loads a base system. It will scan your installation CD/DVD, and ask if it should scan more CD/DVDs. We're going with "no" here. Then it will ask you how it can contact the Debian archives, in the dialogue "configure the package manager". For the NetInstall version of Debian, this is as good as mandatory. So here, we say "yes, use a Network Mirror", and in the following list select the country in which we are (in our case: the Netherlands), so the installer can present us with a number of network mirrors "close by". We select ftp.nl.debian.org. Next screen: should you be behind a proxy server, then it's possible to specify that here. And then the test: the system will say "scanning the mirror..." and try to contact the specified mirror. If it does not succeed, then there is either a network problem, a problem with this box's network card, or you've not specified the mirror or proxy correctly - so fix it. You'll know the network mirror has successfully been contacted when it's saying "Retrieving file 1 of 5". A number of files are retrieved, and the base system is set up. Somewhere early in this setup, the next dialogue appears - currently "configuring popularity-contest". Answer this question as you please. And then one of the last "big" questions: Software Selection. In this dialogue, you can easily select bundles of software to be installed. The choices are currently: * Graphical desktop environment * Web server * Print server * DNS server * File server * Mail server * SQL database * SSH server * Laptop * Standard system utilities (selected by default) We have to make a little confession here: we've never before used this option in the installer. In fact, we even deselect the Standard System, so as to minimize the number of software packages that the base installation of our server contains. This makes it more work to manually add packages later, but we feel it gives us more control and understanding of our systems. So if you're like us: deselect the "Standard system utilities" entry, and select Continue. The next dialogue handles the installation of the [http://www.gnu.org/software/grub/ ''grub'' bootloader]. Unless your disks weren't empty and you're attempting to make this system multiboot, you'll most likely get a question if you'll allow the installer to install ''grub'' into the boot sector of the first hard disk. We'll confirm with "Yes". After the installation of grub is completed, the CD-ROM is ejected, and the system is ready to reboot into Debian Squeeze. Remove the CD and select "Continue" ==Finishing up the installation== The system should reboot into Debian. This means you should see the following boot sequence: * your machine's standard POST messages * briefly a '''welcome to GRUB''' message * then, a blue grub menu on a black screen, with two entries: ** Debian GNU/Linux, with Linux 2.6.32-5-686 ** Debian GNU/Linux, with Linux 2.6.32-5-686 (recovery mode) * then, after a default (short!) time-out, the first grub option will go into effect, and the Linux kernel is started. Lots of cryptic messages in grey-on-black will scroll by, until the last few lines read: Debian GNU/Linux 6.0 easton2 tty1 easton2 login: '''_''' If your system does not reach this login, and/or some horrible error messages appear anywhere in this boot sequence, then you've got some extra work ahead. For now we'll assume you've reached the login prompt without problem. Log in as the principal user (try to avoid logging in as root! That's BAD practice!). Once logged in, save a copy of the boot messages using ''sudo dmesg > boot.txt'' or whatever you like. Then look through the boot messages, e.g. with ''vi -R boot.txt''. Furthermore, [[APT_and_aptitude | use Aptitude]] to make sure ''all'' your software is updated to the latest version. Done! Your base system is ready. You probably now want to [[essential system software | install essential software]], [[roll your own kernel]] and [[connect your server to the Internet]]. Furthermore, you might want to create a couple of [[aliases in every profile]] so that your favourite commands are always available. 418e3ab3feb56f69c2e2f642b9bb1461a0e4ddf9 2717 2715 2012-03-12T20:28:32Z Saruman! 2 put hardware section by itself.. wikitext text/x-wiki __TOC__ ==Hardware preparation== When installing a new server, you must begin with [[Server hardware prep|getting your server hardware right]]. Assuming you've built yourself a new server platform, you can install the operating system following the steps outlined below. Note: it is assumed the server is bare, and the hard disks are completely clean. If they are not, here's how to [[Cleaning a hard disk|clean]] them. ==Planning your network names== If your machine must become a part of an existing network, then it's almost certain that you already have a DNS domain in place; in that case: obtain the DNS suffix your machine will get (the DNS domain your machine will "belong" to). However, it's also possible that this machine is going to be the first machine in your new network, in which case the whole issue of DNS suffixes is wide open. If you need more information on DNS, go [[http://www.isc.org/sw/bind/arm95/Bv9ARM-all.html#id2564824 here]]. For now we'll assume you have (or will quickly obtain) a working knowledge of the DNS system. Here is our tip on choosing a DNS domain for your home network: * do '''not''' use a publicly registered domain name (e.g. "cocacola.com") for any machine that's not primarily intended to serve the public on the Internet; * for machines serving a private network, we urge you to use Top Level Domain name "lan" (to signify your machine is on a Local Area Network or LAN) * for the Domain Name itself, we suggest you use a level 2 name, like "saruman.lan", and not a level 3 name, like "mister.saruman.lan". This is only a short section on DNS, but remember that once a proper DNS system is in place, it takes some work to change it. At any rate, this section has most likely showed you that you need to put some thought into the DNS Domain Name design of your home network. OK, with this out of the way, we can get to installing the OS. ==Operating System installation== To install an Operating System (OS), it's kinda instrumental that you have one. Here, we're going to use [http://www.debian.org/intro/about Debian], the biggest [http://www.debian.org/intro/about#free Free] OS that we know of. Free stands for Freedom, but incidentally that Freedom also means it's gratis, an appealing aspect of Free. To get your own copy of Debian, go to their [http://www.debian.org/distrib/ download site] and obtain a [http://www.debian.org/releases/ release] image - you can opt for the current stable version, but unless Debian has released a new stable version fairly recently, it's also reasonably safe to use the current testing version. In this example we're going to use the Testing version, Debian 7.0, or "Wheezy" as it's also known. (some pages of this wiki were written in the time of Debian 6.0 Squeeze or 5.0 Lenny, and haven't been updated yet). Besides the choice which release of Debian you want to run, you also have to know for which platform you're downloading (in our case: either ''amd64'' or ''i386'' depending on your hardware platform) and what kind of install you wish - if you have a working, fast Internet connection available at the time of install, then we recommend getting the [http://www.debian.org/CD/netinst/ netinst] CD image; it's a relatively small CD, that'll be able to get you going, but gets most of the software you'll need straight from the 'net at install time. In the example at hand we're installing on an AMD Athlon x2-based server, on which we wish to install 64-bits software. We'll download [http://cdimage.debian.org/cdimage/weekly-builds/amd64/iso-cd/debian-testing-amd64-CD-1.iso debian-testing-amd64-CD-1.iso], which is a pre-release candidate of Wheezy. Burn this to a CD-recordable and boot your prepared hardware platform from this CD. After booting from the CD, a friendly graphic screen shows you the Installer boot menu. Your choices are * Install, the default non-graphical installation; * Graphical install, so you can click things; * Advanced options, where you can select expert options like the rescue mode; * Help; this drops you to a non-graphical screen where you can select help texts by using function keys. The screens explain how you can start the installation with extra parameters to instruct Debian to handle your hardware in a non-standard way, e.g. on an old machine with a problematic videocard you could run "install vga=771" (for some laptops) or "install vga=normal fb=false" (to disable the screen framebuffer); * Install with speech synthesis (sorry, no experience with this yet). We're going to use the standard Command Line installation, so we choose "Install" and hit &lt;enter&gt;. {| class="wikitable" border="1" |- |We could simply use "Graphic install", in which case we'd have a nice fresh Graphical User Interface for our installation. ''We're'' not going to, because we're real men, and [http://isg.ee.ethz.ch/tools/realmen/ Real Men Don't Click]. Also, we've found that from the GUI it's hard to switch to a second console and then back. We could also go to the Advanced options, and opt for "Expert install" or "Graphical expert install" as installation method, because it gives a much finer grain of control; however we usually don't need that control, and can do without the barrage of extra questions that the "expert" installation method pose. |} After the Linux kernel finishes initializing the machine, a simple text-based installer appears that immediately starts asking questions. Answer them according to your needs. Our example system uses the following choices: * Language: English * country: other &gt; Europe &gt; Netherlands * locale (since there's no default locale for the combination Netherlands/English): United States - en_US.UTF-8 * keymap: American English (since we have a keyboard with US layout) Some installation software loads, and we get to the next phase: if you have multiple NICs in your machine (which we believe you ''should'' have!!), and if they're detected properly, then you're required to indicate which of the detected network interface cards (NIC) is going to be the "primary" NIC. {| class="wikitable" border="1" |- |Here, trouble could begin. If your machine has only network cards that are '''not''' supported, then you'll see '''no''' cards here - but then how are you going to do a NetInstall? A solution would be to (temporarily) install a NIC that ''is'' supported, like a cheap Realtek card, or an old 3Com 905 card. Then, when the whole system is installed, up and running, you could compile a new kernel that contains support for your actual NICs, and when these work, remove the temporary NIC. For now, we'll assume that at least one of your NICs is recognised properly by the Debian installation routine. |} Select the card that's connected and has (indirect) access to Internet (again: it should ''not'' be connected straight to the wild wild web, but sit safely behind a firewall, at least until we've installed our own firewall); if at all possible, let it be the NIC that'll be connected to your home network itself, on the ''inside'' of your server. Let's assume that this NIC is designated ''eth0'' by the Debian installation. This card will now be configured using DHCP, so if you're on a network with a DHCP-server, the network will work straight away. If it's not, you can either configure the network manually or fix your DHCP-server and connection between it and ''eth0''. Next is one of the hardest questions that any OS installation is going to ask you: what will be the host name of the system? You could easily change it at any time in the future, but possibly with lots of hassle, so you better choose wisely. Here are our tips: * do '''not''' name your machine after the user that's going to use it, e.g. "bernie-pc" (at some time in the future, Bernie's machine will be moved to Alice, so then Alice is working on "bernie-pc" which makes the situation quite unclear); * do '''not''' name your machine after the department or workgroup that's using it most, e.g. "accounting-srv" (same reasoning); * do '''not''' name your machine after it's main function, e.g. "printserver" (at some time in the future, the main function is moved to another machine, and/or an alternative function will become the main function of the machine); * do '''not''' name your machine after it's location, e.g. "srv-boston" (at some time in the future, the box will be moved to another location); * do '''not''' name your machine after it's hardware configuration, e.g. "ibmx346" (at some time in the future, either another xSeries x346 will be wheeled in, or the machine will be upgraded to accomodate increased use or overcome hardware problems - your "ibmx346" could suddenly be running on an xSeries x3650). What we feel are safe names for ''any'' machine in your network are true names, perhaps linked to a common theme: names of European cities, names of movie characters, names of countries or holiday destinations et cetera. Less imaginative would be coded names like "server0001". Immediately following comes the question of the Domain Name. This is about a DNS domain, so effectively the installation program is asking which DNS suffix the host name should have; if the DHCP-server already provided something it'll be suggested, but you can override it if need be. In the preparatory phase, you'll have decided on continuation of your current DNS schema, or starting a new one. Either way, put the chosen DNS suffix in and press &lt;enter&gt;. Next comes one '''VERY''' important question: what to use as root password? We cannot stress this enough: choose a SAFE password! Do NOT go for an easy-to-remember one, go for STRONG and SAFE. There are tools to help you generate strong passwords, like [http://www.pctools.com/guides/password/ this page]: use them! We strongly suggest 10 characters or more, including letters, mixed case, and numbers, so something like ''SuCRe4hecH'' (do NOT use this, generate your own!). Next, give the full name of the principal user of this server (your own, we assume), give the login-name (your given name, we assume), and a corresponding password. Again, use a SAFE password. As long as you don't make your principal user equivalent to root, you might go for a slightly weaker password (8 characters instead of 10), but we rather suggest you make the password just as strong (and different from!) the root password. After entering the details of these two users "root" and "you", we get to the server hardware. ==Partitioning== Now comes the question of partitioning, or how to divide the available disk space into chunks for the server to use. This is a tricky subject, because if you put all storage space into one partition, then some day a runaway process will fill up the entire disk with useless logs, and the system will crash. On the other hand, if you divvy up all space into little chunks, then some application is going to need space in one of those partitions where there is none, even though there may be plenty in other partitions. To minimize the chance of either problem occurring, we're going to use [http://tldp.org/HOWTO/LVM-HOWTO/whatisvolman.html Logical Volume Management (LVM2)] so that we can provision enough space to start our server, but keep some space in reserve to apply when needed, where it'll be needed. So, we at Saruman.biz have put together a recommended standard partitioning scheme. The basis (in accordance with the standard [[Debian directory structure]] is this: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Partition !style="background:#ffdead;"|MD !style="background:#ffdead;"|LVG !style="background:#ffdead;"|LV-name !style="background:#ffdead;"|Size <br> (physical machine) !style="background:#ffdead;"|Size (VM) !style="background:#ffdead;"|File System !style="background:#ffdead;"|Mount point |- | 1 | /dev/md0 | &nbsp; | &nbsp; | 100MiB | 100MiB | ext3 | /boot |- | 2 | /dev/md1 | &nbsp; | &nbsp; | 3GiB | 1GiB | ext3 | / |- | rowspan="8" valign="top" | 3 | rowspan="8" valign="top" | /dev/md2 | rowspan="8" valign="top" style="background:lightgrey"| system | style="background:lightgrey" | swap | 1GiB<ref name="swap">Rule of thumb: twice the size of the machine's RAM, but no less than 256MiB and no more than 2GiB</ref> | 256MiB<ref name="swap"/> | swap | &nbsp; |- | style="background:lightgrey" | var | 1GiB | 512MiB | ext3 | /var |- | style="background:lightgrey" | varlog | 1GiB | 512MiB | ext3 | /var/log |- | style="background:lightgrey" | appslog | 3GiB | -<ref>Yes, we think a separate ''appslog'' is a very good idea, but when creating a minimal VM, we have to save disk space ''somewhere''...</ref> | ext3 | /var/appslog |- | style="background:lightgrey" | home | 1GiB<ref name="home">Note that this heavily depends on the purpose of the machine; if it is not to house any users, then (almost) no space is needed for /home. But on the other hand if e.g. a virtual user is to be used for keeping mailstores, or other service users need home space, then /home needs to be big enough for that.</ref> | 512MiB<ref name="home"/> | ext3 | /home |- | style="background:lightgrey" | usr | 3GiB | 3GiB | ext3 | /usr |- | style="background:lightgrey" | tmp | 1GiB | 512MiB | ext3 | /tmp |- | style="background:lightgrey" | opt | 1GiB | - | ext3 | /opt |- ! colspan="4" style="text-align:right"| Total ! 18.1GiB ! 6.9GiB ! colspan="2" | |- |} As you can see, the partition table works as follows: we assume that we wind up with 3 partitions, either on three separate software RAID arrays (''md0'' through ''md2'') or on one single hardware RAID array (in which case the 2nd column ''MD'' does not apply). The size of the partitions depends on your machine's make: for standard physical machines the 5th column does sensible suggestions, even though you could choose to have different sizes and of course different divisions altogether. If your machine happens to be a virtual one, running inside a [http://www.vmware.com/products/server/ VMware Server] or [http://www.vmware.com/products/vi/esx/ VMware ESX host], or the like, then you might want to start out with more modest partitions. The same holds for small servers that must run off Flash drives. Anyways, we're now at the Debian installation screen that lets us partition our disks. We're ''not'' going to use any of the "guided" partitioning options, we go for "manual". Choosing that brings us to a screen showing all drives that the installation routine has detected, and all partitions on those drives that the installer can "see". We're going to do some assuming here once more: let's assume the drive(s) on which you want to install are visible, and are empty (containing no other partitions). <references/> ===Software RAID partitioning=== If you're to use software RAID, you now have to select the free space on the first drive, press &lt;enter&gt;, and then tell what you want to do with the free space: create a new partition, tell which size you want it to be (see table above), give the type of partition (primary), and give where on the disk it'll sit (the beginning). Next, a screen comes up that details how the partition you're requesting will be created. Here we make some changes: under "use as" we're going to select "physical volume for RAID". This clears all the other options in this screen, except for the "bootable" flag, which must be "on" for the first partition that we'll mount as ''/boot''. Now select "Done setting up the partition". Next, go to the free space on the second disk, and do ''exactly'' the same, to create an identical physical volume for RAID - if it's the first partition, select the "bootable" flag as well (we'll want to be able to boot from this second disk if the first disk fails, right?). Then go back to the rest of the free space on the first disk, make the second physical volume for RAID, duplicate it on the second disk. Then, go back to the rest of the free space on the first disk, make the third physical volume for RAID, and again duplicate it on the second disk. If you now go back to the "partition disks" overview, you'll see all the partitions you've specified listed on their respective disks. But at the top an extra option has appeared, called "configure software RAID". When you now select this option, the installer will ask if it may write the changes you've made to disk. This actually creates the partition tables on the disks. Now you can create RAID devices. The RAID levels that Debian 6.0 offer are 0 (striping), 1 (mirroring), 5 (distributed redundancy), 6 (double distributed redundancy) ant 10 (striped mirrors). For your operating system disk pair, level 1 is the only sane choice. When selecting RAID 1, the installer asks how many active devices to use (2), how many spares (0), and then offers a selection screen where you can mark all members of the array. Select the first partition of both disks (presumably ''/dev/sda1'' and ''/dev/sdb1'') which should correspond to the 100MiB partitions you've created. Then create the other MD devices. Finally, choose &lt;finish&gt;. You'll drop back to the partitioner, but now the three created devices are available in the partitioner as "RAID1 device #0" etc. ===Hardware RAID partitioning=== Now, if you have hardware RAID, then on your first (boot) disk just make 3 partitions, in the following manner: Select the free space on the intended boot disk, press &lt;enter&gt;, select "create a new partition", and fill out the desired size (100MB). Type is primary, location is beginning of the disk, and in the details of the partition, we only need to change the Mount point to "/boot", and set the Bootable flag to "On". Then we're "Done setting up this partition". The second partition is made the same way, but the desired size is 3GB, the Mount point is "/", and the Bootable flag remains off. Again, we're "Done setting up this partition". The third partition is again a primary partition, it takes up the entire rest of the disk, but the type is not ext3, but "physical volume for LVM". Again, we're "Done setting up this partition". But now from the main partitioner screen, we can access "Configure the Logical Volume Manager". The installer asks if it can write out the choices made to the disk, and then enters the LVM setup screen, which begins with a summary explaining that you have one Free Physical Volume, and nothing more. ==Logical Volume creation== We now create a Volume Group (VG), which (in accordance to our partitioning standard) we'll call "system". In this VG, we'll add all Physical Volumes (being the one partition we've designated so in the previous step) using the space bar. To this end, in the volume group creation dialogue, we select that partition (''/dev/md2''). Note that all other selection choices are either unusable (unusable free space) or assigned to other purposes (/boot and /). Now we repeat the following process seven times: * select "Create Logical Volume" * select Volume Group "System" * give the LV Name (from the table, e.g. swap, var etc) * give the LV size (from the table, e.g. 1GB for swap etc) After this, we can select "Finish", the partitioner creates the seven LVs, and we're back at the partitioner screen, where there are now 7 extra "disks", with names such as ''LVM VG system, LV appslog - 3.0GB Linux device mapper (linear)''. Each of these "disks" has one block of empty space, which we now assign: seven times we repeat the following process: * select the unassigned chunk of empty space of an LV (e.g. ''appslog'') and press &lt;enter&gt;; * Change "Use as: do not use" into the desired filesystem (ext3 - only the LV "swap" gets as filesystem type "swap area"); * Change the mount point from "none" to the one corresponding with the name of the LV (note: the swap LV has no mountpoint; the appslog mountpoint must be entered manually as "/var/appslog" and varlog as "/var/log"); * If so desired, a label can be assigned to the partition (we usually don't); * select "Done setting up the partition". Note that sometimes, after creating and assigning the logical volumes, the installer has forgotten to mount the md0 and md1 partitions as /boot and /. In that case you'll have to reassign these partitions to these points in the filesystem. Once all this is done, we can look over the configuration once more, and then select "Finish partitioning and write changes to disk". A summary configuration screen will show, and we'll affirm with "yes" that these partitions can indeed be formatted. After some formatting screens flashing by (unless your partitions are particularly big, your system is particularly slow, or something goes wrong) the installation procedure continues. ==Base system setup== Now the Debian installer loads a base system. It will scan your installation CD/DVD, and ask if it should scan more CD/DVDs. We're going with "no" here. Then it will ask you how it can contact the Debian archives, in the dialogue "configure the package manager". For the NetInstall version of Debian, this is as good as mandatory. So here, we say "yes, use a Network Mirror", and in the following list select the country in which we are (in our case: the Netherlands), so the installer can present us with a number of network mirrors "close by". We select ftp.nl.debian.org. Next screen: should you be behind a proxy server, then it's possible to specify that here. And then the test: the system will say "scanning the mirror..." and try to contact the specified mirror. If it does not succeed, then there is either a network problem, a problem with this box's network card, or you've not specified the mirror or proxy correctly - so fix it. You'll know the network mirror has successfully been contacted when it's saying "Retrieving file 1 of 5". A number of files are retrieved, and the base system is set up. Somewhere early in this setup, the next dialogue appears - currently "configuring popularity-contest". Answer this question as you please. And then one of the last "big" questions: Software Selection. In this dialogue, you can easily select bundles of software to be installed. The choices are currently: * Graphical desktop environment * Web server * Print server * DNS server * File server * Mail server * SQL database * SSH server * Laptop * Standard system utilities (selected by default) We have to make a little confession here: we've never before used this option in the installer. In fact, we even deselect the Standard System, so as to minimize the number of software packages that the base installation of our server contains. This makes it more work to manually add packages later, but we feel it gives us more control and understanding of our systems. So if you're like us: deselect the "Standard system utilities" entry, and select Continue. The next dialogue handles the installation of the [http://www.gnu.org/software/grub/ ''grub'' bootloader]. Unless your disks weren't empty and you're attempting to make this system multiboot, you'll most likely get a question if you'll allow the installer to install ''grub'' into the boot sector of the first hard disk. We'll confirm with "Yes". After the installation of grub is completed, the CD-ROM is ejected, and the system is ready to reboot into Debian Squeeze. Remove the CD and select "Continue" ==Finishing up the installation== The system should reboot into Debian. This means you should see the following boot sequence: * your machine's standard POST messages * briefly a '''welcome to GRUB''' message * then, a blue grub menu on a black screen, with two entries: ** Debian GNU/Linux, with Linux 2.6.32-5-686 ** Debian GNU/Linux, with Linux 2.6.32-5-686 (recovery mode) * then, after a default (short!) time-out, the first grub option will go into effect, and the Linux kernel is started. Lots of cryptic messages in grey-on-black will scroll by, until the last few lines read: Debian GNU/Linux 6.0 easton2 tty1 easton2 login: '''_''' If your system does not reach this login, and/or some horrible error messages appear anywhere in this boot sequence, then you've got some extra work ahead. For now we'll assume you've reached the login prompt without problem. Log in as the principal user (try to avoid logging in as root! That's BAD practice!). Once logged in, save a copy of the boot messages using ''sudo dmesg > boot.txt'' or whatever you like. Then look through the boot messages, e.g. with ''vi -R boot.txt''. Furthermore, [[APT_and_aptitude | use Aptitude]] to make sure ''all'' your software is updated to the latest version. Done! Your base system is ready. You probably now want to [[essential system software | install essential software]], [[roll your own kernel]] and [[connect your server to the Internet]]. Furthermore, you might want to create a couple of [[aliases in every profile]] so that your favourite commands are always available. db6301c9a70df25c970603853c79b98ce14a75a0 0 1629 2716 2012-03-12T20:25:12Z Saruman! 2 hardware section wikitext text/x-wiki When building a small server, the first line of business is getting the hardware right. And you must get it right, because hardware forms the foundations of your server. If the foundations are shoddy, then so will your server be. ==Getting the hardware== {| class="wikitable" border="1" |- |Note: in the following we're assuming you'll be assembling an x86 or x64 type of machine, as it has about the best price/performance ratio you could wish. Hardware costs for other platforms, e.g. IBM's Series p or HP 9000, can be much higher, while platforms like ARM are energy efficient, but just not very powerful. Also, the availability of components and of help can be less than with the ubiquitous x86/x64 platforms. |} Naturally, before we can begin to install the operating system, we need to obtain the necessary hardware. Which hardware you require depends on what you want the server for; a test server on which you will test only a single feature for a short while does not need the same quality of hardware as does a server that's supposed to act as a home server for many tasks for a long time. We'll assume your server will be like ours: a home server that must perform many tasks with sufficient performance for a few users, that's reliable and will last for a couple of years. So build or obtain a server with at least the following hardware: * a spacious casing with big, quiet cooling fans, like the [http://www.coolermaster.com/products/product.php?act=detail&id=317 one we have]; * an efficient, heavy-duty power supply that's rated high enough for your devices, and has a decent efficiency. For example, a [http://www.corsair.com/products/power_supplies.aspx Corsair HX520] power supply; * a server class motherboard, e.g. an [http://www.intel.com/content/www/us/en/motherboards/server-motherboards/server-board.html Intel] or [http://uk.asus.com/Server_Workstation/Server_Motherboards/AMD_Dual_Processor AMD] based motherboard. DO NOT go for the cheapest motherboard you can find: if you pay peanuts, that's what you'll get. Server class motherboards have the quality, stability and durability you'll need from it, and usually also most of the needed peripherals, like multiple ethernet network cards on-board. Usually a Linux server does not require much in the way of video performance (and the screen will be used rarely, if ever), so any old integrated graphics will do. * a matching CPU - or multiple, if you think you need the power and the selected motherboard has the sockets. Furthermore, it pays to think about the energy use of your server CPU. For instance, you could choose an AMD Athlon X2 5600+, running at 2,8 Ghz and 89W maximum, but you can also go for an AMD Athlon X2 4850E, which is dualcore at 2,5GHz, but uses only 45W maximum - almost half of the former! And over a one year period, this choice can save up to 385 kWH. With electricity costing close to €0,25 per kWH (at least for some of us), that could save you €96,- a year (assuming your CPU is running at top speed all the time - which it won't). All I'm saying is: think about power use. * a CD-ROM- or DVD-player - although you might not need it any more after installation. Thus, you may opt to use an external USB DVD-player, if your system allows for booting from it. * ''multiple'' hard disks - you'll want redundancy, because every hard disk fails at some time. The drive with your data on it will fail fatally when it is most inconvenient to you, and any data on it that you consider valuable will likely be lost forever. To make Murphy's work somewhat harder for him, we're going to store our data redundantly, so that if any drive in the server fails, we'll not lose our data or our server. Thus, get yourself at least two hard disks for your operating system, at least 40GiB in size (don't think you'll be able to buy smaller ones nowadays), and spanking new (NEVER use old hard disks for your production server, new ones are just too cheap to run that risk!). You may also consider using 2.5" "notebook" hard disks, since they also consume less power than do 3.5" hard disks. However, you should investigate before buying SSDs for your Linux server, as there are some caveats there. We're not going into that subject here. * (multipe) network card(s) (NICs) if your motherboard does not have enough NICs integrated on-board. You'll want a NIC for your network, and another one for your Internet connection; and possible a third one for the wireless segment of your network. Now build a machine out of the above, or have someone build it for you. ==Preparation of the hardware== (Note: in the following we're again assuming you're running an x86/x64 type of machine. Hardware requirements and preparation for other platforms, e.g. IBM's Series p or HP 9000, can differ significantly) Next, check the assembled hardware: * is the configuration complete? If it does not have a CD/DVDplayer from which it can boot, then installing the software gets more difficult - at least get an USB external DVDdrive or something like that. * are all components connected properly (memory modules seated correctly in their sockets, AGP card inserted correctly into the AGP slot, et cetera) and are all cable connections made (multiple power cables to the motherboard, one power cable plus one data cable to each hard disk, etcetera)? Following this, you may hook up the machine. It's going to need power, and you will need at least a keyboard and a monitor attached. And if you want to use a Graphic User Interface to install, a mouse is required also. When you've ensured that everything is safe, you can turn on the machine, and continue to check it: * do all fans start to run when you turn on the machine? (if not, then '''quickly''' turn off your machine and correct the problem!) * does/do the hard disk(s) spin up? * do the power button and reset button operate correctly? * are the power led, HDD led and other display gadgetry functional? * when you let the machine power up, does it emit a single beep? And does it then show a Power-On Self Test screen (POST)? * Does it show the correct amount of memory in the POST screen? The correct number & speed of the CPU(s)? * Does the machine recognise all controller cards (SCSI, S-ATA etc)? And all attached DVD-drives and hard disks? * are all BIOSes/firmwares up to date? * If you have a hardware RAID controller, are your RAID arrays built already? * does the machine attempt to boot from at least the hard disk? ...et cetera. If there is any problem, or you want to update the BIOS or firmwares, it's best to do it before the operating system is installed. This Wiki, however, is not the place to get the information on how to accomplish these type of tasks. The last steps in the preparation of the hardware, are * to ensure that the machine can boot from CD/DVD, so that you can start installing Debian from it. It is possible to install Debian over the network, but that requires setting up a [http://www.debian-administration.org/articles/478 PXE Boot server] which is (currently) outside the scope of this wiki. * to connect the hardware to the Internet, so that it can get all required updates etcetera; please do ''not'' connect the box ''straight'' to the Internet, but make sure that it's safely behind a firewall, or failing that, a NAT router. By now the system should be almost ready to receive it's Operating System. But first we have an issue to tackle: that of redundancy. ==Software or hardware RAID== Your hard disks will fail. They absolutely will. It is never a question of "if", only of "when". So what will you do when the hard disk containing your complete operating system fails (besides pulling your hair out, that is)? What we propose is this: hard disks are pretty cheap nowadays, so let's use [http://en.wikipedia.org/wiki/Redundant_array_of_independent_disks RAID technology] to make our hard drive space resilient against failure of a whole drive. So first make sure that you have ''two'' disks of equal size instead of only one. Had you already been planning to use multiple disks already, then make sure you have at least ''one'' disk more than your space requirements prescribe; the space on that extra drive will provide the needed redundancy. Next, [[RAID fundamentals under Linux | click here]] to learn a bit more about RAID, to make the decision to use hardware-based and/or software-based RAID, and to plan your RAID arrays. In this example, we'll assume you're using hardware RAID on a RAID controller that's supported by the Debian installation software. This means that the installation software will "see" your RAID array(s) and present them as usable drives. 719e59b0312a1a1359426520fea25aea1b81b4ac 0 1618 2718 2672 2012-03-12T20:29:02Z Saruman! 2 removing hw section wikitext text/x-wiki __TOC__ ==Hardware preparation== When installing a new server, you must begin with [[Server hardware prep|getting your server hardware right]]. Assuming you've built yourself a new server platform, you can install the operating system following the steps outlined below. Note: it is assumed the server is bare, and the hard disks are completely clean. If they are not, here's how to [[Cleaning a hard disk|clean]] them. ==Planning your network names== If your machine must become a part of an existing network, then it's almost certain that you already have a DNS domain in place; in that case: obtain the DNS suffix your machine will get (the DNS domain your machine will "belong" to). However, it's also possible that this machine is going to be the first machine in your new network, in which case the whole issue of DNS suffixes is wide open. If you need more information on DNS, go [[http://www.isc.org/sw/bind/arm95/Bv9ARM-all.html#id2564824 here]]. For now we'll assume you have (or will quickly obtain) a working knowledge of the DNS system. Here is our tip on choosing a DNS domain for your home network: * do '''not''' use a publicly registered domain name (e.g. "cocacola.com") for any machine that's not primarily intended to serve the public on the Internet; * for machines serving a private network, we urge you to use Top Level Domain name "lan" (to signify your machine is on a Local Area Network or LAN) * for the Domain Name itself, we suggest you use a level 2 name, like "saruman.lan", and not a level 3 name, like "mister.saruman.lan". This is only a short section on DNS, but remember that once a proper DNS system is in place, it's pretty much work to change it. At any rate, this section has most likely showed you that you need to put some thought into the DNS Domain Name design of your home network. OK, with this out of the way, we can get to installing the OS. ==Operating System installation== To install an Operating System (OS), it's kinda instrumental that you have one. Here, we're going to use [http://www.debian.org/intro/about Debian], the biggest [http://www.debian.org/intro/about#free Free] OS that we know of. Free stands for Freedom, but incidentally that Freedom also means it's gratis, an appealing aspect of Free. To get your own copy of Debian, go to their [http://www.debian.org/distrib/ download site] and obtain the latest [http://www.debian.org/releases/ Stable] image - in this wiki it's Debian 6.0, or "Squeeze" as it's also known. Besides the choice which release of Debian you want to run, you also have to know for which platform you're downloading (in our case: either ''amd64'' or ''i386'' depending on your hardware platform) and what kind of install you wish - if you have a working, fast Internet connection available at the time of install, then we recommend getting the [[http://www.debian.org/CD/netinst/ netinst] CD image; it's a relatively small CD, that'll be able to get you going, but gets most of the software you'll need straight from the 'net at install time. In the example at hand we're installing on an AMD Athlon x2-based server, on which we wish to install 64-bits software. We'll download [http://cdimage.debian.org/debian-cd/6.0.1a/amd64/iso-cd/debian-6.0.1a-amd64-CD-1.iso debian-6.0.1a-amd64-CD-1.iso], which is Squeeze after its first update. Burn this to a CD-recordable and boot your prepared hardware platform from this CD. After booting from the CD, a friendly graphic screen shows you the Installer boot menu. Your choices are * Install, the default non-graphical installation; * Graphical install, so you can click things; * Advanced options, where you can select expert options like the rescue mode; * Help; this drops you to a non-graphical screen where you can select help texts by using function keys. The screens explain how you can start the installation with extra parameters to instruct Debian to handle your hardware in a non-standard way, e.g. on an old machine with a problematic videocard you could run "install vga=771" (for some laptops) or "install vga=normal fb=false" (to disable the screen framebuffer). We're going to use the standard Command Line installation, so we choose "Install" and hit &lt;enter&gt;. {| class="wikitable" border="1" |- |We could easily use "Graphic install", in which case we'd have a nice fresh Graphical User Interface for our installation. ''We're'' not going to, because we're real men, and [http://isg.ee.ethz.ch/tools/realmen/ Real Men Don't Click]. Also, we've found that from the GUI it's hard to switch to a second console and then back. We could also go to the Advanced options, and opt for "Expert install" or "Graphical expert install" as installation method, because it gives a much finer grain of control; however we usually don't need that control, and can do without the barrage of extra questions that the "expert" installation method pose. |} After the Linux kernel finishes initializing the machine, a simple text-based installer appears that immediately starts asking questions. Answer them according to your needs. Our example system uses the following choices: * Language: English * country: other &gt; Europe &gt; Netherlands * locale (since there's no default locale for the combination Netherlands/English): United States - en_US.UTF-8 * keymap: American English (since we have a keyboard with US layout) Some installation software loads, and we get to the next phase: if you have multiple NICs in your machine (which we believe you ''should'' have!!), and if they're detected properly, then you're required to indicate which of the detected network interface cards (NIC) is going to be the "primary" NIC. {| class="wikitable" border="1" |- |Here, trouble could begin. If your machine has only network cards that are '''not''' supported, then you'll see '''no''' cards here - but then how are you going to do a NetInstall? A solution would be to (temporarily) install a NIC that ''is'' supported, like a cheap Realtek card, or an old 3Com 905 card. Then, when the whole system is installed, up and running, you could compile a new kernel that contains support for your actual NICs, and when these work, remove the temporary NIC. For now, we'll assume that at least one of your NICs is recognised properly by the Debian installation routine. |} Select the card that's connected and has (indirect) access to Internet (again: it should ''not'' be connected straight to the wild wild web, but sit safely behind a firewall, at least until we've installed our own firewall); if at all possible, let it be the NIC that'll be connected to your home network itself, on the ''inside'' of your server. Let's assume that this NIC is designated ''eth0'' by the Debian installation. This card will now be configured using DHCP, so if you're on a network with a DHCP-server, the network will work straight away. If it's not, you can either configure the network manually or fix your DHCP-server and connection between it and ''eth0''. Next is one of the hardest questions that any OS installation is going to ask you: what will be the host name of the system? You could easily change it at any time in the future, but possibly with lots of hassle, so you better choose wisely. Here are our tips: * do '''not''' name your machine after the user that's going to use it, e.g. "bernie-pc" (at some time in the future, Bernie's machine will be moved to Alice, so then Alice is working on "bernie-pc" which makes the situation quite unclear); * do '''not''' name your machine after the department or workgroup that's using it most, e.g. "accounting-srv" (same reasoning); * do '''not''' name your machine after it's main function, e.g. "printserver" (at some time in the future, the main function is moved to another machine, and/or an alternative function will become the main function of the machine); * do '''not''' name your machine after it's location, e.g. "srv-boston" (at some time in the future, the box will be moved to another location); * do '''not''' name your machine after it's hardware configuration, e.g. "ibmx346" (at some time in the future, either another xSeries x346 will be wheeled in, or the machine will be upgraded to accomodate increased use or overcome hardware problems - your "ibmx346" could suddenly be running on an xSeries x3650). What we feel are safe names for ''any'' machine in your network are true names, perhaps linked to a common theme: names of European cities, names of movie characters, names of countries or holiday destinations et cetera. Less imaginative would be coded names like "server0001". Immediately following comes the question of the Domain Name. This is about a DNS domain, so effectively the installation program is asking which DNS suffix the host name should have; if the DHCP-server already provided something it'll be suggested, but you can override it if need be. In the preparatory phase, you'll have decided on continuation of your current DNS schema, or starting a new one. Either way, put the chosen DNS suffix in and press &lt;enter&gt;. Next comes one '''VERY''' important question: what to use as root password? We cannot stress this enough: choose a SAFE password! Do NOT go for an easy-to-remember one, go for STRONG and SAFE. There are tools to help you generate strong passwords, like [http://www.pctools.com/guides/password/ this page]: use them! We strongly suggest 10 characters or more, including letters, mixed case, and numbers, so something like ''SuCRe4hecH'' (do NOT use this, generate your own!). Next, give the full name of the principal user of this server (your own, we assume), give the login-name (your given name, we assume), and a corresponding password. Again, use a SAFE password. As long as you don't make your principal user equivalent to root, you might go for a slightly weaker password (8 characters instead of 10), but we rather suggest you make the password just as strong (and different from!) the root password. After entering the details of these two users "root" and "you", we get to the server hardware. ==Partitioning== Now comes the question of partitioning, or how to divide the available disk space into chunks for the server to use. This is a tricky subject, because if you put all storage space into one partition, then some day a runaway process will fill up the entire disk with useless logs, and the system will crash. On the other hand, if you divvy up all space into little chunks, then some application is going to need space in one of those partitions where there is none, even though there may be plenty in other partitions. To minimize the chance of either problem occurring, we're going to use [http://tldp.org/HOWTO/LVM-HOWTO/whatisvolman.html Logical Volume Management (LVM2)] so that we can provision enough space to start our server, but keep some space in reserve to apply when needed, where it'll be needed. So, we at Saruman.biz have put together a recommended standard partitioning scheme. The basis (in accordance with the standard [[Debian directory structure]] is this: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Partition !style="background:#ffdead;"|MD !style="background:#ffdead;"|LVG !style="background:#ffdead;"|LV-name !style="background:#ffdead;"|Size <br> (physical machine) !style="background:#ffdead;"|Size (VM) !style="background:#ffdead;"|File System !style="background:#ffdead;"|Mount point |- | 1 | /dev/md0 | &nbsp; | &nbsp; | 100MiB | 100MiB | ext3 | /boot |- | 2 | /dev/md1 | &nbsp; | &nbsp; | 3GiB | 1GiB | ext3 | / |- | rowspan="8" valign="top" | 3 | rowspan="8" valign="top" | /dev/md2 | rowspan="8" valign="top" style="background:lightgrey"| system | style="background:lightgrey" | swap | 1GiB<ref name="swap">Rule of thumb: twice the size of the machine's RAM, but no less than 256MiB and no more than 2GiB</ref> | 256MiB<ref name="swap"/> | swap | &nbsp; |- | style="background:lightgrey" | var | 1GiB | 512MiB | ext3 | /var |- | style="background:lightgrey" | varlog | 1GiB | 512MiB | ext3 | /var/log |- | style="background:lightgrey" | appslog | 3GiB | -<ref>Yes, we think a separate ''appslog'' is a very good idea, but when creating a minimal VM, we have to save disk space ''somewhere''...</ref> | ext3 | /var/appslog |- | style="background:lightgrey" | home | 1GiB<ref name="home">Note that this heavily depends on the purpose of the machine; if it is not to house any users, then (almost) no space is needed for /home. But on the other hand if e.g. a virtual user is to be used for keeping mailstores, or other service users need home space, then /home needs to be big enough for that.</ref> | 512MiB<ref name="home"/> | ext3 | /home |- | style="background:lightgrey" | usr | 3GiB | 3GiB | ext3 | /usr |- | style="background:lightgrey" | tmp | 1GiB | 512MiB | ext3 | /tmp |- | style="background:lightgrey" | opt | 1GiB | - | ext3 | /opt |- ! colspan="4" style="text-align:right"| Total ! 18.1GiB ! 6.9GiB ! colspan="2" | |- |} As you can see, the partition table works as follows: we assume that we wind up with 3 partitions, either on three separate software RAID arrays (''md0'' through ''md2'') or on one single hardware RAID array (in which case the 2nd column ''MD'' does not apply). The size of the partitions depends on your machine's make: for standard physical machines the 5th column does sensible suggestions, even though you could choose to have different sizes and of course different divisions altogether. If your machine happens to be a virtual one, running inside a [http://www.vmware.com/products/server/ VMware Server] or [http://www.vmware.com/products/vi/esx/ VMware ESX host], or the like, then you might want to start out with more modest partitions. The same holds for small servers that must run off Flash drives. Anyways, we're now at the Debian installation screen that lets us partition our disks. We're ''not'' going to use any of the "guided" partitioning options, we go for "manual". Choosing that brings us to a screen showing all drives that the installation routine has detected, and all partitions on those drives that the installer can "see". We're going to do some assuming here once more: let's assume the drive(s) on which you want to install are visible, and are empty (containing no other partitions). <references/> ===Software RAID partitioning=== If you're to use software RAID, you now have to select the free space on the first drive, press &lt;enter&gt;, and then tell what you want to do with the free space: create a new partition, tell which size you want it to be (see table above), give the type of partition (primary), and give where on the disk it'll sit (the beginning). Next, a screen comes up that details how the partition you're requesting will be created. Here we make some changes: under "use as" we're going to select "physical volume for RAID". This clears all the other options in this screen, except for the "bootable" flag, which must be "on" for the first partition that we'll mount as ''/boot''. Now select "Done setting up the partition". Next, go to the free space on the second disk, and do ''exactly'' the same, to create an identical physical volume for RAID - if it's the first partition, select the "bootable" flag as well (we'll want to be able to boot from this second disk if the first disk fails, right?). Then go back to the rest of the free space on the first disk, make the second physical volume for RAID, duplicate it on the second disk. Then, go back to the rest of the free space on the first disk, make the third physical volume for RAID, and again duplicate it on the second disk. If you now go back to the "partition disks" overview, you'll see all the partitions you've specified listed on their respective disks. But at the top an extra option has appeared, called "configure software RAID". When you now select this option, the installer will ask if it may write the changes you've made to disk. This actually creates the partition tables on the disks. Now you can create RAID devices. The RAID levels that Debian 6.0 offer are 0 (striping), 1 (mirroring), 5 (distributed redundancy), 6 (double distributed redundancy) ant 10 (striped mirrors). For your operating system disk pair, level 1 is the only sane choice. When selecting RAID 1, the installer asks how many active devices to use (2), how many spares (0), and then offers a selection screen where you can mark all members of the array. Select the first partition of both disks (presumably ''/dev/sda1'' and ''/dev/sdb1'') which should correspond to the 100MiB partitions you've created. Then create the other MD devices. Finally, choose &lt;finish&gt;. You'll drop back to the partitioner, but now the three created devices are available in the partitioner as "RAID1 device #0" etc. ===Hardware RAID partitioning=== Now, if you have hardware RAID, then on your first (boot) disk just make 3 partitions, in the following manner: Select the free space on the intended boot disk, press &lt;enter&gt;, select "create a new partition", and fill out the desired size (100MB). Type is primary, location is beginning of the disk, and in the details of the partition, we only need to change the Mount point to "/boot", and set the Bootable flag to "On". Then we're "Done setting up this partition". The second partition is made the same way, but the desired size is 3GB, the Mount point is "/", and the Bootable flag remains off. Again, we're "Done setting up this partition". The third partition is again a primary partition, it takes up the entire rest of the disk, but the type is not ext3, but "physical volume for LVM". Again, we're "Done setting up this partition". But now from the main partitioner screen, we can access "Configure the Logical Volume Manager". The installer asks if it can write out the choices made to the disk, and then enters the LVM setup screen, which begins with a summary explaining that you have one Free Physical Volume, and nothing more. ==Logical Volume creation== We now create a Volume Group (VG), which (in accordance to our partitioning standard) we'll call "system". In this VG, we'll add all Physical Volumes (being the one partition we've designated so in the previous step) using the space bar. To this end, in the volume group creation dialogue, we select that partition (''/dev/md2''). Note that all other selection choices are either unusable (unusable free space) or assigned to other purposes (/boot and /). Now we repeat the following process seven times: * select "Create Logical Volume" * select Volume Group "System" * give the LV Name (from the table, e.g. swap, var etc) * give the LV size (from the table, e.g. 1GB for swap etc) After this, we can select "Finish", the partitioner creates the seven LVs, and we're back at the partitioner screen, where there are now 7 extra "disks", with names such as ''LVM VG system, LV appslog - 3.0GB Linux device mapper (linear)''. Each of these "disks" has one block of empty space, which we now assign: seven times we repeat the following process: * select the unassigned chunk of empty space of an LV (e.g. ''appslog'') and press &lt;enter&gt;; * Change "Use as: do not use" into the desired filesystem (ext3 - only the LV "swap" gets as filesystem type "swap area"); * Change the mount point from "none" to the one corresponding with the name of the LV (note: the swap LV has no mountpoint; the appslog mountpoint must be entered manually as "/var/appslog" and varlog as "/var/log"); * If so desired, a label can be assigned to the partition (we usually don't); * select "Done setting up the partition". Note that sometimes, after creating and assigning the logical volumes, the installer has forgotten to mount the md0 and md1 partitions as /boot and /. In that case you'll have to reassign these partitions to these points in the filesystem. Once all this is done, we can look over the configuration once more, and then select "Finish partitioning and write changes to disk". A summary configuration screen will show, and we'll affirm with "yes" that these partitions can indeed be formatted. After some formatting screens flashing by (unless your partitions are particularly big, your system is particularly slow, or something goes wrong) the installation procedure continues. ==Base system setup== Now the Debian installer loads a base system. It will scan your installation CD/DVD, and ask if it should scan more CD/DVDs. We're going with "no" here. Then it will ask you how it can contact the Debian archives, in the dialogue "configure the package manager". For the NetInstall version of Debian, this is as good as mandatory. So here, we say "yes, use a Network Mirror", and in the following list select the country in which we are (in our case: the Netherlands), so the installer can present us with a number of network mirrors "close by". We select ftp.nl.debian.org. Next screen: should you be behind a proxy server, then it's possible to specify that here. And then the test: the system will say "scanning the mirror..." and try to contact the specified mirror. If it does not succeed, then there is either a network problem, a problem with this box's network card, or you've not specified the mirror or proxy correctly - so fix it. You'll know the network mirror has successfully been contacted when it's saying "Retrieving file 1 of 5". A number of files are retrieved, and the base system is set up. Somewhere early in this setup, the next dialogue appears - currently "configuring popularity-contest". Answer this question as you please. And then one of the last "big" questions: Software Selection. In this dialogue, you can easily select bundles of software to be installed. The choices are currently: * Graphical desktop environment * Web server * Print server * DNS server * File server * Mail server * SQL database * SSH server * Laptop * Standard system utilities (selected by default) We have to make a little confession here: we've never before used this option in the installer. In fact, we even deselect the Standard System, so as to minimize the number of software packages that the base installation of our server contains. This makes it more work to manually add packages later, but we feel it gives us more control and understanding of our systems. So if you're like us: deselect the "Standard system utilities" entry, and select Continue. The next dialogue handles the installation of the [http://www.gnu.org/software/grub/ ''grub'' bootloader]. Unless your disks weren't empty and you're attempting to make this system multiboot, you'll most likely get a question if you'll allow the installer to install ''grub'' into the boot sector of the first hard disk. We'll confirm with "Yes". After the installation of grub is completed, the CD-ROM is ejected, and the system is ready to reboot into Debian Squeeze. Remove the CD and select "Continue" ==Finishing up the installation== The system should reboot into Debian. This means you should see the following boot sequence: * your machine's standard POST messages * briefly a '''welcome to GRUB''' message * then, a blue grub menu on a black screen, with two entries: ** Debian GNU/Linux, with Linux 2.6.32-5-686 ** Debian GNU/Linux, with Linux 2.6.32-5-686 (recovery mode) * then, after a default (short!) time-out, the first grub option will go into effect, and the Linux kernel is started. Lots of cryptic messages in grey-on-black will scroll by, until the last few lines read: Debian GNU/Linux 6.0 easton2 tty1 easton2 login: '''_''' If your system does not reach this login, and/or some horrible error messages appear anywhere in this boot sequence, then you've got some extra work ahead. For now we'll assume you've reached the login prompt without problem. Log in as the principal user (try to avoid logging in as root! That's BAD practice!). Once logged in, save a copy of the boot messages using ''sudo dmesg > boot.txt'' or whatever you like. Then look through the boot messages, e.g. with ''vi -R boot.txt''. Furthermore, [[APT_and_aptitude | use Aptitude]] to make sure ''all'' your software is updated to the latest version. Done! Your base system is ready. You probably now want to [[essential system software | install essential software]], [[roll your own kernel]] and [[connect your server to the Internet]]. Furthermore, you might want to create a couple of [[aliases in every profile]] so that your favourite commands are always available. 62cf56be6f2305020ceef0676adf8b52ac76e1b1 0 1409 2719 2429 2012-03-12T20:29:30Z Saruman! 2 removing hw section wikitext text/x-wiki __TOC__ ==Hardware preparation== When installing a new server, you must begin with [[Server hardware prep|getting your server hardware right]]. Assuming you've built yourself a new server platform, you can install the operating system following the steps outlined below. Note: it is assumed the server is bare, and the hard disks are completely clean. If they are not, here's how to [[Cleaning a hard disk|clean]] them. ==Planning your network names== If your machine must become a part of an existing network, then it's almost certain that you already have a DNS domain in place; in that case: obtain the DNS suffix your machine will get (the DNS domain your machine will "belong" to). However, it's also possible that this machine is going to be the first machine in your new network, in which case the whole issue of DNS suffixes is wide open. If you need more information on DNS, go [[http://www.isc.org/sw/bind/arm95/Bv9ARM-all.html#id2564824 here]]. For now we'll assume you have (or will quickly obtain) a working knowledge of the DNS system. Here is our tip on choosing a DNS domain for your home network: * do '''not''' use a publicly registered domain name (e.g. "cocacola.com") for any machine that's not primarily intended to serve the public on the Internet; * for machines serving a private network, we urge you to use Top Level Domain name "lan" (to signify your machine is on a Local Area Network or LAN) * for the Domain Name itself, we suggest you use a level 2 name, like "saruman.lan", and not a level 3 name, like "mister.saruman.lan". This is only a short section on DNS, but remember that once a proper DNS system is in place, it's pretty much work to change it. At any rate, this section has most likely showed you that you need to put some thought into the DNS Domain Name design of your home network. OK, with this out of the way, we can get to installing the OS. ==Operating System installation== To install an Operating System (OS), it's kinda instrumental that you have one. Here, we're going to use [http://www.debian.org/intro/about Debian], the biggest [http://www.debian.org/intro/about#free Free] OS that we know of. Free stands for Freedom, but incidentally that Freedom also means it's gratis, an appealing aspect of Free. To get your own copy of Debian, go to their [http://www.debian.org/distrib/ download site] and obtain the latest [http://www.debian.org/releases/ Stable] image - in this wiki it's Debian 5.0, or "Lenny" as it's also known (although it wasn't stable at the time of writing this). Besides the choice which release of Debian you want to run, you also have to know for which platform you're downloading (in our case: either ''amd64'' or ''i386'' depending on your hardware platform) and what kind of install you wish - if you have a working, fast Internet connection available at the time of install, then we recommend getting the [[http://www.debian.org/CD/netinst/ netinst] CD image; it's a relatively small CD, that'll be able to get you going, but gets most of the software you'll need straight from the 'net at install time. In the example at hand we're installing on an AMD Athlon x2-based server, on which we wish to install 64-bits software. We'll download [http://cdimage.debian.org/cdimage/weekly-builds/amd64/iso-cd/debian-testing-amd64-CD-1.iso debian-testing-amd64-CD-1.iso], which is Lenny, not yet stable at the time of writing. Burn this to a CD-recordable and boot your prepared hardware platform from this CD. After booting from the CD, a friendly prompt invites you to indicate how you want to start installing (image 1). Your choices are listed under &lt;F3&gt;; we're going to use the standard Command Line installation, so we choose "install" and hit &lt;enter&gt;. {| class="wikitable" border="1" |- |We could easily use "Graphic install", in which case we'd have a nice fresh Graphical User Interface for our installation. ''We're'' not going to, because we're real men, and [http://isg.ee.ethz.ch/tools/realmen/ Real Men Don't Click]. Also, we've found that from the GUI it's hard to switch to a second console and then back. We could also go to the Advanced options (image 2), and opt for "Expert install" or "Graphical expert install" as installation method, because it gives a much finer grain of control; however we usually don't need that control, and can do without the barrage of extra questions that the "expert" installation method pose. |} After the Linux kernel finishes initializing the machine, a simple text-based installer appears (image 3) that immediately starts asking questions. Answer them according to your needs. Our example system uses the following choices: * Language: english * country: other &gt; Netherlands * keymap: American English (since we have a keyboard with US layout) Some installation software loads, and we get to the next phase: if you have multiple NICs in your machine (which we believe you ''should'' have!!), and if they're detected properly, then you're required to indicate which of the detected network interface cards (NIC) is going to be the "primary" NIC. {| class="wikitable" border="1" |- |Here, trouble could begin. If your machine has only network cards that are '''not''' supported, then you'll see '''no''' cards here - but then how are you going to do a NetInstall? A solution would be to (temporarily) install a NIC that ''is'' supported, like a cheap Realtek card, or an old 3Com 905 card. Then, when the whole system is installed, up and running, you could compile a new kernel that contains support for your actual NICs, and when these work, remove the temporary NIC. For now, we'll assume that at least one of your NICs is recognised properly by the Debian installation routine. |} Select the card that's connected and has (indirect) access to Internet (again: it should ''not'' be connected straight to the wild wild web, but sit safely behind a firewall, at least until we've installed our own firewall); if at all possible, let it be the NIC that'll be connected to your home network itself, on the ''inside'' of your server. Let's assume that this NIC is designated ''eth0'' by the Debian installation. This card will now be configured using DHCP, so if you're on a network with a DHCP-server, the network will work straight away. If it's not, you can either configure the network manually or fix your DHCP-server and connection between it and ''eth0''. Next is one of the hardest questions that any OS installation is going to ask you: what will be the host name of the system? You could change it at any time in the future, but with lots of hassle, so you better choose wisely. Here are our tips: * do '''not''' name your machine after the user that's going to use it, e.g. "bernie-pc" (at some time in the future, Bernie's machine will be moved to Alice, so then Alice is working on "bernie-pc" which makes the situation quite unclear); * do '''not''' name your machine after the department or workgroup that's using it most, e.g. "accounting-srv" (same reasoning); * do '''not''' name your machine after it's main function, e.g. "printserver" (at some time in the future, the main function is moved to another machine, and/or an alternative function will become the main function of the machine); * do '''not''' name your machine after it's location, e.g. "srv-boston" (at some time in the future, the box will be moved to another location); * do '''not''' name your machine after it's hardware configuration, e.g. "ibmx346" (at some time in the future, either another xSeries x346 will be wheeled in, or the machine will be upgraded to accomodate increased use or overcome hardware problems - your "ibmx346" could suddenly be running on an xSeries x3650). What we feel are safe names for ''any'' machine in your network are true names, perhaps linked to a common theme: names of European cities, names of movie characters, names of countries or holiday destinations et cetera. Immediately following comes the question of the Domain Name. This is about a DNS domain, so effectively the installation program is asking which DNS suffix the host name should have; if the DHCP-server already provided something it'll be suggested, but you can override it if need be. In the preparatory phase, you'll have decided on continuation of your current DNS schema, or starting a new one. Either way, put the chosen DNS suffix in and press &lt;enter&gt;. ==Partitioning== Next comes the question of partitioning, or how to divide the available disk space into chunks for the server to use. This is a tricky subject, because if you put all storage space into one partition, then some day a runaway process will fill up the entire disk with useless logs, and the system will crash. On the other hand, if you divvy up all space into little chunks, then some application is going to need space in one of those partitions where there is none, even though there may be plenty in other partitions. To prevent both problems from occuring, we're going to use [http://tldp.org/HOWTO/LVM-HOWTO/whatisvolman.html Logical Volume Management (LVM)] so that we can provision enough space to start our server, but keep some space in reserve to apply when needed, where it'll be needed. So, we at Saruman.biz have put together a recommended standard partitioning scheme. The basis (in accordance with the standard [[Debian directory structure]]is this: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Partition !style="background:#ffdead;"|MD !style="background:#ffdead;"|LVG !style="background:#ffdead;"|LV-name !style="background:#ffdead;"|Size <br> (physical machine) !style="background:#ffdead;"|Size (VM) !style="background:#ffdead;"|File System !style="background:#ffdead;"|Mount point |- | 1 | /dev/md0 | &nbsp; | &nbsp; | 100MiB | 100MiB | ext3 | /boot |- | 2 | /dev/md1 | &nbsp; | &nbsp; | 3GiB | 1GiB | ext3 | / |- | rowspan="8" valign="top" | 3 | rowspan="8" valign="top" | /dev/md2 | rowspan="8" valign="top" style="background:lightgrey"| system | style="background:lightgrey" | swap | 1GiB<ref name="swap">Rule of thumb: twice the size of the machine's RAM, but no less than 256MiB and no more than 2GiB</ref> | 256MiB<ref name="swap"/> | swap | &nbsp; |- | style="background:lightgrey" | var | 1GiB | 512MiB | ext3 | /var |- | style="background:lightgrey" | varlog | 1GiB | 512MiB | ext3 | /var/log |- | style="background:lightgrey" | appslog | 3GiB | -<ref>Yes, we think a separate ''appslog'' is a very good idea, but when creating a minimal VM, we have to save disk space ''somewhere''...</ref> | ext3 | /var/appslog |- | style="background:lightgrey" | home | 1GiB<ref name="home">Note that this heavily depends on the purpose of the machine; if it is not to house any users, then (almost) no space is needed for /home. But on the other hand if e.g. a virtual user is to be used for keeping mailstores, or other service users need home space, then /home needs to be big enough for that.</ref> | 512MiB<ref name="home"/> | ext3 | /home |- | style="background:lightgrey" | usr | 3GiB | 3GiB | ext3 | /usr |- | style="background:lightgrey" | tmp | 1GiB | 512MiB | ext3 | /tmp |- | style="background:lightgrey" | opt | 1GiB | - | ext3 | /opt |- ! colspan="4" style="text-align:right"| Total ! 18.1GiB ! 6.9GiB ! colspan="2" | |- |} As you can see, the partition table works as follows: we assume that we wind up with 3 partitions, either on three separate software RAID arrays (''md0'' through ''md2'') or on one single hardware RAID array (in which case the 2nd column ''MD'' does not apply). The size of the partitions depends on your machine's make: for standard physical machines the 5th column does sensible suggestions, even though you could choose to have different sizes and of course different divisions altogether. If your machine happens to be a virtual one, running inside a [http://www.vmware.com/products/server/ VMware Server] or [http://www.vmware.com/products/vi/esx/ VMware ESX host], or the like, then you might want to start out with more modest partitions. The same holds for small servers that must run off Flash drives. Anyways, we're now at the Debian installation screen that lets us partition our disks. We're ''not'' going to use any of the "guided" partitionings, we go for "manual". Choosing that brings us to a screen showing all drives that the installation routine has detected, and all partitions on those drives that the installer can "see". We're going to do some assuming here once more: let's assume the drive(s) on which you want to install are visible, and are empty (containing no other partitions). <references/> ===Software RAID partitioning=== If you're to use software RAID, you now have to select the free space on the first drive, press &lt;enter&gt;, and then tell what you want to do with the free space: create a new partition, tell which size you want it to be (see table above), give the type of partition (primary), and give where on the disk it'll sit (the beginning). Next, a screen comes up that details how the partition you're requesting will be created. Here we make some changes: under "use as" we're going to select "physical volume for RAID". This clears all the other options in this screen, except for the "bootable" flag, which must be "on" for the first partition that we'll mount as ''/boot''. Now select "Done setting up the partition". Next, go to the free space on the second disk, and do ''exactly'' the same, to create an identical physical volume for RAID - if it's the first partition, select the "bootable" flag as well (we'll want to be able to boot from this second disk if the first disk fails, right?). Then go back to the rest of the free space on the first disk, make the second physical volume for RAID, duplicate it on the second disk. Then, go back to the rest of the free space on the first disk, make the third physical volume for RAID, and again duplicate it on the second disk. If you now go back to the "partition disks" overview, you'll see all the partitions you've specified listed on their respective disks. But at the top an extra option has appeared, called "configure software RAID". When you now select this option, the installer will ask if it may write the changes you've made to disk. This actually creates the partition tables on the disks. Note that at the end of configuring your partitions, an extra screen may appear (image 4): this asks if you care to identify which MD RAID devices must be started in order to be able to mount the root filesystem. Answering this question with a list of MD's like "md0 md1 md2" or simply "all" will let your server start the listed MD's very early in the boot sequence. ===Hardware RAID partitioning=== Now, if you have hardware RAID, then on your first (boot) disk just make 3 partitions, in the following manner: Select the free space on the intended boot disk, press &lt;enter&gt;, select "create a new partition", and fill out the desired size (100MB). Type is primary, location is beginning of the disk, and in the details of the partition, we only need to change the Mount point to "/boot", and set the Bootable flag to "On". Then we're "Done setting up this partition". The second partition is made the same way, but the desired size is 3GB, the Mount point is "/", and the Bootable flag remains off. Again, we're "Done setting up this partition". The third partition is again a primary partition, it takes up the entire rest of the disk, but the type is not ext3, but "physical volume for LVM". Again, we're "Done setting up this partition". But now from the main partitioner screen, we can access "Configure the Logical Volume Manager". The installer asks if it can write out the choices made to the disk, and then enters the LVM setup screen, which begins with a summary explaining that you have one Free Physical Volume, and nothing more. We now create a Volume Group (VG), which (in accordance to our partitioning standard) we'll call "system". In this VG, we'll add all Physical Volumes (being the one partition we've designated so in the previous step) using the space bar. Now we repeat the following process seven times: * select "Create Logical Volume" * select Volume Group "System" * give the LV Name (from the table, e.g. swap, var etc) * give the LV size (from the table, e.g. 1GB for swap etc) After this, we can select "Finish", the partitioner creates the seven LVs, and we're back at the partitioner screen, where there are now 7 extra "disks", with names such as ''LVM VG system, LV appslog - 3.2GB Linux device mapper''. Each of these "disks" has one block of empty space, which we now assign: seven times we repeat the following process: * select the unassigned chunk of empty space of an LV (e.g. appslog) and press &lt;enter&gt;; * Change "Use as: do not use" into the desired filesystem (ext3 - only the LV "swap" gets as filesystem type "swap area") * Change the mount point from "none" to the one corresponding with the name of the LV (note: the swap LV has no mountpoint; the appslog mountpoint must be entered manually as "/var/appslog") * If so desired, a label can be assigned to the partition (we usually don't) * select "Done setting up the partition" Once all this is done, we can look over the configuration once more, and then select "Finish partitioning and write changes to disk". A summary configuration screen will show, and we'll affirm with "yes" that these partitions can indeed be formatted. After some formatting screens flashing by (unless your partitions are particularly big, your system is particularly slow, or something goes wrong) the installation procedure continues. ==Final installer steps== Next comes one '''VERY''' important question: what to use as root password? We cannot stress this enough: choose a SAFE password! Do NOT go for an easy-to-remember one, go for STRONG and SAFE. There are tools to help you generate strong passwords, like [http://www.pctools.com/guides/password/ this page]: use them! We strongly suggest 10 characters or more, including letters, mixed case, and numbers, so something like ''SuCRe4hecH'' (do NOT use this, generate your own!). Next, give the full name of the principal user of this server (your own, we assume), give the login-name (your given name, we assume), and a corresponding password. Again, use a SAFE password. As long as you don't make your principal user equivalent to root, you might go for a slightly weaker password (8 characters instead of 10), but we rather suggest you make the password just as strong (and different from!) the root password. After entering the details of these two users "root" and "you", the Debian installer will ask you how it can contact the Debian archives, in the dialoge "configure the package manager". For the NetInstall version of Debian, this is as good as mandatory. So here, we say "yes, use a Network Mirror", and in the following list select the country in which we are (in our case: the Netherlands), so the installer can present us with a number of network mirrors "close by". We select ftp.nl.debian.org. Next screen: should you be behind a proxy server, then it's possible to specify that here. And then the test: the system will say "scanning the mirror..." and try to contact the specified mirror. If it does not succeed, then there is either a network problem, a problem with this box's network card, or you've not specified the mirror or proxy correctly - so fix it. You'll know the network mirror has succesfully been contacted when the next dialogue appears - currently "configuring popularity-contest". Answer this question as you please. And then one of the last "big" questions: Software Selection. In this dialogue, you can easily select bundles of software to be installed. The choices are currently: * Desktop environment * Web server * Print server * DNS server * File server * Mail server * SQL database * Laptop * Standard system (selected by default) We have to make a little confession here: we've never before used this option in the installer. In fact, we even deselect the Standard System, so as to minimize the number of software packages that the base installation of our server contains. This makes it more work to manually add packages later, but we feel it gives us more control and understanding of our systems. So if you are like us: deselect the Standard System entry, and select Continue. The next dialogue handles the installation of the [http://www.gnu.org/software/grub/ ''grub'' bootloader]. Unless your disks weren't empty and you're attempting to make this system multiboot, you'll most likely get a question if you'll allow the installer to install ''grub'' into the boot sector of the first hard disk. We'll confirm with "Yes". After the installation of grub is completed, the CD-ROM is ejected, and the system is ready to reboot into Debian Etch. Remove the CD and select "Continue" ==Finishing up the installation== The system should reboot into Debian. This means you should see the following boot sequence: * your machine's standard POST messages * then, a blue grub menu on a black screen, with two entries: ** Debian GNU/Linux, kernel 2.6.&lt;something&gt; ** Debian GNU/Linux, kernel 2.6.&lt;something&gt (single-user mode); * then, after a default time-out, the first grub option will go into effect, and the Linux kernel is started. Lots of cryptic messages in grey-on-black will scroll by, until the last few lines read: "Debian GNU/Linux 4.0 &lt;hostname&gt; tty1" and "&lt;hostname&gt; login:" If your system does not reach this login, and/or some horrible error messages appear anywhere in this boot sequence, then you've got some extra work ahead. For now we'll assume you've reached the login prompt without problem. Log in as the principal user (try to avoid logging in as root! That's BAD practice!). Once logged in, save a copy of the boot messages using ''sudo dmesg > boot.txt'' or whatever you like. Then look through the boot messages, e.g. with ''vi -R boot.txt''. Furthermore, [[APT_and_aptitude | use Aptitude]] to make sure ''all'' your software is updated to the latest version. Done! Your base system is ready. You probably now want to [[essential system software | install essential software]], [[roll your own kernel]] and [[connect your server to the Internet]]. Furthermore, you might want to create a couple of [[aliases in every profile]] so that your favorite commands are always available. f0f6c8adba82d6707e25ad27d0dfa7cbd6f0874f 0 1620 2724 2701 2012-04-01T14:58:54Z Saruman! 2 /* Adding schemas */ new wikitext text/x-wiki Note: if you need information on the OpenLDAP version from Debian 5.0, see this page: [[OpenLDAP 2.4.11]] == OpenLDAP installation== Note: we're going to install OpenLDAP on our server as [http://www.openldap.org/doc/admin24/config.html#Local%20Directory%20Service the local directory service], without replication, referrals or other advanced features. Under Debian Squeeze, this is OpenLDAP 2.4.23. ===Standard installation=== Installing OpenLDAP on your Debian server is ridiculously simple. Just make sure your server is up-to-date (''sudo apt-get update'' followed by ''sudo apt-get upgrade''), and then install the two main components for your OpenLDAP server. First off: the LDAP client and utilities sudo apt-get install ldap-utils This will result in the installation of as much as 8 different packages (''ldap-utils'', ''libgcrypt11'', ''libgnutls26'', ''libgpg-error0'', ''libldap-2.4-2'', ''libsasl2-2'', ''libsasl2-modules'', and ''libtasn1-3''). Next the main component of an LDAP server installation, the stand-alone LDAP daemon "slapd" sudo apt-get install slapd This may also install up to 8 packages (''slapd'', ''libltdl7'', ''libperl5.10'', ''libslp1'', ''odbcinst'', ''odbcinst1debian2'', ''psmisc'' and ''unixodbc''). The Debian configuration script will ask you for only one single thing: an administrator password. As always: generate a strong password! After you've provided the password, the LDAP database is created with the administrator name "admin" and as a base directory, something based on your DNS name. Suppose your internal domain is "amber.lan", then the script will generate ''suffix "dc=amber,dc=lan"''<ref>Should you see a third, empty, domain component (''dc='') then this is caused by a trailing dot in your particular DNS name: the DNS root. You might have specified your domain as "amber.lan.". You ''should'' change your domain name to a name without the DNS root, and you ''must'' regenerate your LDAP directory.</ref>. The above method of configuring yields you an LDAP database with only two objects in it. Suppose your DNS name is "easton2.amber.lan", then the two objects are: * a single Organization (o="amber.lan") with Distinguished Name dn="dc=amber,dc=lan" * a single administrator with Common Name cn="admin", and dn="cn=admin,dc=amber,dc=lan" Note, however, that there's ''also'' a second LDAP database, "cn=config", which on your server is located under ''/etc/ldap/slapd.d''. We'll cover what's in it further on. <references/> ===Testing the installation=== After installation of the package, it should automatically have been started, and should now be operational. This can be checked with a utility like ''nmap'': root@easton2:~# '''nmap -p 389 localhost''' Starting Nmap 5.00 ( <nowiki>http://nmap.org</nowiki> ) at 2011-04-13 21:19 CEST Interesting ports on localhost (127.0.0.1): PORT STATE SERVICE 389/tcp open ldap Nmap done: 1 IP address (1 host up) scanned in 0.40 seconds root@easton2:~#'''_''' Another way to test if the LDAP server is functional, is by querying it with the ''ldapsearch'' utility, part of the package ''ldap-utils''. Let's see if we can find the naming context of the LDAP server: root@easton2:~# '''ldapsearch -x -b <nowiki>''</nowiki> -s base '(objectclass=*)' namingContexts''' # extended LDIF # # LDAPv3 # base <> with scope baseObject # filter: (objectclass=*) # requesting: namingContexts # # dn: namingContexts: dc=amber,dc=lan # search result search: 2 result: 0 Success # numResponses: 2 # numEntries: 1 root@easton2:~# '''_''' With this command, we do a search using * basic authentication (instead of one encrypted with SASL), * searching within the LDAP tree from base <nowiki>''</nowiki> (meaning the absolute root of the tree), * looking for base object only (instead of a one-level search, a subtree search, or a children-search), * filtering for objects of any class, * asking for the naming context of the result. The output shows that the server responds; two objects have been considered, but none match the filter (that the object should have an objectClass). Let's now do the same but with authentication, to see if we can bind to the LDAP server. We'll first use an incorrect password, then the correct one: root@easton2:~# '''ldapsearch -W -D "cn=admin,dc=amber,dc=lan"''' Enter LDAP Password: ldap_bind: Invalid credentials (49) root@easton2:~# '''ldapsearch -W -D "cn=admin,dc=amber,dc=lan"''' Enter LDAP Password: # extended LDIF # # LDAPv3 # base <> (default) with scope subtree # filter: (objectclass=*) # requesting: ALL # # search result search: 2 result: 32 No such object # numResponses: 1 root@easton2:~# '''_''' Finally, you could simply install and run a graphical management tool for LDAP servers, like [http://directory.apache.org/studio/ Apache Directory Studio]. Note however that if this check fails, then this could also mean problems with firewalls, network connections et cetera. ===Post-install reconfiguration=== Since the default configuration with the server's DNS domain as LDAP base might not always be the most convenient configuration, you could run the configuration again using ''dpkg-reconfigure slapd''. However, following this procedure is '''only''' necessary if you want to change any of the default installation values like the backend database type or DNS domain name; things like the organization name can be edited with other means, as will be shown later on. To be able to reconfigure the LDAP service, you can run the reconfiguration command ''sudo dpkg-reconfigure slapd''. Contrary to some older versions of Debian, you do not need to manually stop the ''slapd'' daemon, and you don't need to manually remove the old configuration or database (in fact, if you do, then the ''slapd'' package will break, so you cannot easily remove it with APT tools). Interestingly enough, this reconfiguration asks you many ''more'' questions. The answers could look like this: omit OpenLDAP config: no DNS domain name: saruman.biz Organization name: Saruman Administrator passwd: wEt3udes Database backend: HDB DB remove after purge: yes Move old DB: yes Allow LDAPv2: no As you can see, the reconfiguration yields much more configuration options than plain installation - although really you'll probably answer most questions with their default values anyway. The above method of configuring yields you an LDAP database with only two objects in it: * a single Organization (o="Saruman") with Distinguished Name dn="dc=saruman,dc=biz" * a single administrator with Common Name cn="admin", and dn="cn=admin,dc=saruman,dc=biz" Also note that the reconfiguration creates a backup of the "old" LDAP database in a directory with a name like ''/var/backup/unknown-2.4.23-7.ldapdb''; if you just reconfigured after installation, then you probably don't need this backup, so you can remove it. The database that your OpenLDAP server uses is a standard Berkeley DB (BDB/HDB) database. Now we most likely will require some other databases as well in our server setup, something modern like PostgreSQL or MySQL - so why don't we configure our OpenLDAP to use this same database as well? For the answer, see [http://www.openldap.org/doc/admin24/intro.html#LDAP%20vs%20RDBMS here] - in short, the LDAP tree structure does not lend itself very well to inclusion in a modern relational database. Thus, we advise to stick with the Berkeley database provided with OpenLDAP. Now, for the database backend, we have the choice between two almost identical flavours: * the ''bdb'' backend used to be the recommended primary backend for a normal slapd database. It uses the Oracle Berkeley DB package, referred to as ''BDB'', to store data. It makes extensive use of indexing and caching to speed data access. * the ''hdb'' backend is a variant of the ''bdb'' backend that uses a hierarchical database layout which supports subtree renames. It is otherwise identical to the ''bdb'' behavior, and all the same configuration options apply. In Debian 6.0 "Squeeze" with OpenLDAP 2.4.23, HDB is the default backend. ==OpenLDAP server configuration== <small>(text from http://www.rjsystems.nl/en/2100-d6-openldap-provider.php)</small> As of OpenLDAP 2.4.23-3, the ''slapd'' runtime configuration is fully LDAP-enabled. The default is to manage it using the standard LDAP operations with data in LDIF. The old ''slapd.conf'' format is still supported, but since that file must now be converted to the new ''slapd-config'' format to allow runtime changes to be saved, it seems likely that the developers will eventually phase it out. Therefore, we'll focus only on the new configuration method, the main advantage of which is that any changes made are immediately active, so it is no longer necessary to restart ''slapd'' after making configuration changes. The new configuration format uses a slapd backend database that is found in the ''/etc/ldap/slapd.d/'' directory. The configuration is stored as a special LDAP directory with a predefined schema and DIT, the root of which is called ''cn=config''. If you go look there, you'll find that most parts of this LDAP directory consist of editable flat files. ===Check the current LDAP configuration=== From the command line, there really are several ways to check the current LDAP configuration: * from the server itself, you can use the trusty ''ldapsearch'' command, running under root: this'll authenticate with user ID 0. Filtering only for distinguished names: root@easton2:/etc/ldap# '''ldapsearch -LLL -Y EXTERNAL -H ldapi:/// -b cn=config dn''' SASL/EXTERNAL authentication started SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth SASL SSF: 0 dn: cn=config dn: cn=module{0},cn=config dn: cn=schema,cn=config dn: cn={0}core,cn=schema,cn=config dn: cn={1}cosine,cn=schema,cn=config dn: cn={2}nis,cn=schema,cn=config dn: cn={3}inetorgperson,cn=schema,cn=config dn: olcBackend={0}hdb,cn=config dn: olcDatabase={-1}frontend,cn=config dn: olcDatabase={0}config,cn=config dn: olcDatabase={1}hdb,cn=config root@easton2:/etc/ldap# '''_''' * to get an idea of what the ''cn=config'' database looks like ''within LDAP itself'', you can run this command: root@easton2:/etc/ldap# '''slapcat -b cn=config''' dn: cn=config objectClass: olcGlobal cn: config olcArgsFile: /var/run/slapd/slapd.args olcLogLevel: none olcPidFile: /var/run/slapd/slapd.pid olcToolThreads: 1 '''''(more LDIF texts)''''' entryUUID: f2a8f568-fa40-102f-8b9d-5d4cbccf32a9 creatorsName: cn=admin,cn=config createTimestamp: 20110413174103Z entryCSN: 20110413174103.641065Z#000000#000#000000 modifiersName: cn=admin,cn=config modifyTimestamp: 20110413174103Z root@easton2:/etc/ldap# '''_''' : As you can see, this generates a pretty large LDIF dump of the contents of the ''cn=config'' directory. Much of it consists of schema information. The LDAP configuration directives are attributes of the directory entries (objects) and most them start with the prefix "olc" ('''O'''pen'''L'''DAP '''C'''onfiguration). Also, some of the objects have names with numbers between curly brackets. This is to compensate for the fact that LDAP databases do not store their contents in any particular order; they are inherently unordered. The numbers constitute a numeric index to ensure a consistent order in the configuration database and thereby preserve all ordering dependencies. The index numbers, however, are generated automatically in the order they are created and usually do not have to be provided. * you can see the configuration by browsing through all the plain-text flat files in ''/etc/ldap/slapd.d/'' and its subdirectories. Note that by default there is no way to do this remotely. If you'd like to browse this configuration using a GUI tool like [http://directory.apache.org/studio/ apache directory studio], don't bother. Debian sets the ''cn=config'' part of the database with a root user of ''cn=admin,cn=config'', but without a password, so you cannot bind to the ''cn=config'' database as anything else than the local root user. Thus you cannot access the ''cn=config'' database by GUI. ===Adding or modifying the cn=config admin password=== To add a password to the config RootDN, we first must generate one; for this we can use the ''slappasswd'' command. By default it'll create an SSHA password, but by specifying MD5 as hash (using '' -h {MD5}'') it will create an MD5 encrypted password. The command interactively asks you for the password, and won't show you what you've typed, so be precise: root@easton2:/etc/ldap# '''slappasswd -h {MD5}''' New password: Re-enter new password: {MD5}d5axCh6gYGjhfK4PGs09us== root@easton2:/etc/ldap# '''_''' Now we determine the DN (Distinguished Name) for the database that contains the RootDN password. We'll also check if there isn't a password in place already. To do this we used the following LDAP search command. root@easton2:/etc/ldap# '''ldapsearch -LLL -Y EXTERNAL -H ldapi:/// -b cn=config olcRootDN=cn=admin,cn=config dn olcRootDN olcRootPW''' SASL/EXTERNAL authentication started SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth SASL SSF: 0 dn: olcDatabase={0}config,cn=config olcRootDN: cn=admin,cn=config root@easton2:/etc/ldap# '''_''' Note the olcDatabase line, as it's the result we were looking for; it'll be needed for the ''ldapmodify'' command. Furthermore, note the absence of an olcRootPW entry; this is the starting point for a Debian OpenLDAP server.<br> Now we can stick in a new password. If no password is present, you can use this interactive procedure: root@easton2:/etc/ldap# '''ldapmodify -Y EXTERNAL -H ldapi:///''' SASL/EXTERNAL authentication started SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth SASL SSF: 0 '''dn: olcDatabase={0}config,cn=config''' '''add: olcRootPW''' '''olcRootPW: {MD5}d5axCh6gYGjhfK4PGs09us==''' modifying entry "olcDatabase={0}config,cn=config" root@easton2:/etc/ldap# '''_''' Note the following points: * we use the olcDatabase location as found with the previous ''ldapsearch'' command; * we input the MD5 password that we've generated previously; * as soon as you put in an empty line, the entry gets added; * you have to use CTRL-D to end this interactive mode; * if a password was already in place, we could still use the above, but we'd interactively feed the second line as '''replace: olcRootPW'''. We could also put the password in an ldif file, and feed that to the server. To this end, we'd create an ldif file with the following content: dn: olcDatabase={0}config,cn=config changetype: modify add: olcRootPW olcRootPW: {MD5}d5axCh6gYGjhfK4PGs09us== If this file is called ''addpassword.ldif'' and is created in ''/tmp'', then the addition can be executed using root@easton2:/etc/ldap# '''ldapmodify -Y EXTERNAL -H ldapi:/// -f /tmp/addpassword.ldif''' SASL/EXTERNAL authentication started SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth SASL SSF: 0 modifying entry "olcDatabase={0}config,cn=config" root@easton2:/tmp# '''_''' ==Adding or modifying (configuration) information== The simple way of changing anything in the database goes like this: ===Method 1: interactive CLI tool=== As an example, let's add an index to the configuration. We'll start by seeing which indices already exist, then interactively add two indices. Finally, we check that the indices are there: root@easton2:/tmp# '''ldapsearch -LLLQY EXTERNAL -H ldapi:/// -b cn=config olcDatabase={1}hdb olcDbIndex''' dn: olcDatabase={1}hdb,cn=config olcDbIndex: objectClass eq root@easton2:/tmp# '''ldapmodify -Y EXTERNAL -H ldapi:///''' SASL/EXTERNAL authentication started SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth SASL SSF: 0 '''dn: olcDatabase={1}hdb,cn=config''' '''add: olcDbIndex''' '''olcDbIndex: cn eq''' '''olcDbIndex: uid eq''' modifying entry "olcDatabase={1}hdb,cn=config" root@easton2:/tmp# '''ldapsearch -LLLQY EXTERNAL -H ldapi:/// -b cn=config olcDatabase={1}hdb olcDbIndex''' dn: olcDatabase={1}hdb,cn=config olcDbIndex: objectClass eq olcDbIndex: cn eq olcDbIndex: uid eq root@easton2:/tmp# '''_''' (And ofcourse we press ctrl-D to end interactive mode).<br>Note: we can /modify multiple attributes in one stanza, but we can also add multiple objects/attributes in one ''ldapmodify'' session: * If you input an empty line, you can start another ''dn:'' line, and perform another action; * If you input a minus sign by itself on a line, then OpenLDAP will assume you'll be performing another action in/on the same object. Modifying works almost the same; we only need keyword ''replace'' instead of ''add'': root@easton2:/tmp# '''ldapsearch -LLLQY EXTERNAL -H ldapi:/// -b cn=config -s base olcLogLevel''' dn: cn=config olcLogLevel: none root@easton2:/tmp# '''ldapmodify -Y EXTERNAL -H ldapi:///''' SASL/EXTERNAL authentication started SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth SASL SSF: 0 '''dn: cn=config''' '''changetype: modify''' '''replace: olcLogLevel''' '''olcLogLevel: stats''' modifying entry "cn=config" root@easton2:/tmp# '''ldapsearch -LLLQY EXTERNAL -H ldapi:/// -b cn=config -s base olcLogLevel''' dn: cn=config olcLogLevel: stats root@easton2:/tmp# '''_''' Note the ''-s base'' option that limits the search for the ''olcLogLevel'' attribute to the ''cn=config'' container. Deleting information from an LDAP tree rarely ever happens, because once an attribute is used for anything, you aren't allowed to delete it, only modify it. However, if you want to delete anything, you can use the changetype "modify" with action "delete": root@easton2:/tmp# '''ldapmodify -Y EXTERNAL -H ldapi:///''' SASL/EXTERNAL authentication started SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth SASL SSF: 0 '''dn: olcDatabase={0}config,cn=config''' '''changetype: modify''' '''delete: olcRootPW''' modifying entry "olcDatabase={0}config,cn=config" root@easton2:/tmp# '''_''' ===Method 2: use an ldif file=== ===Method 3: use an LDAP browser=== With this method, you just use your LDAP browser for the addition or modification, according to its specific usage instructions. In the back, the tool will communicate with the LDAP server as you would in the previous methods. Note however, that this method relies on a bind account in the configuration database, which is a serious security risk. ==Adding schemas== A major task in LDAP maintenance is the addition of LDAP schemas. By default, only 4 schemas will be present in your LDAP server: ''core'', ''cosine'', ''nis'' and ''inetorgperson''. Any other schema, -- say, for Samba -- would need to be added. However, let's first check which schemas are already installed. Let's try two different methods, and see what they'll show out of the box: root@easton2:/tmp# '''ldapsearch -LLLQY EXTERNAL -H ldapi:/// -b cn=schema,cn=config "(objectClass=olcSchemaConfig)" dn''' dn: cn=schema,cn=config dn: cn={0}core,cn=schema,cn=config dn: cn={1}cosine,cn=schema,cn=config dn: cn={2}nis,cn=schema,cn=config dn: cn={3}inetorgperson,cn=schema,cn=config root@easton2:/tmp# '''ls -l /etc/ldap/slapd.d/cn=config/cn=schema''' total 40 -rw------- 1 openldap openldap 15474 Jun 13 17:39 cn={0}core.ldif -rw------- 1 openldap openldap 11308 Jun 13 17:39 cn={1}cosine.ldif -rw------- 1 openldap openldap 6438 Jun 13 17:39 cn={2}nis.ldif -rw------- 1 openldap openldap 2802 Jun 13 17:39 cn={3}inetorgperson.ldif root@easton2:/tmp# '''_''' To add a schema, you need a schema in LDIF format, which you can then add to the LDAP database using the ''ldapadd'' command. Suppose you have a schema file ''samba.schema'' which you've copied to the ''/etc/ldap/schema'' directory. You'd first have to convert this to a suitable LDIF file. This can be done using ''slaptest'', however ''slaptest'' requires access to the other schemas that your new schema is building on. So we now do this: * under ''/tmp'' we create a file ''schema_convert.conf'' with the following content:<br><pre>include /etc/ldap/schema/core.schema<br>include /etc/ldap/schema/cosine.schema<br>include /etc/ldap/schema/nis.schema<br>include /etc/ldap/schema/inetorgperson.schema<br>include /etc/ldap/schema/samba.schema</pre><br>Note that we're including the schema files of all the schemas that are already in our LDAP server, * now we create a working directory where ''slaptest'' can put our new LDIF file:<br><pre>mkdir /tmp/ldif_output</pre> 03900ecd58bf4c8b1f012167de029ba35cb7e7f3 2725 2724 2012-04-01T14:59:45Z Saruman! 2 /* Adding schemas */ layout wikitext text/x-wiki Note: if you need information on the OpenLDAP version from Debian 5.0, see this page: [[OpenLDAP 2.4.11]] == OpenLDAP installation== Note: we're going to install OpenLDAP on our server as [http://www.openldap.org/doc/admin24/config.html#Local%20Directory%20Service the local directory service], without replication, referrals or other advanced features. Under Debian Squeeze, this is OpenLDAP 2.4.23. ===Standard installation=== Installing OpenLDAP on your Debian server is ridiculously simple. Just make sure your server is up-to-date (''sudo apt-get update'' followed by ''sudo apt-get upgrade''), and then install the two main components for your OpenLDAP server. First off: the LDAP client and utilities sudo apt-get install ldap-utils This will result in the installation of as much as 8 different packages (''ldap-utils'', ''libgcrypt11'', ''libgnutls26'', ''libgpg-error0'', ''libldap-2.4-2'', ''libsasl2-2'', ''libsasl2-modules'', and ''libtasn1-3''). Next the main component of an LDAP server installation, the stand-alone LDAP daemon "slapd" sudo apt-get install slapd This may also install up to 8 packages (''slapd'', ''libltdl7'', ''libperl5.10'', ''libslp1'', ''odbcinst'', ''odbcinst1debian2'', ''psmisc'' and ''unixodbc''). The Debian configuration script will ask you for only one single thing: an administrator password. As always: generate a strong password! After you've provided the password, the LDAP database is created with the administrator name "admin" and as a base directory, something based on your DNS name. Suppose your internal domain is "amber.lan", then the script will generate ''suffix "dc=amber,dc=lan"''<ref>Should you see a third, empty, domain component (''dc='') then this is caused by a trailing dot in your particular DNS name: the DNS root. You might have specified your domain as "amber.lan.". You ''should'' change your domain name to a name without the DNS root, and you ''must'' regenerate your LDAP directory.</ref>. The above method of configuring yields you an LDAP database with only two objects in it. Suppose your DNS name is "easton2.amber.lan", then the two objects are: * a single Organization (o="amber.lan") with Distinguished Name dn="dc=amber,dc=lan" * a single administrator with Common Name cn="admin", and dn="cn=admin,dc=amber,dc=lan" Note, however, that there's ''also'' a second LDAP database, "cn=config", which on your server is located under ''/etc/ldap/slapd.d''. We'll cover what's in it further on. <references/> ===Testing the installation=== After installation of the package, it should automatically have been started, and should now be operational. This can be checked with a utility like ''nmap'': root@easton2:~# '''nmap -p 389 localhost''' Starting Nmap 5.00 ( <nowiki>http://nmap.org</nowiki> ) at 2011-04-13 21:19 CEST Interesting ports on localhost (127.0.0.1): PORT STATE SERVICE 389/tcp open ldap Nmap done: 1 IP address (1 host up) scanned in 0.40 seconds root@easton2:~#'''_''' Another way to test if the LDAP server is functional, is by querying it with the ''ldapsearch'' utility, part of the package ''ldap-utils''. Let's see if we can find the naming context of the LDAP server: root@easton2:~# '''ldapsearch -x -b <nowiki>''</nowiki> -s base '(objectclass=*)' namingContexts''' # extended LDIF # # LDAPv3 # base <> with scope baseObject # filter: (objectclass=*) # requesting: namingContexts # # dn: namingContexts: dc=amber,dc=lan # search result search: 2 result: 0 Success # numResponses: 2 # numEntries: 1 root@easton2:~# '''_''' With this command, we do a search using * basic authentication (instead of one encrypted with SASL), * searching within the LDAP tree from base <nowiki>''</nowiki> (meaning the absolute root of the tree), * looking for base object only (instead of a one-level search, a subtree search, or a children-search), * filtering for objects of any class, * asking for the naming context of the result. The output shows that the server responds; two objects have been considered, but none match the filter (that the object should have an objectClass). Let's now do the same but with authentication, to see if we can bind to the LDAP server. We'll first use an incorrect password, then the correct one: root@easton2:~# '''ldapsearch -W -D "cn=admin,dc=amber,dc=lan"''' Enter LDAP Password: ldap_bind: Invalid credentials (49) root@easton2:~# '''ldapsearch -W -D "cn=admin,dc=amber,dc=lan"''' Enter LDAP Password: # extended LDIF # # LDAPv3 # base <> (default) with scope subtree # filter: (objectclass=*) # requesting: ALL # # search result search: 2 result: 32 No such object # numResponses: 1 root@easton2:~# '''_''' Finally, you could simply install and run a graphical management tool for LDAP servers, like [http://directory.apache.org/studio/ Apache Directory Studio]. Note however that if this check fails, then this could also mean problems with firewalls, network connections et cetera. ===Post-install reconfiguration=== Since the default configuration with the server's DNS domain as LDAP base might not always be the most convenient configuration, you could run the configuration again using ''dpkg-reconfigure slapd''. However, following this procedure is '''only''' necessary if you want to change any of the default installation values like the backend database type or DNS domain name; things like the organization name can be edited with other means, as will be shown later on. To be able to reconfigure the LDAP service, you can run the reconfiguration command ''sudo dpkg-reconfigure slapd''. Contrary to some older versions of Debian, you do not need to manually stop the ''slapd'' daemon, and you don't need to manually remove the old configuration or database (in fact, if you do, then the ''slapd'' package will break, so you cannot easily remove it with APT tools). Interestingly enough, this reconfiguration asks you many ''more'' questions. The answers could look like this: omit OpenLDAP config: no DNS domain name: saruman.biz Organization name: Saruman Administrator passwd: wEt3udes Database backend: HDB DB remove after purge: yes Move old DB: yes Allow LDAPv2: no As you can see, the reconfiguration yields much more configuration options than plain installation - although really you'll probably answer most questions with their default values anyway. The above method of configuring yields you an LDAP database with only two objects in it: * a single Organization (o="Saruman") with Distinguished Name dn="dc=saruman,dc=biz" * a single administrator with Common Name cn="admin", and dn="cn=admin,dc=saruman,dc=biz" Also note that the reconfiguration creates a backup of the "old" LDAP database in a directory with a name like ''/var/backup/unknown-2.4.23-7.ldapdb''; if you just reconfigured after installation, then you probably don't need this backup, so you can remove it. The database that your OpenLDAP server uses is a standard Berkeley DB (BDB/HDB) database. Now we most likely will require some other databases as well in our server setup, something modern like PostgreSQL or MySQL - so why don't we configure our OpenLDAP to use this same database as well? For the answer, see [http://www.openldap.org/doc/admin24/intro.html#LDAP%20vs%20RDBMS here] - in short, the LDAP tree structure does not lend itself very well to inclusion in a modern relational database. Thus, we advise to stick with the Berkeley database provided with OpenLDAP. Now, for the database backend, we have the choice between two almost identical flavours: * the ''bdb'' backend used to be the recommended primary backend for a normal slapd database. It uses the Oracle Berkeley DB package, referred to as ''BDB'', to store data. It makes extensive use of indexing and caching to speed data access. * the ''hdb'' backend is a variant of the ''bdb'' backend that uses a hierarchical database layout which supports subtree renames. It is otherwise identical to the ''bdb'' behavior, and all the same configuration options apply. In Debian 6.0 "Squeeze" with OpenLDAP 2.4.23, HDB is the default backend. ==OpenLDAP server configuration== <small>(text from http://www.rjsystems.nl/en/2100-d6-openldap-provider.php)</small> As of OpenLDAP 2.4.23-3, the ''slapd'' runtime configuration is fully LDAP-enabled. The default is to manage it using the standard LDAP operations with data in LDIF. The old ''slapd.conf'' format is still supported, but since that file must now be converted to the new ''slapd-config'' format to allow runtime changes to be saved, it seems likely that the developers will eventually phase it out. Therefore, we'll focus only on the new configuration method, the main advantage of which is that any changes made are immediately active, so it is no longer necessary to restart ''slapd'' after making configuration changes. The new configuration format uses a slapd backend database that is found in the ''/etc/ldap/slapd.d/'' directory. The configuration is stored as a special LDAP directory with a predefined schema and DIT, the root of which is called ''cn=config''. If you go look there, you'll find that most parts of this LDAP directory consist of editable flat files. ===Check the current LDAP configuration=== From the command line, there really are several ways to check the current LDAP configuration: * from the server itself, you can use the trusty ''ldapsearch'' command, running under root: this'll authenticate with user ID 0. Filtering only for distinguished names: root@easton2:/etc/ldap# '''ldapsearch -LLL -Y EXTERNAL -H ldapi:/// -b cn=config dn''' SASL/EXTERNAL authentication started SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth SASL SSF: 0 dn: cn=config dn: cn=module{0},cn=config dn: cn=schema,cn=config dn: cn={0}core,cn=schema,cn=config dn: cn={1}cosine,cn=schema,cn=config dn: cn={2}nis,cn=schema,cn=config dn: cn={3}inetorgperson,cn=schema,cn=config dn: olcBackend={0}hdb,cn=config dn: olcDatabase={-1}frontend,cn=config dn: olcDatabase={0}config,cn=config dn: olcDatabase={1}hdb,cn=config root@easton2:/etc/ldap# '''_''' * to get an idea of what the ''cn=config'' database looks like ''within LDAP itself'', you can run this command: root@easton2:/etc/ldap# '''slapcat -b cn=config''' dn: cn=config objectClass: olcGlobal cn: config olcArgsFile: /var/run/slapd/slapd.args olcLogLevel: none olcPidFile: /var/run/slapd/slapd.pid olcToolThreads: 1 '''''(more LDIF texts)''''' entryUUID: f2a8f568-fa40-102f-8b9d-5d4cbccf32a9 creatorsName: cn=admin,cn=config createTimestamp: 20110413174103Z entryCSN: 20110413174103.641065Z#000000#000#000000 modifiersName: cn=admin,cn=config modifyTimestamp: 20110413174103Z root@easton2:/etc/ldap# '''_''' : As you can see, this generates a pretty large LDIF dump of the contents of the ''cn=config'' directory. Much of it consists of schema information. The LDAP configuration directives are attributes of the directory entries (objects) and most them start with the prefix "olc" ('''O'''pen'''L'''DAP '''C'''onfiguration). Also, some of the objects have names with numbers between curly brackets. This is to compensate for the fact that LDAP databases do not store their contents in any particular order; they are inherently unordered. The numbers constitute a numeric index to ensure a consistent order in the configuration database and thereby preserve all ordering dependencies. The index numbers, however, are generated automatically in the order they are created and usually do not have to be provided. * you can see the configuration by browsing through all the plain-text flat files in ''/etc/ldap/slapd.d/'' and its subdirectories. Note that by default there is no way to do this remotely. If you'd like to browse this configuration using a GUI tool like [http://directory.apache.org/studio/ apache directory studio], don't bother. Debian sets the ''cn=config'' part of the database with a root user of ''cn=admin,cn=config'', but without a password, so you cannot bind to the ''cn=config'' database as anything else than the local root user. Thus you cannot access the ''cn=config'' database by GUI. ===Adding or modifying the cn=config admin password=== To add a password to the config RootDN, we first must generate one; for this we can use the ''slappasswd'' command. By default it'll create an SSHA password, but by specifying MD5 as hash (using '' -h {MD5}'') it will create an MD5 encrypted password. The command interactively asks you for the password, and won't show you what you've typed, so be precise: root@easton2:/etc/ldap# '''slappasswd -h {MD5}''' New password: Re-enter new password: {MD5}d5axCh6gYGjhfK4PGs09us== root@easton2:/etc/ldap# '''_''' Now we determine the DN (Distinguished Name) for the database that contains the RootDN password. We'll also check if there isn't a password in place already. To do this we used the following LDAP search command. root@easton2:/etc/ldap# '''ldapsearch -LLL -Y EXTERNAL -H ldapi:/// -b cn=config olcRootDN=cn=admin,cn=config dn olcRootDN olcRootPW''' SASL/EXTERNAL authentication started SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth SASL SSF: 0 dn: olcDatabase={0}config,cn=config olcRootDN: cn=admin,cn=config root@easton2:/etc/ldap# '''_''' Note the olcDatabase line, as it's the result we were looking for; it'll be needed for the ''ldapmodify'' command. Furthermore, note the absence of an olcRootPW entry; this is the starting point for a Debian OpenLDAP server.<br> Now we can stick in a new password. If no password is present, you can use this interactive procedure: root@easton2:/etc/ldap# '''ldapmodify -Y EXTERNAL -H ldapi:///''' SASL/EXTERNAL authentication started SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth SASL SSF: 0 '''dn: olcDatabase={0}config,cn=config''' '''add: olcRootPW''' '''olcRootPW: {MD5}d5axCh6gYGjhfK4PGs09us==''' modifying entry "olcDatabase={0}config,cn=config" root@easton2:/etc/ldap# '''_''' Note the following points: * we use the olcDatabase location as found with the previous ''ldapsearch'' command; * we input the MD5 password that we've generated previously; * as soon as you put in an empty line, the entry gets added; * you have to use CTRL-D to end this interactive mode; * if a password was already in place, we could still use the above, but we'd interactively feed the second line as '''replace: olcRootPW'''. We could also put the password in an ldif file, and feed that to the server. To this end, we'd create an ldif file with the following content: dn: olcDatabase={0}config,cn=config changetype: modify add: olcRootPW olcRootPW: {MD5}d5axCh6gYGjhfK4PGs09us== If this file is called ''addpassword.ldif'' and is created in ''/tmp'', then the addition can be executed using root@easton2:/etc/ldap# '''ldapmodify -Y EXTERNAL -H ldapi:/// -f /tmp/addpassword.ldif''' SASL/EXTERNAL authentication started SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth SASL SSF: 0 modifying entry "olcDatabase={0}config,cn=config" root@easton2:/tmp# '''_''' ==Adding or modifying (configuration) information== The simple way of changing anything in the database goes like this: ===Method 1: interactive CLI tool=== As an example, let's add an index to the configuration. We'll start by seeing which indices already exist, then interactively add two indices. Finally, we check that the indices are there: root@easton2:/tmp# '''ldapsearch -LLLQY EXTERNAL -H ldapi:/// -b cn=config olcDatabase={1}hdb olcDbIndex''' dn: olcDatabase={1}hdb,cn=config olcDbIndex: objectClass eq root@easton2:/tmp# '''ldapmodify -Y EXTERNAL -H ldapi:///''' SASL/EXTERNAL authentication started SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth SASL SSF: 0 '''dn: olcDatabase={1}hdb,cn=config''' '''add: olcDbIndex''' '''olcDbIndex: cn eq''' '''olcDbIndex: uid eq''' modifying entry "olcDatabase={1}hdb,cn=config" root@easton2:/tmp# '''ldapsearch -LLLQY EXTERNAL -H ldapi:/// -b cn=config olcDatabase={1}hdb olcDbIndex''' dn: olcDatabase={1}hdb,cn=config olcDbIndex: objectClass eq olcDbIndex: cn eq olcDbIndex: uid eq root@easton2:/tmp# '''_''' (And ofcourse we press ctrl-D to end interactive mode).<br>Note: we can /modify multiple attributes in one stanza, but we can also add multiple objects/attributes in one ''ldapmodify'' session: * If you input an empty line, you can start another ''dn:'' line, and perform another action; * If you input a minus sign by itself on a line, then OpenLDAP will assume you'll be performing another action in/on the same object. Modifying works almost the same; we only need keyword ''replace'' instead of ''add'': root@easton2:/tmp# '''ldapsearch -LLLQY EXTERNAL -H ldapi:/// -b cn=config -s base olcLogLevel''' dn: cn=config olcLogLevel: none root@easton2:/tmp# '''ldapmodify -Y EXTERNAL -H ldapi:///''' SASL/EXTERNAL authentication started SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth SASL SSF: 0 '''dn: cn=config''' '''changetype: modify''' '''replace: olcLogLevel''' '''olcLogLevel: stats''' modifying entry "cn=config" root@easton2:/tmp# '''ldapsearch -LLLQY EXTERNAL -H ldapi:/// -b cn=config -s base olcLogLevel''' dn: cn=config olcLogLevel: stats root@easton2:/tmp# '''_''' Note the ''-s base'' option that limits the search for the ''olcLogLevel'' attribute to the ''cn=config'' container. Deleting information from an LDAP tree rarely ever happens, because once an attribute is used for anything, you aren't allowed to delete it, only modify it. However, if you want to delete anything, you can use the changetype "modify" with action "delete": root@easton2:/tmp# '''ldapmodify -Y EXTERNAL -H ldapi:///''' SASL/EXTERNAL authentication started SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth SASL SSF: 0 '''dn: olcDatabase={0}config,cn=config''' '''changetype: modify''' '''delete: olcRootPW''' modifying entry "olcDatabase={0}config,cn=config" root@easton2:/tmp# '''_''' ===Method 2: use an ldif file=== ===Method 3: use an LDAP browser=== With this method, you just use your LDAP browser for the addition or modification, according to its specific usage instructions. In the back, the tool will communicate with the LDAP server as you would in the previous methods. Note however, that this method relies on a bind account in the configuration database, which is a serious security risk. ==Adding schemas== A major task in LDAP maintenance is the addition of LDAP schemas. By default, only 4 schemas will be present in your LDAP server: ''core'', ''cosine'', ''nis'' and ''inetorgperson''. Any other schema, -- say, for Samba -- would need to be added. However, let's first check which schemas are already installed. Let's try two different methods, and see what they'll show out of the box: root@easton2:/tmp# '''ldapsearch -LLLQY EXTERNAL -H ldapi:/// -b cn=schema,cn=config "(objectClass=olcSchemaConfig)" dn''' dn: cn=schema,cn=config dn: cn={0}core,cn=schema,cn=config dn: cn={1}cosine,cn=schema,cn=config dn: cn={2}nis,cn=schema,cn=config dn: cn={3}inetorgperson,cn=schema,cn=config root@easton2:/tmp# '''ls -l /etc/ldap/slapd.d/cn=config/cn=schema''' total 40 -rw------- 1 openldap openldap 15474 Jun 13 17:39 cn={0}core.ldif -rw------- 1 openldap openldap 11308 Jun 13 17:39 cn={1}cosine.ldif -rw------- 1 openldap openldap 6438 Jun 13 17:39 cn={2}nis.ldif -rw------- 1 openldap openldap 2802 Jun 13 17:39 cn={3}inetorgperson.ldif root@easton2:/tmp# '''_''' To add a schema, you need a schema in LDIF format, which you can then add to the LDAP database using the ''ldapadd'' command. Suppose you have a schema file ''samba.schema'' which you've copied to the ''/etc/ldap/schema'' directory. You'd first have to convert this to a suitable LDIF file. This can be done using ''slaptest'', however ''slaptest'' requires access to the other schemas that your new schema is building on. So we now do this: * under ''/tmp'' we create a file ''schema_convert.conf'' with the following content:<pre>include /etc/ldap/schema/core.schema<br>include /etc/ldap/schema/cosine.schema<br>include /etc/ldap/schema/nis.schema<br>include /etc/ldap/schema/inetorgperson.schema<br>include /etc/ldap/schema/samba.schema</pre>Note that we're including the schema files of all the schemas that are already in our LDAP server, * now we create a working directory where ''slaptest'' can put our new LDIF file:<pre>mkdir /tmp/ldif_output</pre> * h 6d71da472dddcfdf7cca9b47e2aa2cc44f4a684f 2726 2725 2012-04-01T15:25:39Z Saruman! 2 /* Adding schemas */ more wikitext text/x-wiki Note: if you need information on the OpenLDAP version from Debian 5.0, see this page: [[OpenLDAP 2.4.11]] == OpenLDAP installation== Note: we're going to install OpenLDAP on our server as [http://www.openldap.org/doc/admin24/config.html#Local%20Directory%20Service the local directory service], without replication, referrals or other advanced features. Under Debian Squeeze, this is OpenLDAP 2.4.23. ===Standard installation=== Installing OpenLDAP on your Debian server is ridiculously simple. Just make sure your server is up-to-date (''sudo apt-get update'' followed by ''sudo apt-get upgrade''), and then install the two main components for your OpenLDAP server. First off: the LDAP client and utilities sudo apt-get install ldap-utils This will result in the installation of as much as 8 different packages (''ldap-utils'', ''libgcrypt11'', ''libgnutls26'', ''libgpg-error0'', ''libldap-2.4-2'', ''libsasl2-2'', ''libsasl2-modules'', and ''libtasn1-3''). Next the main component of an LDAP server installation, the stand-alone LDAP daemon "slapd" sudo apt-get install slapd This may also install up to 8 packages (''slapd'', ''libltdl7'', ''libperl5.10'', ''libslp1'', ''odbcinst'', ''odbcinst1debian2'', ''psmisc'' and ''unixodbc''). The Debian configuration script will ask you for only one single thing: an administrator password. As always: generate a strong password! After you've provided the password, the LDAP database is created with the administrator name "admin" and as a base directory, something based on your DNS name. Suppose your internal domain is "amber.lan", then the script will generate ''suffix "dc=amber,dc=lan"''<ref>Should you see a third, empty, domain component (''dc='') then this is caused by a trailing dot in your particular DNS name: the DNS root. You might have specified your domain as "amber.lan.". You ''should'' change your domain name to a name without the DNS root, and you ''must'' regenerate your LDAP directory.</ref>. The above method of configuring yields you an LDAP database with only two objects in it. Suppose your DNS name is "easton2.amber.lan", then the two objects are: * a single Organization (o="amber.lan") with Distinguished Name dn="dc=amber,dc=lan" * a single administrator with Common Name cn="admin", and dn="cn=admin,dc=amber,dc=lan" Note, however, that there's ''also'' a second LDAP database, "cn=config", which on your server is located under ''/etc/ldap/slapd.d''. We'll cover what's in it further on. <references/> ===Testing the installation=== After installation of the package, it should automatically have been started, and should now be operational. This can be checked with a utility like ''nmap'': root@easton2:~# '''nmap -p 389 localhost''' Starting Nmap 5.00 ( <nowiki>http://nmap.org</nowiki> ) at 2011-04-13 21:19 CEST Interesting ports on localhost (127.0.0.1): PORT STATE SERVICE 389/tcp open ldap Nmap done: 1 IP address (1 host up) scanned in 0.40 seconds root@easton2:~#'''_''' Another way to test if the LDAP server is functional, is by querying it with the ''ldapsearch'' utility, part of the package ''ldap-utils''. Let's see if we can find the naming context of the LDAP server: root@easton2:~# '''ldapsearch -x -b <nowiki>''</nowiki> -s base '(objectclass=*)' namingContexts''' # extended LDIF # # LDAPv3 # base <> with scope baseObject # filter: (objectclass=*) # requesting: namingContexts # # dn: namingContexts: dc=amber,dc=lan # search result search: 2 result: 0 Success # numResponses: 2 # numEntries: 1 root@easton2:~# '''_''' With this command, we do a search using * basic authentication (instead of one encrypted with SASL), * searching within the LDAP tree from base <nowiki>''</nowiki> (meaning the absolute root of the tree), * looking for base object only (instead of a one-level search, a subtree search, or a children-search), * filtering for objects of any class, * asking for the naming context of the result. The output shows that the server responds; two objects have been considered, but none match the filter (that the object should have an objectClass). Let's now do the same but with authentication, to see if we can bind to the LDAP server. We'll first use an incorrect password, then the correct one: root@easton2:~# '''ldapsearch -W -D "cn=admin,dc=amber,dc=lan"''' Enter LDAP Password: ldap_bind: Invalid credentials (49) root@easton2:~# '''ldapsearch -W -D "cn=admin,dc=amber,dc=lan"''' Enter LDAP Password: # extended LDIF # # LDAPv3 # base <> (default) with scope subtree # filter: (objectclass=*) # requesting: ALL # # search result search: 2 result: 32 No such object # numResponses: 1 root@easton2:~# '''_''' Finally, you could simply install and run a graphical management tool for LDAP servers, like [http://directory.apache.org/studio/ Apache Directory Studio]. Note however that if this check fails, then this could also mean problems with firewalls, network connections et cetera. ===Post-install reconfiguration=== Since the default configuration with the server's DNS domain as LDAP base might not always be the most convenient configuration, you could run the configuration again using ''dpkg-reconfigure slapd''. However, following this procedure is '''only''' necessary if you want to change any of the default installation values like the backend database type or DNS domain name; things like the organization name can be edited with other means, as will be shown later on. To be able to reconfigure the LDAP service, you can run the reconfiguration command ''sudo dpkg-reconfigure slapd''. Contrary to some older versions of Debian, you do not need to manually stop the ''slapd'' daemon, and you don't need to manually remove the old configuration or database (in fact, if you do, then the ''slapd'' package will break, so you cannot easily remove it with APT tools). Interestingly enough, this reconfiguration asks you many ''more'' questions. The answers could look like this: omit OpenLDAP config: no DNS domain name: saruman.biz Organization name: Saruman Administrator passwd: wEt3udes Database backend: HDB DB remove after purge: yes Move old DB: yes Allow LDAPv2: no As you can see, the reconfiguration yields much more configuration options than plain installation - although really you'll probably answer most questions with their default values anyway. The above method of configuring yields you an LDAP database with only two objects in it: * a single Organization (o="Saruman") with Distinguished Name dn="dc=saruman,dc=biz" * a single administrator with Common Name cn="admin", and dn="cn=admin,dc=saruman,dc=biz" Also note that the reconfiguration creates a backup of the "old" LDAP database in a directory with a name like ''/var/backup/unknown-2.4.23-7.ldapdb''; if you just reconfigured after installation, then you probably don't need this backup, so you can remove it. The database that your OpenLDAP server uses is a standard Berkeley DB (BDB/HDB) database. Now we most likely will require some other databases as well in our server setup, something modern like PostgreSQL or MySQL - so why don't we configure our OpenLDAP to use this same database as well? For the answer, see [http://www.openldap.org/doc/admin24/intro.html#LDAP%20vs%20RDBMS here] - in short, the LDAP tree structure does not lend itself very well to inclusion in a modern relational database. Thus, we advise to stick with the Berkeley database provided with OpenLDAP. Now, for the database backend, we have the choice between two almost identical flavours: * the ''bdb'' backend used to be the recommended primary backend for a normal slapd database. It uses the Oracle Berkeley DB package, referred to as ''BDB'', to store data. It makes extensive use of indexing and caching to speed data access. * the ''hdb'' backend is a variant of the ''bdb'' backend that uses a hierarchical database layout which supports subtree renames. It is otherwise identical to the ''bdb'' behavior, and all the same configuration options apply. In Debian 6.0 "Squeeze" with OpenLDAP 2.4.23, HDB is the default backend. ==OpenLDAP server configuration== <small>(text from http://www.rjsystems.nl/en/2100-d6-openldap-provider.php)</small> As of OpenLDAP 2.4.23-3, the ''slapd'' runtime configuration is fully LDAP-enabled. The default is to manage it using the standard LDAP operations with data in LDIF. The old ''slapd.conf'' format is still supported, but since that file must now be converted to the new ''slapd-config'' format to allow runtime changes to be saved, it seems likely that the developers will eventually phase it out. Therefore, we'll focus only on the new configuration method, the main advantage of which is that any changes made are immediately active, so it is no longer necessary to restart ''slapd'' after making configuration changes. The new configuration format uses a slapd backend database that is found in the ''/etc/ldap/slapd.d/'' directory. The configuration is stored as a special LDAP directory with a predefined schema and DIT, the root of which is called ''cn=config''. If you go look there, you'll find that most parts of this LDAP directory consist of editable flat files. ===Check the current LDAP configuration=== From the command line, there really are several ways to check the current LDAP configuration: * from the server itself, you can use the trusty ''ldapsearch'' command, running under root: this'll authenticate with user ID 0. Filtering only for distinguished names: root@easton2:/etc/ldap# '''ldapsearch -LLL -Y EXTERNAL -H ldapi:/// -b cn=config dn''' SASL/EXTERNAL authentication started SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth SASL SSF: 0 dn: cn=config dn: cn=module{0},cn=config dn: cn=schema,cn=config dn: cn={0}core,cn=schema,cn=config dn: cn={1}cosine,cn=schema,cn=config dn: cn={2}nis,cn=schema,cn=config dn: cn={3}inetorgperson,cn=schema,cn=config dn: olcBackend={0}hdb,cn=config dn: olcDatabase={-1}frontend,cn=config dn: olcDatabase={0}config,cn=config dn: olcDatabase={1}hdb,cn=config root@easton2:/etc/ldap# '''_''' * to get an idea of what the ''cn=config'' database looks like ''within LDAP itself'', you can run this command: root@easton2:/etc/ldap# '''slapcat -b cn=config''' dn: cn=config objectClass: olcGlobal cn: config olcArgsFile: /var/run/slapd/slapd.args olcLogLevel: none olcPidFile: /var/run/slapd/slapd.pid olcToolThreads: 1 '''''(more LDIF texts)''''' entryUUID: f2a8f568-fa40-102f-8b9d-5d4cbccf32a9 creatorsName: cn=admin,cn=config createTimestamp: 20110413174103Z entryCSN: 20110413174103.641065Z#000000#000#000000 modifiersName: cn=admin,cn=config modifyTimestamp: 20110413174103Z root@easton2:/etc/ldap# '''_''' : As you can see, this generates a pretty large LDIF dump of the contents of the ''cn=config'' directory. Much of it consists of schema information. The LDAP configuration directives are attributes of the directory entries (objects) and most them start with the prefix "olc" ('''O'''pen'''L'''DAP '''C'''onfiguration). Also, some of the objects have names with numbers between curly brackets. This is to compensate for the fact that LDAP databases do not store their contents in any particular order; they are inherently unordered. The numbers constitute a numeric index to ensure a consistent order in the configuration database and thereby preserve all ordering dependencies. The index numbers, however, are generated automatically in the order they are created and usually do not have to be provided. * you can see the configuration by browsing through all the plain-text flat files in ''/etc/ldap/slapd.d/'' and its subdirectories. Note that by default there is no way to do this remotely. If you'd like to browse this configuration using a GUI tool like [http://directory.apache.org/studio/ apache directory studio], don't bother. Debian sets the ''cn=config'' part of the database with a root user of ''cn=admin,cn=config'', but without a password, so you cannot bind to the ''cn=config'' database as anything else than the local root user. Thus you cannot access the ''cn=config'' database by GUI. ===Adding or modifying the cn=config admin password=== To add a password to the config RootDN, we first must generate one; for this we can use the ''slappasswd'' command. By default it'll create an SSHA password, but by specifying MD5 as hash (using '' -h {MD5}'') it will create an MD5 encrypted password. The command interactively asks you for the password, and won't show you what you've typed, so be precise: root@easton2:/etc/ldap# '''slappasswd -h {MD5}''' New password: Re-enter new password: {MD5}d5axCh6gYGjhfK4PGs09us== root@easton2:/etc/ldap# '''_''' Now we determine the DN (Distinguished Name) for the database that contains the RootDN password. We'll also check if there isn't a password in place already. To do this we used the following LDAP search command. root@easton2:/etc/ldap# '''ldapsearch -LLL -Y EXTERNAL -H ldapi:/// -b cn=config olcRootDN=cn=admin,cn=config dn olcRootDN olcRootPW''' SASL/EXTERNAL authentication started SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth SASL SSF: 0 dn: olcDatabase={0}config,cn=config olcRootDN: cn=admin,cn=config root@easton2:/etc/ldap# '''_''' Note the olcDatabase line, as it's the result we were looking for; it'll be needed for the ''ldapmodify'' command. Furthermore, note the absence of an olcRootPW entry; this is the starting point for a Debian OpenLDAP server.<br> Now we can stick in a new password. If no password is present, you can use this interactive procedure: root@easton2:/etc/ldap# '''ldapmodify -Y EXTERNAL -H ldapi:///''' SASL/EXTERNAL authentication started SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth SASL SSF: 0 '''dn: olcDatabase={0}config,cn=config''' '''add: olcRootPW''' '''olcRootPW: {MD5}d5axCh6gYGjhfK4PGs09us==''' modifying entry "olcDatabase={0}config,cn=config" root@easton2:/etc/ldap# '''_''' Note the following points: * we use the olcDatabase location as found with the previous ''ldapsearch'' command; * we input the MD5 password that we've generated previously; * as soon as you put in an empty line, the entry gets added; * you have to use CTRL-D to end this interactive mode; * if a password was already in place, we could still use the above, but we'd interactively feed the second line as '''replace: olcRootPW'''. We could also put the password in an ldif file, and feed that to the server. To this end, we'd create an ldif file with the following content: dn: olcDatabase={0}config,cn=config changetype: modify add: olcRootPW olcRootPW: {MD5}d5axCh6gYGjhfK4PGs09us== If this file is called ''addpassword.ldif'' and is created in ''/tmp'', then the addition can be executed using root@easton2:/etc/ldap# '''ldapmodify -Y EXTERNAL -H ldapi:/// -f /tmp/addpassword.ldif''' SASL/EXTERNAL authentication started SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth SASL SSF: 0 modifying entry "olcDatabase={0}config,cn=config" root@easton2:/tmp# '''_''' ==Adding or modifying (configuration) information== The simple way of changing anything in the database goes like this: ===Method 1: interactive CLI tool=== As an example, let's add an index to the configuration. We'll start by seeing which indices already exist, then interactively add two indices. Finally, we check that the indices are there: root@easton2:/tmp# '''ldapsearch -LLLQY EXTERNAL -H ldapi:/// -b cn=config olcDatabase={1}hdb olcDbIndex''' dn: olcDatabase={1}hdb,cn=config olcDbIndex: objectClass eq root@easton2:/tmp# '''ldapmodify -Y EXTERNAL -H ldapi:///''' SASL/EXTERNAL authentication started SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth SASL SSF: 0 '''dn: olcDatabase={1}hdb,cn=config''' '''add: olcDbIndex''' '''olcDbIndex: cn eq''' '''olcDbIndex: uid eq''' modifying entry "olcDatabase={1}hdb,cn=config" root@easton2:/tmp# '''ldapsearch -LLLQY EXTERNAL -H ldapi:/// -b cn=config olcDatabase={1}hdb olcDbIndex''' dn: olcDatabase={1}hdb,cn=config olcDbIndex: objectClass eq olcDbIndex: cn eq olcDbIndex: uid eq root@easton2:/tmp# '''_''' (And ofcourse we press ctrl-D to end interactive mode).<br>Note: we can /modify multiple attributes in one stanza, but we can also add multiple objects/attributes in one ''ldapmodify'' session: * If you input an empty line, you can start another ''dn:'' line, and perform another action; * If you input a minus sign by itself on a line, then OpenLDAP will assume you'll be performing another action in/on the same object. Modifying works almost the same; we only need keyword ''replace'' instead of ''add'': root@easton2:/tmp# '''ldapsearch -LLLQY EXTERNAL -H ldapi:/// -b cn=config -s base olcLogLevel''' dn: cn=config olcLogLevel: none root@easton2:/tmp# '''ldapmodify -Y EXTERNAL -H ldapi:///''' SASL/EXTERNAL authentication started SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth SASL SSF: 0 '''dn: cn=config''' '''changetype: modify''' '''replace: olcLogLevel''' '''olcLogLevel: stats''' modifying entry "cn=config" root@easton2:/tmp# '''ldapsearch -LLLQY EXTERNAL -H ldapi:/// -b cn=config -s base olcLogLevel''' dn: cn=config olcLogLevel: stats root@easton2:/tmp# '''_''' Note the ''-s base'' option that limits the search for the ''olcLogLevel'' attribute to the ''cn=config'' container. Deleting information from an LDAP tree rarely ever happens, because once an attribute is used for anything, you aren't allowed to delete it, only modify it. However, if you want to delete anything, you can use the changetype "modify" with action "delete": root@easton2:/tmp# '''ldapmodify -Y EXTERNAL -H ldapi:///''' SASL/EXTERNAL authentication started SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth SASL SSF: 0 '''dn: olcDatabase={0}config,cn=config''' '''changetype: modify''' '''delete: olcRootPW''' modifying entry "olcDatabase={0}config,cn=config" root@easton2:/tmp# '''_''' ===Method 2: use an ldif file=== ===Method 3: use an LDAP browser=== With this method, you just use your LDAP browser for the addition or modification, according to its specific usage instructions. In the back, the tool will communicate with the LDAP server as you would in the previous methods. Note however, that this method relies on a bind account in the configuration database, which is a serious security risk. ==Adding schemas== A major task in LDAP maintenance is the addition of LDAP schemas. By default, only 4 schemas will be present in your LDAP server: ''core'', ''cosine'', ''nis'' and ''inetorgperson''. Any other schema, -- say, for Samba -- would need to be added. ===Checking existing schemas=== Let's first check which schemas are already installed. Let's try two different methods, and see what they'll show out of the box: root@easton2:/tmp# '''ldapsearch -LLLQY EXTERNAL -H ldapi:/// -b cn=schema,cn=config "(objectClass=olcSchemaConfig)" dn''' dn: cn=schema,cn=config dn: cn={0}core,cn=schema,cn=config dn: cn={1}cosine,cn=schema,cn=config dn: cn={2}nis,cn=schema,cn=config dn: cn={3}inetorgperson,cn=schema,cn=config root@easton2:/tmp# '''ls -l /etc/ldap/slapd.d/cn=config/cn=schema''' total 40 -rw------- 1 openldap openldap 15474 Jun 13 17:39 cn={0}core.ldif -rw------- 1 openldap openldap 11308 Jun 13 17:39 cn={1}cosine.ldif -rw------- 1 openldap openldap 6438 Jun 13 17:39 cn={2}nis.ldif -rw------- 1 openldap openldap 2802 Jun 13 17:39 cn={3}inetorgperson.ldif root@easton2:/tmp# '''_''' ===Creating a suitable LDIF file for the schema=== To add a schema, you need a schema in LDIF format, which you can then add to the LDAP database using the ''ldapadd'' command. Suppose you have a schema file ''samba.schema'' which you've copied to the ''/etc/ldap/schema'' directory. You'd first have to convert this to a suitable LDIF file. This can be done using ''slaptest'', however ''slaptest'' requires access to the other schemas that your new schema is building on. So we now do this: * under ''/tmp'' we create a file ''schema_convert.conf'' with the following content (Note that we're including the schema files of all the schemas that are already in our LDAP server): include /etc/ldap/schema/core.schema include /etc/ldap/schema/cosine.schema include /etc/ldap/schema/nis.schema include /etc/ldap/schema/inetorgperson.schema include /etc/ldap/schema/samba.schema * now we create a working directory where ''slaptest'' can put our new LDIF file, and have ''slaptest'' create the configuration: root@easton2:/tmp# '''mkdir /tmp/ldif_output''' root@easton2:/tmp# '''slaptest -f /tmp/schema_convert.conf -F /tmp/ldif_output''' config file testing succeeded root@easton2:/tmp# '''_''' * The previous step has created a directory structure under ''/tmp/ldif_output'' that actually mirrors the config directory ''/etc/ldap/slapd.d/cn=config/cn=schema'', but it contains a shiny new ''cn={4}samba.ldif'' file. We need to edit this file a bit before we can actually feed it to the LDAP server. Thus we'll edit it using (note the extra backslashes to escape the equal-sign and curly brackets): root@easton2:/tmp# '''vi /tmp/ldif_output/cn\=config/cn\=schema/cn\=\{4\}samba.ldif''' * We need to change and edit some parts of ''cn={4}samba.ldif'': ** Near the top we find ''dn: cn={4}samba''. We'll change this to the correct distinguished name ''dn: cn=samba,cn=schema,cn=config'' ** Also near the top: ''cn: {4}samba''. We'll change this to ''cn: samba'' ** The last seven lines look like the bit below - we need to remove these lines: structuralObjectClass: olcSchemaConfig entryUUID: f19250ba-1057-1031-88b7-8301a25f1d46 creatorsName: cn=config createTimestamp: 20120401150603Z entryCSN: 20120401150603.478495Z#000000#000#000000 modifiersName: cn=config modifyTimestamp: 20120401150603Z * We'll store the cleaned up LDIF file in ''/etc/ldap/schema'' with the originating schema file root@easton2:/tmp# '''mv /tmp/ldif_output/cn\=config/cn\=schema/cn\=\{4\}samba.ldif /etc/ldap/schema/samba.ldif''' root@easton2:/tmp# '''_''' ===Inserting the LDIF file in the LDAP server=== Time to actually invoke ''ldapadd'' which can put this schema in our LDAP server. root@easton2:/tmp# '''ldapadd -QY EXTERNAL -H ldapi:/// -f /etc/ldap/schema/samba.ldif''' adding new entry "cn=samba,cn=schema,cn=config" root@easton2:/tmp# '''_''' f967a7d7d2ab85beff0f47cab1bef55b129a53ce 2727 2726 2012-04-01T15:28:13Z Saruman! 2 /* Adding schemas */ path wikitext text/x-wiki Note: if you need information on the OpenLDAP version from Debian 5.0, see this page: [[OpenLDAP 2.4.11]] == OpenLDAP installation== Note: we're going to install OpenLDAP on our server as [http://www.openldap.org/doc/admin24/config.html#Local%20Directory%20Service the local directory service], without replication, referrals or other advanced features. Under Debian Squeeze, this is OpenLDAP 2.4.23. ===Standard installation=== Installing OpenLDAP on your Debian server is ridiculously simple. Just make sure your server is up-to-date (''sudo apt-get update'' followed by ''sudo apt-get upgrade''), and then install the two main components for your OpenLDAP server. First off: the LDAP client and utilities sudo apt-get install ldap-utils This will result in the installation of as much as 8 different packages (''ldap-utils'', ''libgcrypt11'', ''libgnutls26'', ''libgpg-error0'', ''libldap-2.4-2'', ''libsasl2-2'', ''libsasl2-modules'', and ''libtasn1-3''). Next the main component of an LDAP server installation, the stand-alone LDAP daemon "slapd" sudo apt-get install slapd This may also install up to 8 packages (''slapd'', ''libltdl7'', ''libperl5.10'', ''libslp1'', ''odbcinst'', ''odbcinst1debian2'', ''psmisc'' and ''unixodbc''). The Debian configuration script will ask you for only one single thing: an administrator password. As always: generate a strong password! After you've provided the password, the LDAP database is created with the administrator name "admin" and as a base directory, something based on your DNS name. Suppose your internal domain is "amber.lan", then the script will generate ''suffix "dc=amber,dc=lan"''<ref>Should you see a third, empty, domain component (''dc='') then this is caused by a trailing dot in your particular DNS name: the DNS root. You might have specified your domain as "amber.lan.". You ''should'' change your domain name to a name without the DNS root, and you ''must'' regenerate your LDAP directory.</ref>. The above method of configuring yields you an LDAP database with only two objects in it. Suppose your DNS name is "easton2.amber.lan", then the two objects are: * a single Organization (o="amber.lan") with Distinguished Name dn="dc=amber,dc=lan" * a single administrator with Common Name cn="admin", and dn="cn=admin,dc=amber,dc=lan" Note, however, that there's ''also'' a second LDAP database, "cn=config", which on your server is located under ''/etc/ldap/slapd.d''. We'll cover what's in it further on. <references/> ===Testing the installation=== After installation of the package, it should automatically have been started, and should now be operational. This can be checked with a utility like ''nmap'': root@easton2:~# '''nmap -p 389 localhost''' Starting Nmap 5.00 ( <nowiki>http://nmap.org</nowiki> ) at 2011-04-13 21:19 CEST Interesting ports on localhost (127.0.0.1): PORT STATE SERVICE 389/tcp open ldap Nmap done: 1 IP address (1 host up) scanned in 0.40 seconds root@easton2:~#'''_''' Another way to test if the LDAP server is functional, is by querying it with the ''ldapsearch'' utility, part of the package ''ldap-utils''. Let's see if we can find the naming context of the LDAP server: root@easton2:~# '''ldapsearch -x -b <nowiki>''</nowiki> -s base '(objectclass=*)' namingContexts''' # extended LDIF # # LDAPv3 # base <> with scope baseObject # filter: (objectclass=*) # requesting: namingContexts # # dn: namingContexts: dc=amber,dc=lan # search result search: 2 result: 0 Success # numResponses: 2 # numEntries: 1 root@easton2:~# '''_''' With this command, we do a search using * basic authentication (instead of one encrypted with SASL), * searching within the LDAP tree from base <nowiki>''</nowiki> (meaning the absolute root of the tree), * looking for base object only (instead of a one-level search, a subtree search, or a children-search), * filtering for objects of any class, * asking for the naming context of the result. The output shows that the server responds; two objects have been considered, but none match the filter (that the object should have an objectClass). Let's now do the same but with authentication, to see if we can bind to the LDAP server. We'll first use an incorrect password, then the correct one: root@easton2:~# '''ldapsearch -W -D "cn=admin,dc=amber,dc=lan"''' Enter LDAP Password: ldap_bind: Invalid credentials (49) root@easton2:~# '''ldapsearch -W -D "cn=admin,dc=amber,dc=lan"''' Enter LDAP Password: # extended LDIF # # LDAPv3 # base <> (default) with scope subtree # filter: (objectclass=*) # requesting: ALL # # search result search: 2 result: 32 No such object # numResponses: 1 root@easton2:~# '''_''' Finally, you could simply install and run a graphical management tool for LDAP servers, like [http://directory.apache.org/studio/ Apache Directory Studio]. Note however that if this check fails, then this could also mean problems with firewalls, network connections et cetera. ===Post-install reconfiguration=== Since the default configuration with the server's DNS domain as LDAP base might not always be the most convenient configuration, you could run the configuration again using ''dpkg-reconfigure slapd''. However, following this procedure is '''only''' necessary if you want to change any of the default installation values like the backend database type or DNS domain name; things like the organization name can be edited with other means, as will be shown later on. To be able to reconfigure the LDAP service, you can run the reconfiguration command ''sudo dpkg-reconfigure slapd''. Contrary to some older versions of Debian, you do not need to manually stop the ''slapd'' daemon, and you don't need to manually remove the old configuration or database (in fact, if you do, then the ''slapd'' package will break, so you cannot easily remove it with APT tools). Interestingly enough, this reconfiguration asks you many ''more'' questions. The answers could look like this: omit OpenLDAP config: no DNS domain name: saruman.biz Organization name: Saruman Administrator passwd: wEt3udes Database backend: HDB DB remove after purge: yes Move old DB: yes Allow LDAPv2: no As you can see, the reconfiguration yields much more configuration options than plain installation - although really you'll probably answer most questions with their default values anyway. The above method of configuring yields you an LDAP database with only two objects in it: * a single Organization (o="Saruman") with Distinguished Name dn="dc=saruman,dc=biz" * a single administrator with Common Name cn="admin", and dn="cn=admin,dc=saruman,dc=biz" Also note that the reconfiguration creates a backup of the "old" LDAP database in a directory with a name like ''/var/backup/unknown-2.4.23-7.ldapdb''; if you just reconfigured after installation, then you probably don't need this backup, so you can remove it. The database that your OpenLDAP server uses is a standard Berkeley DB (BDB/HDB) database. Now we most likely will require some other databases as well in our server setup, something modern like PostgreSQL or MySQL - so why don't we configure our OpenLDAP to use this same database as well? For the answer, see [http://www.openldap.org/doc/admin24/intro.html#LDAP%20vs%20RDBMS here] - in short, the LDAP tree structure does not lend itself very well to inclusion in a modern relational database. Thus, we advise to stick with the Berkeley database provided with OpenLDAP. Now, for the database backend, we have the choice between two almost identical flavours: * the ''bdb'' backend used to be the recommended primary backend for a normal slapd database. It uses the Oracle Berkeley DB package, referred to as ''BDB'', to store data. It makes extensive use of indexing and caching to speed data access. * the ''hdb'' backend is a variant of the ''bdb'' backend that uses a hierarchical database layout which supports subtree renames. It is otherwise identical to the ''bdb'' behavior, and all the same configuration options apply. In Debian 6.0 "Squeeze" with OpenLDAP 2.4.23, HDB is the default backend. ==OpenLDAP server configuration== <small>(text from http://www.rjsystems.nl/en/2100-d6-openldap-provider.php)</small> As of OpenLDAP 2.4.23-3, the ''slapd'' runtime configuration is fully LDAP-enabled. The default is to manage it using the standard LDAP operations with data in LDIF. The old ''slapd.conf'' format is still supported, but since that file must now be converted to the new ''slapd-config'' format to allow runtime changes to be saved, it seems likely that the developers will eventually phase it out. Therefore, we'll focus only on the new configuration method, the main advantage of which is that any changes made are immediately active, so it is no longer necessary to restart ''slapd'' after making configuration changes. The new configuration format uses a slapd backend database that is found in the ''/etc/ldap/slapd.d/'' directory. The configuration is stored as a special LDAP directory with a predefined schema and DIT, the root of which is called ''cn=config''. If you go look there, you'll find that most parts of this LDAP directory consist of editable flat files. ===Check the current LDAP configuration=== From the command line, there really are several ways to check the current LDAP configuration: * from the server itself, you can use the trusty ''ldapsearch'' command, running under root: this'll authenticate with user ID 0. Filtering only for distinguished names: root@easton2:/etc/ldap# '''ldapsearch -LLL -Y EXTERNAL -H ldapi:/// -b cn=config dn''' SASL/EXTERNAL authentication started SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth SASL SSF: 0 dn: cn=config dn: cn=module{0},cn=config dn: cn=schema,cn=config dn: cn={0}core,cn=schema,cn=config dn: cn={1}cosine,cn=schema,cn=config dn: cn={2}nis,cn=schema,cn=config dn: cn={3}inetorgperson,cn=schema,cn=config dn: olcBackend={0}hdb,cn=config dn: olcDatabase={-1}frontend,cn=config dn: olcDatabase={0}config,cn=config dn: olcDatabase={1}hdb,cn=config root@easton2:/etc/ldap# '''_''' * to get an idea of what the ''cn=config'' database looks like ''within LDAP itself'', you can run this command: root@easton2:/etc/ldap# '''slapcat -b cn=config''' dn: cn=config objectClass: olcGlobal cn: config olcArgsFile: /var/run/slapd/slapd.args olcLogLevel: none olcPidFile: /var/run/slapd/slapd.pid olcToolThreads: 1 '''''(more LDIF texts)''''' entryUUID: f2a8f568-fa40-102f-8b9d-5d4cbccf32a9 creatorsName: cn=admin,cn=config createTimestamp: 20110413174103Z entryCSN: 20110413174103.641065Z#000000#000#000000 modifiersName: cn=admin,cn=config modifyTimestamp: 20110413174103Z root@easton2:/etc/ldap# '''_''' : As you can see, this generates a pretty large LDIF dump of the contents of the ''cn=config'' directory. Much of it consists of schema information. The LDAP configuration directives are attributes of the directory entries (objects) and most them start with the prefix "olc" ('''O'''pen'''L'''DAP '''C'''onfiguration). Also, some of the objects have names with numbers between curly brackets. This is to compensate for the fact that LDAP databases do not store their contents in any particular order; they are inherently unordered. The numbers constitute a numeric index to ensure a consistent order in the configuration database and thereby preserve all ordering dependencies. The index numbers, however, are generated automatically in the order they are created and usually do not have to be provided. * you can see the configuration by browsing through all the plain-text flat files in ''/etc/ldap/slapd.d/'' and its subdirectories. Note that by default there is no way to do this remotely. If you'd like to browse this configuration using a GUI tool like [http://directory.apache.org/studio/ apache directory studio], don't bother. Debian sets the ''cn=config'' part of the database with a root user of ''cn=admin,cn=config'', but without a password, so you cannot bind to the ''cn=config'' database as anything else than the local root user. Thus you cannot access the ''cn=config'' database by GUI. ===Adding or modifying the cn=config admin password=== To add a password to the config RootDN, we first must generate one; for this we can use the ''slappasswd'' command. By default it'll create an SSHA password, but by specifying MD5 as hash (using '' -h {MD5}'') it will create an MD5 encrypted password. The command interactively asks you for the password, and won't show you what you've typed, so be precise: root@easton2:/etc/ldap# '''slappasswd -h {MD5}''' New password: Re-enter new password: {MD5}d5axCh6gYGjhfK4PGs09us== root@easton2:/etc/ldap# '''_''' Now we determine the DN (Distinguished Name) for the database that contains the RootDN password. We'll also check if there isn't a password in place already. To do this we used the following LDAP search command. root@easton2:/etc/ldap# '''ldapsearch -LLL -Y EXTERNAL -H ldapi:/// -b cn=config olcRootDN=cn=admin,cn=config dn olcRootDN olcRootPW''' SASL/EXTERNAL authentication started SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth SASL SSF: 0 dn: olcDatabase={0}config,cn=config olcRootDN: cn=admin,cn=config root@easton2:/etc/ldap# '''_''' Note the olcDatabase line, as it's the result we were looking for; it'll be needed for the ''ldapmodify'' command. Furthermore, note the absence of an olcRootPW entry; this is the starting point for a Debian OpenLDAP server.<br> Now we can stick in a new password. If no password is present, you can use this interactive procedure: root@easton2:/etc/ldap# '''ldapmodify -Y EXTERNAL -H ldapi:///''' SASL/EXTERNAL authentication started SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth SASL SSF: 0 '''dn: olcDatabase={0}config,cn=config''' '''add: olcRootPW''' '''olcRootPW: {MD5}d5axCh6gYGjhfK4PGs09us==''' modifying entry "olcDatabase={0}config,cn=config" root@easton2:/etc/ldap# '''_''' Note the following points: * we use the olcDatabase location as found with the previous ''ldapsearch'' command; * we input the MD5 password that we've generated previously; * as soon as you put in an empty line, the entry gets added; * you have to use CTRL-D to end this interactive mode; * if a password was already in place, we could still use the above, but we'd interactively feed the second line as '''replace: olcRootPW'''. We could also put the password in an ldif file, and feed that to the server. To this end, we'd create an ldif file with the following content: dn: olcDatabase={0}config,cn=config changetype: modify add: olcRootPW olcRootPW: {MD5}d5axCh6gYGjhfK4PGs09us== If this file is called ''addpassword.ldif'' and is created in ''/tmp'', then the addition can be executed using root@easton2:/etc/ldap# '''ldapmodify -Y EXTERNAL -H ldapi:/// -f /tmp/addpassword.ldif''' SASL/EXTERNAL authentication started SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth SASL SSF: 0 modifying entry "olcDatabase={0}config,cn=config" root@easton2:/tmp# '''_''' ==Adding or modifying (configuration) information== The simple way of changing anything in the database goes like this: ===Method 1: interactive CLI tool=== As an example, let's add an index to the configuration. We'll start by seeing which indices already exist, then interactively add two indices. Finally, we check that the indices are there: root@easton2:/tmp# '''ldapsearch -LLLQY EXTERNAL -H ldapi:/// -b cn=config olcDatabase={1}hdb olcDbIndex''' dn: olcDatabase={1}hdb,cn=config olcDbIndex: objectClass eq root@easton2:/tmp# '''ldapmodify -Y EXTERNAL -H ldapi:///''' SASL/EXTERNAL authentication started SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth SASL SSF: 0 '''dn: olcDatabase={1}hdb,cn=config''' '''add: olcDbIndex''' '''olcDbIndex: cn eq''' '''olcDbIndex: uid eq''' modifying entry "olcDatabase={1}hdb,cn=config" root@easton2:/tmp# '''ldapsearch -LLLQY EXTERNAL -H ldapi:/// -b cn=config olcDatabase={1}hdb olcDbIndex''' dn: olcDatabase={1}hdb,cn=config olcDbIndex: objectClass eq olcDbIndex: cn eq olcDbIndex: uid eq root@easton2:/tmp# '''_''' (And ofcourse we press ctrl-D to end interactive mode).<br>Note: we can /modify multiple attributes in one stanza, but we can also add multiple objects/attributes in one ''ldapmodify'' session: * If you input an empty line, you can start another ''dn:'' line, and perform another action; * If you input a minus sign by itself on a line, then OpenLDAP will assume you'll be performing another action in/on the same object. Modifying works almost the same; we only need keyword ''replace'' instead of ''add'': root@easton2:/tmp# '''ldapsearch -LLLQY EXTERNAL -H ldapi:/// -b cn=config -s base olcLogLevel''' dn: cn=config olcLogLevel: none root@easton2:/tmp# '''ldapmodify -Y EXTERNAL -H ldapi:///''' SASL/EXTERNAL authentication started SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth SASL SSF: 0 '''dn: cn=config''' '''changetype: modify''' '''replace: olcLogLevel''' '''olcLogLevel: stats''' modifying entry "cn=config" root@easton2:/tmp# '''ldapsearch -LLLQY EXTERNAL -H ldapi:/// -b cn=config -s base olcLogLevel''' dn: cn=config olcLogLevel: stats root@easton2:/tmp# '''_''' Note the ''-s base'' option that limits the search for the ''olcLogLevel'' attribute to the ''cn=config'' container. Deleting information from an LDAP tree rarely ever happens, because once an attribute is used for anything, you aren't allowed to delete it, only modify it. However, if you want to delete anything, you can use the changetype "modify" with action "delete": root@easton2:/tmp# '''ldapmodify -Y EXTERNAL -H ldapi:///''' SASL/EXTERNAL authentication started SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth SASL SSF: 0 '''dn: olcDatabase={0}config,cn=config''' '''changetype: modify''' '''delete: olcRootPW''' modifying entry "olcDatabase={0}config,cn=config" root@easton2:/tmp# '''_''' ===Method 2: use an ldif file=== ===Method 3: use an LDAP browser=== With this method, you just use your LDAP browser for the addition or modification, according to its specific usage instructions. In the back, the tool will communicate with the LDAP server as you would in the previous methods. Note however, that this method relies on a bind account in the configuration database, which is a serious security risk. ==Adding schemas== A major task in LDAP maintenance is the addition of LDAP schemas. By default, only 4 schemas will be present in your LDAP server: ''core'', ''cosine'', ''nis'' and ''inetorgperson''. Any other schema, -- say, for Samba -- would need to be added. ===Checking existing schemas=== Let's first check which schemas are already installed. Let's try two different methods, and see what they'll show out of the box: root@easton2:/tmp# '''ldapsearch -LLLQY EXTERNAL -H ldapi:/// -b cn=schema,cn=config "(objectClass=olcSchemaConfig)" dn''' dn: cn=schema,cn=config dn: cn={0}core,cn=schema,cn=config dn: cn={1}cosine,cn=schema,cn=config dn: cn={2}nis,cn=schema,cn=config dn: cn={3}inetorgperson,cn=schema,cn=config root@easton2:/tmp# '''ls -l /etc/ldap/slapd.d/cn=config/cn=schema''' total 40 -rw------- 1 openldap openldap 15474 Jun 13 17:39 cn={0}core.ldif -rw------- 1 openldap openldap 11308 Jun 13 17:39 cn={1}cosine.ldif -rw------- 1 openldap openldap 6438 Jun 13 17:39 cn={2}nis.ldif -rw------- 1 openldap openldap 2802 Jun 13 17:39 cn={3}inetorgperson.ldif root@easton2:/tmp# '''_''' ===Creating a suitable LDIF file for the schema=== To add a schema, you need a schema in LDIF format, which you can then add to the LDAP database using the ''ldapadd'' command. Suppose you have a schema file ''samba.schema'' which you've copied to the ''/etc/ldap/schema'' directory. You'd first have to convert this to a suitable LDIF file. This can be done using ''slaptest'', however ''slaptest'' requires access to the other schemas that your new schema is building on. So we now do this: * We create a file ''schema_convert.conf'' with the content shown below. Note that we're including the schema files of all the schemas that are already in our LDAP server. Furthermore, because we may need it again with the next schema addition, it makes sense to save this file under ''/etc/ldap/schema'': include /etc/ldap/schema/core.schema include /etc/ldap/schema/cosine.schema include /etc/ldap/schema/nis.schema include /etc/ldap/schema/inetorgperson.schema include /etc/ldap/schema/samba.schema * now we create a working directory where ''slaptest'' can put our new LDIF file, and have ''slaptest'' create the configuration: root@easton2:/tmp# '''mkdir /tmp/ldif_output''' root@easton2:/tmp# '''slaptest -f /etc/ldap/schema/schema_convert.conf -F /tmp/ldif_output''' config file testing succeeded root@easton2:/tmp# '''_''' * The previous step has created a directory structure under ''/tmp/ldif_output'' that actually mirrors the config directory ''/etc/ldap/slapd.d/cn=config/cn=schema'', but it contains a shiny new ''cn={4}samba.ldif'' file. We need to edit this file a bit before we can actually feed it to the LDAP server. Thus we'll edit it using (note the extra backslashes to escape the equal-sign and curly brackets): root@easton2:/tmp# '''vi /tmp/ldif_output/cn\=config/cn\=schema/cn\=\{4\}samba.ldif''' * We need to change and edit some parts of ''cn={4}samba.ldif'': ** Near the top we find ''dn: cn={4}samba''. We'll change this to the correct distinguished name ''dn: cn=samba,cn=schema,cn=config'' ** Also near the top: ''cn: {4}samba''. We'll change this to ''cn: samba'' ** The last seven lines look like the bit below - we need to remove these lines: structuralObjectClass: olcSchemaConfig entryUUID: f19250ba-1057-1031-88b7-8301a25f1d46 creatorsName: cn=config createTimestamp: 20120401150603Z entryCSN: 20120401150603.478495Z#000000#000#000000 modifiersName: cn=config modifyTimestamp: 20120401150603Z * We'll store the cleaned up LDIF file in ''/etc/ldap/schema'' with the originating schema file root@easton2:/tmp# '''mv /tmp/ldif_output/cn\=config/cn\=schema/cn\=\{4\}samba.ldif /etc/ldap/schema/samba.ldif''' root@easton2:/tmp# '''_''' ===Inserting the LDIF file in the LDAP server=== Time to actually invoke ''ldapadd'' which can put this schema in our LDAP server. root@easton2:/tmp# '''ldapadd -QY EXTERNAL -H ldapi:/// -f /etc/ldap/schema/samba.ldif''' adding new entry "cn=samba,cn=schema,cn=config" root@easton2:/tmp# '''_''' f6f86c21d2fb18949cddb18efbeb348914ef49c1 0 1630 2728 2012-04-24T17:38:10Z Saruman! 2 dedfsdf wikitext text/x-wiki Dit is een testpagina! Echt waar! 21dba07d48e591ac98fcbf1bf68a8287741a68a9 2729 2728 2012-04-24T17:38:36Z Saruman! 2 wikitext text/x-wiki Dit is een testpagina! Echt waar! {{testsjabloon}} 26d4da40cffde4876925469998d8297b78bf3acf 10 1631 2730 2012-04-24T17:38:56Z Saruman! 2 Created page with "Dit is een template." wikitext text/x-wiki Dit is een template. 1eeb40e29ebc27c4f064137c917112d467c8fde1 0 1423 2732 1467 2012-05-27T08:35:23Z Saruman! 2 added inform. wikitext text/x-wiki ==Using APT and Aptitude== Your Debian system can easily be expanded, and also kept up-to-date with the latest security fixes, if you use Debian's beautiful [http://www.debian.org/doc/manuals/apt-howto/ch1.en.html APT (Advanced Packaging Technology)] tools. Of all available [http://en.wikipedia.org/wiki/Advanced_Packaging_Tool APT-based tools], we usually use the following: * apt-get, the command line utilities that go with APT; or * aptitude, a [http://en.wikipedia.org/wiki/Curses_%28programming_library%29 curses-based] frontend for APT. These APT-based tools are incredibly powerful and flexible, but we're not going to explain them fully here (for tuturials and whatnot, go [http://www.debian.org/doc/manuals/apt-howto/ here]). What we need to establish now, is how to configure APT, and how to use it. APT gets its information from a configuration file that can be found in ''/etc/apt''. Of these, the most important is ''sources.list'' because it defines what packages and updates can be installed from where, and even what version of Debian we want to maintain. For now let's just suffice to say that in the sources.list, you need to remove the references to the CD-ROm with which you installed the system, and specify which on-line repository you wish to use for installing and updating packages. To this end, open ''/etc/apt/sources.list'' with [[Vim | your favourite text editor]] while you are logged in as root. References to the CD-ROM look a bit like this: deb cdrom:[Debian GNU/Linux testing _Etch_ - Official Beta i386 CD Binary-1 20070317-21:45]/ etch contrib main Disable this line by putting a hash (#) in front of it (you could have more than one line beginning with ''deb cdrom:''). Now make sure you have a section that references one or more on-line repositories. This could make your ''sources.list'' look like this: <pre> # deb cdrom:[Debian GNU/Linux testing _Etch_ - Official Beta i386 CD Binary-1 20070317-21:45]/ etch contrib main deb ftp://ftp.nl.debian.org/debian/ etch main contrib deb-src ftp://ftp.nl.debian.org/debian/ etch main contrib deb http://security.debian.org/ etch/updates main contrib deb-src http://security.debian.org/ etch/updates main contrib # deb ftp://ftp.nl.debian.org/debian-volatile etch/volatile main contrib </pre> When you want to update, change, add software, or even remove software, you better update your APT system by running one of the following commands: * sudo apt-get update * sudo aptitude update * sudo aptitude, then press ''u'' Note: if you haven't installed [[sudo]] yet, then you can only run the commands as root, and they are then: ''apt-get update'', ''aptitude update'', and ''aptitude'' then ''u''. ==Getting informed on installed packages== You might at some time wonder if a package is already installed. Usually, you'd check this using dpkg --get-selections The output of this can be rather unwieldy, but you can send the output to a program like ''grep'' to refine your search. As an example: use dpkg --get-selections | grep install -c to see just how many packages you have. But this standard command doesn't directly concerns itself with versions or installation history. Now if you're wondering what version a specific package (or set of packages) is, then you can install package ''apt-show-versions'' and run it on the command line; if you wish to know the version of a particular file, e.g. ''sudo'', you'd run apt-show-versions sudo This package is described on [http://www.debianadmin.com/list-your-installed-package-versions-with-apt-show-versions.html Debian Admin]. It can do much more, but there's a fine ''man'' page for that. Furthermore, if you're interested in the installation history of your packages, you could check out the ''dpkg'' log file, by default ''/var/log/dpkg.log''. This logging file/location is set in ''/etc/dpkg/dpkg.cfg''. So to find the installation time/date of all programs, you could execute grep "status installed" /var/log/dpkg.log 9eae5dc021d2a605de50b2c11c40533ee48ec47f 2740 2732 2012-08-05T15:30:05Z Saruman! 2 added apt-file wikitext text/x-wiki ==Using APT and Aptitude== Your Debian system can easily be expanded, and also kept up-to-date with the latest security fixes, if you use Debian's beautiful [http://www.debian.org/doc/manuals/apt-howto/ch1.en.html APT (Advanced Packaging Technology)] tools. Of all available [http://en.wikipedia.org/wiki/Advanced_Packaging_Tool APT-based tools], we usually use the following: * apt-get, the command line utilities that go with APT; or * aptitude, a [http://en.wikipedia.org/wiki/Curses_%28programming_library%29 curses-based] frontend for APT. These APT-based tools are incredibly powerful and flexible, but we're not going to explain them fully here (for tuturials and whatnot, go [http://www.debian.org/doc/manuals/apt-howto/ here]). What we need to establish now, is how to configure APT, and how to use it. APT gets its information from a configuration file that can be found in ''/etc/apt''. Of these, the most important is ''sources.list'' because it defines what packages and updates can be installed from where, and even what version of Debian we want to maintain. For now let's just suffice to say that in the sources.list, you need to remove the references to the CD-ROm with which you installed the system, and specify which on-line repository you wish to use for installing and updating packages. To this end, open ''/etc/apt/sources.list'' with [[Vim | your favourite text editor]] while you are logged in as root. References to the CD-ROM look a bit like this: deb cdrom:[Debian GNU/Linux testing _Etch_ - Official Beta i386 CD Binary-1 20070317-21:45]/ etch contrib main Disable this line by putting a hash (#) in front of it (you could have more than one line beginning with ''deb cdrom:''). Now make sure you have a section that references one or more on-line repositories. This could make your ''sources.list'' look like this: <pre> # deb cdrom:[Debian GNU/Linux testing _Etch_ - Official Beta i386 CD Binary-1 20070317-21:45]/ etch contrib main deb ftp://ftp.nl.debian.org/debian/ etch main contrib deb-src ftp://ftp.nl.debian.org/debian/ etch main contrib deb http://security.debian.org/ etch/updates main contrib deb-src http://security.debian.org/ etch/updates main contrib # deb ftp://ftp.nl.debian.org/debian-volatile etch/volatile main contrib </pre> When you want to update, change, add software, or even remove software, you better update your APT system by running one of the following commands: * sudo apt-get update * sudo aptitude update * sudo aptitude, then press ''u'' Note: if you haven't installed [[sudo]] yet, then you can only run the commands as root, and they are then: ''apt-get update'', ''aptitude update'', and ''aptitude'' then ''u''. ==Getting informed on installed packages== You might at some time wonder if a package is already installed. Usually, you'd check this using dpkg --get-selections The output of this can be rather unwieldy, but you can send the output to a program like ''grep'' to refine your search. As an example: use dpkg --get-selections | grep install -c to see just how many packages you have. But this standard command doesn't directly concerns itself with versions or installation history. Now if you're wondering what version a specific package (or set of packages) is, then you can install package ''apt-show-versions'' and run it on the command line; if you wish to know the version of a particular file, e.g. ''sudo'', you'd run apt-show-versions sudo This package is described on [http://www.debianadmin.com/list-your-installed-package-versions-with-apt-show-versions.html Debian Admin]. It can do much more, but there's a fine ''man'' page for that. Furthermore, if you're interested in the installation history of your packages, you could check out the ''dpkg'' log file, by default ''/var/log/dpkg.log''. This logging file/location is set in ''/etc/dpkg/dpkg.cfg''. So to find the installation time/date of all programs, you could execute grep "status installed" /var/log/dpkg.log ==Getting information on packages that are NOT installed== This can be done with a package named '''apt-file'''. More information [http://www.debianhelp.co.uk/findfile.htm here]. 372bdc968db71374b2d35ff319237909d643c3d4 1 1632 2733 2012-07-08T21:48:38Z 174.62.124.8 0 a tip for people wikitext text/x-wiki Here's a specific tip for diagnosing ipsec tunnel difficulties. If nothing is happening -- the tunnel doesn't seem to be activating, and there isn't any output about it at all -- it's probable that your security policy configuration is incorrect, so nothing is even trying to use the tunnel. In my case, I got the direction of the traffic mixed up, and tried to say "inbound traffic from myself to machine XYZ should go through the tunnel" (and vice versa). Since I was just working with IP addresses, it was really easy to get them backwards and not notice that fact without a rigorous inspection. Once I reversed the direction and was able to get some output in my logs, my other issues were much easier to identify. :) Here's my other specific tip. Output like "ERROR: phase1 negotiation failed due to time up." may mean "check your firewalls, you're probably blocking the port. and then when you're done, check your OTHER firewall." (If you're on Amazon EC2, that means to check your security groups, including (if you're in a VPC) both inbound and outbound rules, and subnet ACLs. -- [[Special:Contributions/174.62.124.8|174.62.124.8]] 23:48, 8 July 2012 (CEST) 60bb4d6210c6c806dcb4a7026db1cc9745930d7d 2734 2733 2012-07-11T18:05:37Z Saruman! 2 wikitext text/x-wiki Here's a specific tip for diagnosing ipsec tunnel difficulties. If nothing is happening -- the tunnel doesn't seem to be activating, and there isn't any output about it at all -- it's probable that your security policy configuration is incorrect, so nothing is even trying to use the tunnel. In my case, I got the direction of the traffic mixed up, and tried to say "inbound traffic from myself to machine XYZ should go through the tunnel" (and vice versa). Since I was just working with IP addresses, it was really easy to get them backwards and not notice that fact without a rigorous inspection. Once I reversed the direction and was able to get some output in my logs, my other issues were much easier to identify. :) Here's my other specific tip. Output like "ERROR: phase1 negotiation failed due to time up." may mean "check your firewalls, you're probably blocking the port. and then when you're done, check your OTHER firewall." (If you're on Amazon EC2, that means to check your security groups, including (if you're in a VPC) both inbound and outbound rules, and subnet ACLs. -- [[Special:Contributions/174.62.124.8|174.62.124.8]] 23:48, 8 July 2012 (CEST) : Good tips! Thanks, --[[User:Saruman!|Saruman!]] 20:05, 11 July 2012 (CEST) dfeab30200225b9dd38930fe62d5c948df0e9e71 0 1 2738 2669 2012-08-05T15:11:31Z Saruman! 2 dlna wikitext text/x-wiki <big>'''Welcome to SaruWiki.'''</big> This Wiki is intended to document bits and bobs about [http://www.kernel.org/ Linux] (and some Unix) in general, and [http://www.debian.org Debian] in particular. In it, [[SaruWiki:About|we]] wish to collect the tips and tricks of both [[SaruWiki:About|our own team of Linux admins]] and those of other interested users. If you are interested in my work on [http://www.dya.info DYA|Infrastructure], please visit the [https://dya-knowledge.sogeti.nl/ SmartMart demo site]. Consult the [http://meta.wikimedia.org/wiki/Help:Contents User's Guide] for information on using this wiki's software. <big>NOTE:</big> '''you must confirm edits''' when you're not logged in with a user account. Thanks to the Mediawiki ConfirmEdit extension we've cut our wikispam considerably. Sorry to make you anonymous contributors jump through this little hoop for every edit, but there you are. ---- <big>'''Main Content'''</big> * Setting up a [[Debian Squeeze base server]] is a howto on the installation of a very basic Linux box under Lenny (it's actually not even a server yet). * Using ''md'' for [[software-based RAID]] contains our ideas and observations on redundancy. * The use of [[APT and aptitude]] is crucial to the concept of a Debian machine. * [[Roll your own kernel]] discusses the pros and cons of compiling your own kernel, and how to do it. * [[Essential system software]] lists all (sets of) packages that we deem, well, essential. * [[Apache2 and PHP5]] are essential packages if you want to light your own little [[LAMP]]. * [[Pluggable Authentication Modules (PAM)]] is a great way to secure your server and arrange logins - if you get to understand them * [[Certificate fundamentals | The "certificates" section]] explains how you create your own Certificate Authority (CA) and the neat things you can do with it. * [[Database 101]] introduces you to MySQL. * [[OpenLDAP]] is a rudimentary howto about getting OpenLDAP to be your central user repository. * The [[Installing SaMBa with OpenLDAP support | SaMBa section]] explains how to install SaMBa with OpenLDAP as user backend. * [[Add an X11 server]] to your server, if you need one. * Of course we have a [[e-mail server section]], where we focus on Postfix and virtual mail domains, and add in a whiff of MySQL and OpenLDAP. * The [[Asterisk section]] is about all things re: telephony on Debian Lenny. * The [[system boot procedure]] section explains what we can customise in the standard ways Debian boots. * The [[networking section]] treats subjects like setting persistent routes. * The [[firewall section]] is where we discuss "IPtables" (netfilter) and how we use it for firewalling. * The [[native IPsec tunnel]] section describes how to configure an IPsec tunnel. * [[Hardware monitoring]] is important for your server's health and reliability. * [[Vmware_server|VMware Server basics]] gives some pointers on how to install VMware Server on a Debian server box. * Make your server a [[Microsoft PPTP server | Microsoft client compatible VPN Server ]]. * Creating a [[backup]] for your server. * How to install [[Mediawiki Installation | Mediawiki]] on your Debian server - like what you're looking at now. * How to [[DLNA server|create your own multimedia server]], supporting [http://www.dlna.org/ DLNA] (which is [http://hometheater.about.com/od/interactivetelevision/a/Samsung-Allshare-Media-Streaming-basics-bg.htm Samsung's "AllShare"]) If you'd like to create a new page, please log in and go ahead: <inputbox> type=create </inputbox> ---- '''Note''': the Wiki admins reserve the right to edit or remove any content they feel is not suitable for this site, not relevant, (too) inaccurate or otherwise not in line with the intentions and spirit of the admin team. ---- <websiteFrame> website=http://www.google.com/talk/service/badge/Show?tk&#61;z01q6amlqld8jocej2ca891jl9dunqqra83nhehaoqpednb5skkur0fv70jsuavce4ii9ms5e9afdr8qmpsc1d9upni4jom8g1em3p1cvq1p5eo1ugv162fosgprdv867iuememlcogfle8n3dmcf97durjld85avnh8k5lm1&amp;w=200&amp;h=60 border=0 height=60 width=200 name=GoogleChatwithSaruman! allowtransparency=true </websiteFrame> 0af76cc299d87ceed805bf81161e130424485541 0 1635 2739 2012-08-05T15:19:01Z Saruman! 2 start wikitext text/x-wiki Target of this section of the wiki is to explain how to install and configure your Debian server so that it can act as a multimedia repository for your DLNA-capable equipment. In this case, we're going to optimize our DLNA server for a Samsung SmartTV, which supports Samsung's "AllShare", a slightly extended variant of DLNA. We start out by downloading the latest version of MiniDLNA from its [http://sourceforge.net/projects/minidlna/files/ SourceForge website]. At the time of writing, it's version 1.0.25. This file is extracted to the '''/usr/src/''' directory: '''localhost:/usr/src# ''tar xzf minidlna_1.0.25_src.tar.gz'' localhost:/usr/src# ''cd minidlna-1.0.25/'' localhost:/usr/srcminidlna-1.0.25# ''make'' ./genconfig.sh ERROR! Cannot continue. The following required libraries are either missing, or are missing development headers: libavcodec libavformat libavutil libflac libvorbis libogg libid3tag libexif libjpeg make: *** [config.h] Error 1 localhost:/usr/srcminidlna-1.0.25# ''_''''' MiniDLNA has some dependencies; executing the '''make''' command has shown us which dependencies are unfulfilled (your list will probably differ). After installing all packages that MiniDLNA needs, the output of '''make''' becomes: 02315785a38134c0c10c3c76b856d3e7086adeef 2741 2739 2012-08-05T15:51:05Z Saruman! 2 wikitext text/x-wiki Target of this section of the wiki is to explain how to install and configure your Debian server so that it can act as a multimedia repository for your DLNA-capable equipment. In this case, we're going to optimize our DLNA server for a Samsung SmartTV, which supports Samsung's "AllShare", a slightly extended variant of DLNA. We start out by downloading the latest version of MiniDLNA from its [http://sourceforge.net/projects/minidlna/files/ SourceForge website]. At the time of writing, it's version 1.0.25. This file is extracted to the '''/usr/src/''' directory: '''localhost:/usr/src# ''tar xzf minidlna_1.0.25_src.tar.gz'' localhost:/usr/src# ''cd minidlna-1.0.25/'' localhost:/usr/srcminidlna-1.0.25# ''make'' ./genconfig.sh ERROR! Cannot continue. The following required libraries are either missing, or are missing development headers: libavcodec libavformat libavutil libflac libvorbis libogg libid3tag libexif libjpeg make: *** [config.h] Error 1 localhost:/usr/srcminidlna-1.0.25# ''_''''' MiniDLNA has some dependencies; executing the '''make''' command has shown us which dependencies are unfulfilled (your list will probably differ). In the above case, the cure for the missing libraries is '''localhost:/usr/src# ''apt-get install libavcodec-dev libavformat-dev libflac-dev libvorbis-dev libexif-dev libjpeg-dev libid3tag0-dev''''' After installing all packages that MiniDLNA needs, the output of '''make''' becomes: '''dworkin:/usr/src/minidlna-1.0.25# ''make'' ./genconfig.sh Compiling minidlna.c Compiling upnphttp.c Compiling upnpdescgen.c Compiling upnpsoap.c Compiling upnpreplyparse.c Compiling minixml.c Compiling getifaddr.c Compiling daemonize.c Compiling upnpglobalvars.c Compiling options.c Compiling minissdp.c Compiling uuid.c Compiling upnpevents.c Compiling sql.c Compiling utils.c Compiling metadata.c Compiling scanner.c scanner.c: In function âinsert_containersâ: scanner.c:172: warning: format â%lXâ expects type âlong unsigned intâ, but argument 3 has type âsqlite_int64â scanner.c:195: warning: format â%lXâ expects type âlong unsigned intâ, but argument 3 has type âsqlite_int64â scanner.c:207: warning: format â%lXâ expects type âlong unsigned intâ, but argument 4 has type âsqlite_int64â scanner.c:276: warning: format â%lXâ expects type âlong unsigned intâ, but argument 3 has type âsqlite_int64â scanner.c:281: warning: format â%lXâ expects type âlong unsigned intâ, but argument 4 has type âsqlite_int64â scanner.c:297: warning: format â%lXâ expects type âlong unsigned intâ, but argument 4 has type âsqlite_int64â scanner.c:318: warning: format â%lXâ expects type âlong unsigned intâ, but argument 3 has type âsqlite_int64â scanner.c:323: warning: format â%lXâ expects type âlong unsigned intâ, but argument 4 has type âsqlite_int64â scanner.c:338: warning: format â%lXâ expects type âlong unsigned intâ, but argument 4 has type âsqlite_int64â Compiling inotify.c Compiling tivo_utils.c Compiling tivo_beacon.c Compiling tivo_commands.c Compiling tagutils/textutils.c Compiling tagutils/misc.c Compiling tagutils/tagutils.c Compiling playlist.c Compiling image_utils.c Compiling albumart.c Compiling log.c Linking minidlna Compiling testupnpdescgen.c Linking testupnpdescgen dworkin:/usr/src/minidlna-1.0.25# ''_''''' 8a05d1dbc88fff3a6e9a34a30172a90cbfc2c70b 2742 2741 2012-08-05T15:54:14Z Saruman! 2 wikitext text/x-wiki Target of this section of the wiki is to explain how to install and configure your Debian server so that it can act as a multimedia repository for your DLNA-capable equipment. In this case, we're going to optimize our DLNA server for a Samsung SmartTV, which supports Samsung's "AllShare", a slightly extended variant of DLNA. We start out by downloading the latest version of MiniDLNA from its [http://sourceforge.net/projects/minidlna/files/ SourceForge website]. At the time of writing, it's version 1.0.25. This file is extracted to the '''/usr/src/''' directory: localhost:/usr/src# '''tar xzf minidlna_1.0.25_src.tar.gz''' localhost:/usr/src# '''cd minidlna-1.0.25/''' localhost:/usr/srcminidlna-1.0.25# '''make''' ./genconfig.sh ERROR! Cannot continue. The following required libraries are either missing, or are missing development headers: libavcodec libavformat libavutil libflac libvorbis libogg libid3tag libexif libjpeg make: *** [config.h] Error 1 localhost:/usr/srcminidlna-1.0.25# '''_''' MiniDLNA has some dependencies; executing the ''make'' command has shown us which dependencies are unfulfilled (your list will probably differ). In the above case, the cure for the missing libraries is ''localhost:/usr/src# '''apt-get install libavcodec-dev libavformat-dev libflac-dev libvorbis-dev libexif-dev libjpeg-dev libid3tag0-dev''' '' After installing all packages that MiniDLNA needs, the output of ''make'' may be similar to: localhost:/usr/src/minidlna-1.0.25# '''make''' ./genconfig.sh Compiling minidlna.c Compiling upnphttp.c Compiling upnpdescgen.c Compiling upnpsoap.c Compiling upnpreplyparse.c Compiling minixml.c Compiling getifaddr.c Compiling daemonize.c Compiling upnpglobalvars.c Compiling options.c Compiling minissdp.c Compiling uuid.c Compiling upnpevents.c Compiling sql.c Compiling utils.c Compiling metadata.c Compiling scanner.c scanner.c: In function âinsert_containersâ: scanner.c:172: warning: format â%lXâ expects type âlong unsigned intâ, but argument 3 has type âsqlite_int64â scanner.c:195: warning: format â%lXâ expects type âlong unsigned intâ, but argument 3 has type âsqlite_int64â scanner.c:207: warning: format â%lXâ expects type âlong unsigned intâ, but argument 4 has type âsqlite_int64â scanner.c:276: warning: format â%lXâ expects type âlong unsigned intâ, but argument 3 has type âsqlite_int64â scanner.c:281: warning: format â%lXâ expects type âlong unsigned intâ, but argument 4 has type âsqlite_int64â scanner.c:297: warning: format â%lXâ expects type âlong unsigned intâ, but argument 4 has type âsqlite_int64â scanner.c:318: warning: format â%lXâ expects type âlong unsigned intâ, but argument 3 has type âsqlite_int64â scanner.c:323: warning: format â%lXâ expects type âlong unsigned intâ, but argument 4 has type âsqlite_int64â scanner.c:338: warning: format â%lXâ expects type âlong unsigned intâ, but argument 4 has type âsqlite_int64â Compiling inotify.c Compiling tivo_utils.c Compiling tivo_beacon.c Compiling tivo_commands.c Compiling tagutils/textutils.c Compiling tagutils/misc.c Compiling tagutils/tagutils.c Compiling playlist.c Compiling image_utils.c Compiling albumart.c Compiling log.c Linking minidlna Compiling testupnpdescgen.c Linking testupnpdescgen localhost:/usr/src/minidlna-1.0.25# '''_''' c2c9ea104342dba1719ec22433a34512e940ad77 2743 2742 2012-08-05T17:46:02Z Saruman! 2 wikitext text/x-wiki Target of this section of the wiki is to explain how to install and configure your Debian server so that it can act as a multimedia repository for your DLNA-capable equipment. In this case, we're going to optimize our DLNA server for a Samsung SmartTV, which supports Samsung's "AllShare", a slightly extended variant of DLNA. ==Compiling and installing== We start out by downloading the latest version of MiniDLNA from its [http://sourceforge.net/projects/minidlna/files/ SourceForge website]. At the time of writing, it's version 1.0.25. This file is extracted to the '''/usr/src/''' directory: localhost:/usr/src# '''tar xzf minidlna_1.0.25_src.tar.gz''' localhost:/usr/src# '''cd minidlna-1.0.25/''' localhost:/usr/srcminidlna-1.0.25# '''make''' ./genconfig.sh ERROR! Cannot continue. The following required libraries are either missing, or are missing development headers: libavcodec libavformat libavutil libflac libvorbis libogg libid3tag libexif libjpeg make: *** [config.h] Error 1 localhost:/usr/srcminidlna-1.0.25# '''_''' MiniDLNA has some dependencies; executing the ''make'' command has shown us which dependencies are unfulfilled (your list will probably differ). In the above case, the cure for the missing libraries is ''localhost:/usr/src# '''apt-get install libavcodec-dev libavformat-dev libflac-dev libvorbis-dev libexif-dev libjpeg-dev libid3tag0-dev''' '' After installing all packages that MiniDLNA needs, the output of ''make'' may be similar to: localhost:/usr/src/minidlna-1.0.25# '''make''' ./genconfig.sh Compiling minidlna.c Compiling upnphttp.c Compiling upnpdescgen.c Compiling upnpsoap.c Compiling upnpreplyparse.c Compiling minixml.c Compiling getifaddr.c Compiling daemonize.c Compiling upnpglobalvars.c Compiling options.c Compiling minissdp.c Compiling uuid.c Compiling upnpevents.c Compiling sql.c Compiling utils.c Compiling metadata.c Compiling scanner.c scanner.c: In function âinsert_containersâ: scanner.c:172: warning: format â%lXâ expects type âlong unsigned intâ, but argument 3 has type âsqlite_int64â scanner.c:195: warning: format â%lXâ expects type âlong unsigned intâ, but argument 3 has type âsqlite_int64â scanner.c:207: warning: format â%lXâ expects type âlong unsigned intâ, but argument 4 has type âsqlite_int64â scanner.c:276: warning: format â%lXâ expects type âlong unsigned intâ, but argument 3 has type âsqlite_int64â scanner.c:281: warning: format â%lXâ expects type âlong unsigned intâ, but argument 4 has type âsqlite_int64â scanner.c:297: warning: format â%lXâ expects type âlong unsigned intâ, but argument 4 has type âsqlite_int64â scanner.c:318: warning: format â%lXâ expects type âlong unsigned intâ, but argument 3 has type âsqlite_int64â scanner.c:323: warning: format â%lXâ expects type âlong unsigned intâ, but argument 4 has type âsqlite_int64â scanner.c:338: warning: format â%lXâ expects type âlong unsigned intâ, but argument 4 has type âsqlite_int64â Compiling inotify.c Compiling tivo_utils.c Compiling tivo_beacon.c Compiling tivo_commands.c Compiling tagutils/textutils.c Compiling tagutils/misc.c Compiling tagutils/tagutils.c Compiling playlist.c Compiling image_utils.c Compiling albumart.c Compiling log.c Linking minidlna Compiling testupnpdescgen.c Linking testupnpdescgen localhost:/usr/src/minidlna-1.0.25# '''_''' After succesful compilation, we can simply install with localhost:/usr/src/minidlna-1.0.25# '''make install''' install -d /usr/sbin install minidlna /usr/sbin localhost:/usr/src/minidlna-1.0.25# '''_''' ==Starting MiniDLNA== dce6b6384bd4a7bde739676f5f4ec5cc11d850c1 0 1488 2744 2444 2012-08-16T09:33:33Z Saruman! 2 /* CA.sh - certificate creation made easy */ typo's wikitext text/x-wiki ==Preparing for certificate creation== When we're going to create certificates, we're going to use the ''openssl'' command twice: * once to create a "certificate signing request", in which we define all information to be included in the certificate, and actually generate the public and private key parts of the key pair, and * once to instruct the OpenSSL package to sign the certificate with our CA root certificate. The first step thus '''creates''' the actual keypair, and the second step '''signs''' the public key. However, we're going to need to input a lot of parameters on the ''openssl'' command line. We can make things a bit easier for us by specifying these in the ''openssl.cnf'' file, just as we have added some values when creating the CA itself. To be precise, we're going to add '''X.509 V3 extensions''' By default OpenSSL generates V1 certificates, but if we're not extremely worried about offending certain ancient web browsers, we can add V3 extensions, and even make ''openssl'' do that by default. To do this, we find in ''/etc/ssl/openssl.cnf'' the following line in the section ''[ req ]'', which is likely present but commented out: req_extensions = v3_req # The extensions to add to a certificate request Simply remove the # sign in front of it, so that it appears as given above. This by default enables V3 extensions. Furthermore, check the section ''[ v3_req ]''. It should look like this: [ v3_req ] # Extensions to add to a certificate request basicConstraints = CA:FALSE keyUsage = nonRepudiation, digitalSignature, keyEncipherment subjectKeyIdentifier = hash What is added is the last line, with ''subjectKeyIdentifier''; this line specifies how to identify the public key being certified, so that distinct keys used by the same subject can be differentiated (e.g. as key updating occurs, for example). Four values are possible, but the IETF Public Key Infrastructure (PKIX) working group recommends the setting ''subjectKeyIdentifier=hash'' ==Creating an SSL certificate== Now we can create an SSL certificate for a web server. For the Common Name of the certificate, we need the '''exact''' name of the web server that'll offer the SSL connections. However, some servers run different websites as Virtual Hosts, so they could be running, for example, www.saruman.biz, as well as shop.saruman.biz. That might present a problem, because if the certificate is issued for www.saruman.biz, then each visitor of shop.saruman.biz will get a warning along the lines of "Warning: The website you're trying to visit is shop.saruman.biz, but the certificate offered is for www.saruman.biz". To prevent that, we could use the wildcard character in the name of the certificate, so as to generate a certificate for *.saruman.biz. === CA.sh - certificate creation made easy=== Since we have the ''openssl.cnf'' set up just right, and the ''CA.sh'' script primed, generating an SSL certificate is not very hard. From any old directory, run as root /usr/lib/ssl/misc/CA.sh -newreq This will create the signing request. The questions it'll ask, are * a PEM passphrase, with which to protect the private key of the key pair. Note: you cannot generate a signing request without passphrase, so the private key you'll generate will ''always'' have a passphrase. If this is not what you want, do not despair: you can easily remove the passphrase from the private key after it's been generated (see further down). So just use a passphrase, even if you don't need one. * Country/State/Locality/Organization/Organizational Unit; just as with the CA root certificate creation, these have your preprogrammed defaults that you may or may not change. * Common Name; here we MUST give the DNS name of the host that is going to use the certificate, e.g. ''shop.saruman.biz'', or ''*.saruman.biz''. * Challenge password; leave it blank, it's just to protect your signing request while en-route to the CA - but that's you anyway :-) * Optional company name; leave that blank too, it's also extra information for the CA. Now your private key and your certificate signing request (CSR) are ready; they're called ''newkey.pem'' and ''newreq.pem'' by default, and are located in your working directory. Time to do some signing! From that same working directory, run /usr/lib/ssl/misc/CA.sh -sign The script will show that it's using the config file ''/usr/lib/ssl/openssl.cnf'' (as we indeed wish), and then ask for the super-duper-secret passphrase to the CA private key (provided you've left that in directory ''/etc/ssl/ca/private''). Feed the script the passphrase, and it'll get to work. It'll check the request, then show you the details of the certificate you're about to sign. An example would be Certificate Details: Serial Number: 1 (0x1) Validity Not Before: Oct 27 09:34:00 2008 GMT Not After : Nov 1 09:34:00 2009 GMT Subject: countryName = NL stateOrProvinceName = Utrecht organizationName = Saruman.biz organizationalUnitName = Internet Dept. commonName = shop.saruman.biz emailAddress = webmaster@saruman.biz X509v3 extensions: X509v3 Basic Constraints: CA:FALSE Netscape Comment: OpenSSL Generated Certificate X509v3 Subject Key Identifier: 30:F2:61:80:AA:CF:1B:F0:3E:44:41:D6:38:CC:31:F0:94:28:BD:2B X509v3 Authority Key Identifier: keyid:80:41:F8:A5:1F:C2:27:6E:CF:A9:28:8E:8A:EF:83:E7:FD:8A:D5:26 Certificate is to be certified until Nov 1 09:34:00 2009 GMT (370 days) Sign the certificate? [y/n]: After doing your CA duty and diligently checking all the data, just press ''y''. The script certifies the request, and asks if it is to commit the request. This means it'll update it's own database, by saving a copy of the signed certificate in ''/etc/ssl/ca/newcerts'' named after its serial number (''01.pem'' for this example). Furthermore the script will record the serial and ID's of the generated certificate so that the next certificate will have a new serial number. And now: hey presto! We have a ''newcert.pem'' in our working directory! For good measure: * delete ''newreq.pem'' * rename the generated private key ''newkey.pem'' to ''shop.saruman.biz.seckey.pem'' * rename the generated public certificate ''newcert.pem'' to ''shop.saruman.biz.pem'' To remove the passphrase from the private key, use a command like this: openssl rsa -in shop.saruman.biz.seckey.pem -out shop.saruman.biz.nokey.pem This will make ''openssl'' ask for your passphrase, and then create the unsecured ''shop.saruman.biz.nokey.pem'' key file. Best practice: ALWAYS use a passphrase-protected key, unless the application cannot support it (e.g. Postfix). Save the secure private key and its PEM passphrase in a safe place (e.g. Keepass database). And if you removed the passphrase from the private key, then store it in an even safer place! Now you can deploy your certificate. (more on that in another section). === openssl - the hard way to certificate creation=== We don't actually need to use the ''CA.sh'' script, because we can do manually what the ''CA.sh'' script does. That gives us more control, but also more work. Let's see what we've got to do. We will now perform the first step in our "manual" certificate generation: we create a signing request with all the information that we want in our SSL certificate. We run the magic incantation - note how we already openssl req -new -nodes -keyout webmail.saruman.biz.key.pem -out webmail.saruman.biz.req.pem This generates a new private key (named ''webmail.saruman.biz.key.pem''), and a new, non-encrypted (because of ''-nodes''), key signing request named ''webmail.saruman.biz.req.pem''. We can leave out terms like ''-newkey rsa:2048'' and ''-days 370'' since we've put that in the configuration file. And naturally you're free to choose your own names for the keys. FIXME - need the full process here === Validating the generated certificates=== Again, we can use the ''openssl'' command to validate the keys we've generated. For instance, the ''CA.sh'' generated certificate, after renaming, is verified with openssl x509 -in shop.saruman.biz.pem -noout -purpose Certificate purposes: SSL client : Yes SSL client CA : No SSL server : Yes SSL server CA : No Netscape SSL server : Yes Netscape SSL server CA : No S/MIME signing : Yes S/MIME signing CA : No S/MIME encryption : Yes S/MIME encryption CA : No CRL signing : Yes CRL signing CA : No Any Purpose : Yes Any Purpose CA : Yes OCSP helper : Yes OCSP helper CA : No Notice that the certificate is valid for everything except CA tasks. Likewise, using ''-dates'' instead of ''-purpose'' lets you see the validity time period, and ''-text'' gives the whole text of the certificate. Note the line marked "issuer", and see how your own CA is referenced there. 59ca2feaf90a4b6359aa3d3f823cf6a7e16d4a32 5 1636 2745 2012-10-03T17:23:24Z 151.67.101.210 0 Created page with "hello m8 my antivirus maybe dont allow me to see all stuff in ur server ..should i login ? register?" wikitext text/x-wiki hello m8 my antivirus maybe dont allow me to see all stuff in ur server ..should i login ? register? 99536460372579965dbfa6747d552aa62d9d6438 2746 2745 2012-10-03T17:58:26Z Saruman! 2 aw wikitext text/x-wiki hello m8 my antivirus maybe dont allow me to see all stuff in ur server ..should i login ? register? : Heya, antivirus shouldn't block any content. Also, logging in won't allow you to see more, only to post without captcha. Maybe your browser blocks Javascript? The MediaWiki software uses some of that... By the way, there's not much more on this site than this wiki that records Linux bits'n'bobs... --[[User:Saruman!|Saruman!]] 19:58, 3 October 2012 (CEST) 99bc576817118f82cb9bc1da0d0ac7056e4a1f3b 1 1607 2748 2559 2013-05-03T04:08:17Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 3 1638 2749 2013-05-04T21:24:50Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2750 2749 2013-05-04T21:24:57Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 3 1639 2751 2013-05-04T21:25:25Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2752 2751 2013-05-04T21:25:35Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 5 1640 2753 2013-05-04T21:25:57Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2754 2753 2013-05-04T21:26:07Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1641 2755 2013-05-04T21:27:05Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2756 2755 2013-05-04T21:27:16Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 13 1642 2757 2013-05-04T21:27:47Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2758 2757 2013-05-04T21:27:56Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 5 1643 2759 2013-05-04T21:28:16Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2760 2759 2013-05-04T21:28:30Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 5 1644 2761 2013-05-04T21:28:44Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2762 2761 2013-05-04T21:28:52Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 5 1645 2763 2013-05-04T21:29:03Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2764 2763 2013-05-04T21:29:11Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 5 1646 2765 2013-05-04T21:29:43Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2766 2765 2013-05-04T21:29:54Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 5 1647 2767 2013-05-04T21:30:59Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2768 2767 2013-05-04T21:31:07Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 5 1636 2769 2746 2013-05-04T21:31:32Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 13 1648 2770 2013-05-04T21:31:50Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2771 2770 2013-05-04T21:32:06Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 103 1649 2772 2013-05-04T21:32:27Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2773 2772 2013-05-04T21:32:38Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 11 1650 2774 2013-05-04T21:33:37Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2775 2774 2013-05-04T21:33:44Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 5 1651 2776 2013-05-04T21:34:10Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2777 2776 2013-05-04T21:34:21Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1652 2778 2013-05-04T21:34:41Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2779 2778 2013-05-04T21:34:51Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 15 1653 2780 2013-05-04T21:35:17Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2781 2780 2013-05-04T21:35:29Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1654 2782 2013-05-04T21:36:08Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2783 2782 2013-05-04T21:36:17Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1655 2784 2013-05-04T21:36:30Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2785 2784 2013-05-04T21:36:37Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 11 1656 2786 2013-05-04T21:37:18Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2787 2786 2013-05-04T21:37:25Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 11 1657 2788 2013-05-04T21:37:39Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2789 2788 2013-05-04T21:37:50Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 5 1658 2790 2013-05-04T21:38:10Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2791 2790 2013-05-04T21:38:18Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1659 2792 2013-05-04T21:38:35Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2793 2792 2013-05-04T21:38:42Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1660 2794 2013-05-04T21:38:59Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2795 2794 2013-05-04T21:39:09Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 3 1661 2796 2013-05-04T21:39:38Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2797 2796 2013-05-04T21:39:48Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1662 2798 2013-05-04T21:42:21Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2799 2798 2013-05-04T21:42:28Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1663 2800 2013-05-04T21:42:42Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2801 2800 2013-05-04T21:42:51Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1664 2802 2013-05-04T21:43:05Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2803 2802 2013-05-04T21:43:13Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1665 2804 2013-05-04T21:43:27Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2805 2804 2013-05-04T21:43:34Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1666 2806 2013-05-04T21:43:47Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2807 2806 2013-05-04T21:43:55Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1627 2808 2712 2013-05-04T21:44:08Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 3 1667 2809 2013-05-04T21:44:22Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2810 2809 2013-05-04T21:44:29Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 9 1668 2811 2013-05-04T21:44:46Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2812 2811 2013-05-04T21:44:55Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 9 1669 2813 2013-05-04T21:45:19Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2814 2813 2013-05-04T21:45:25Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 9 1670 2815 2013-05-04T21:45:38Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2816 2815 2013-05-04T21:45:44Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1671 2817 2013-05-04T22:11:09Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2818 2817 2013-05-04T22:11:19Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1672 2819 2013-05-04T22:11:39Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2820 2819 2013-05-04T22:11:47Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1673 2821 2013-05-04T22:12:02Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2822 2821 2013-05-04T22:12:12Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1674 2823 2013-05-04T22:12:27Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2824 2823 2013-05-04T22:12:34Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1675 2825 2013-05-04T22:12:51Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2826 2825 2013-05-04T22:13:00Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1676 2827 2013-05-04T22:13:17Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2828 2827 2013-05-04T22:13:26Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1677 2829 2013-05-04T22:13:41Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2830 2829 2013-05-04T22:13:49Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1678 2831 2013-05-04T22:14:24Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2832 2831 2013-05-04T22:14:30Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1679 2833 2013-05-04T22:14:45Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2834 2833 2013-05-04T22:14:55Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1680 2835 2013-05-04T22:15:22Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2836 2835 2013-05-04T22:15:28Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1681 2837 2013-05-04T22:15:47Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2838 2837 2013-05-04T22:15:53Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 3 1682 2839 2013-05-04T22:16:25Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2840 2839 2013-05-04T22:16:34Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1632 2841 2734 2013-05-04T22:16:50Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1683 2842 2013-05-04T22:17:15Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2843 2842 2013-05-04T22:17:23Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1684 2844 2013-05-04T22:17:38Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2845 2844 2013-05-04T22:17:45Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1685 2846 2013-05-04T22:18:13Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2847 2846 2013-05-04T22:18:20Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1686 2848 2013-05-04T22:18:44Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2849 2848 2013-05-04T22:18:51Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 3 1687 2850 2013-05-04T22:19:43Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2851 2850 2013-05-04T22:19:51Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1688 2852 2013-05-04T22:20:02Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2853 2852 2013-05-04T22:20:09Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1689 2854 2013-05-04T22:20:27Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2855 2854 2013-05-04T22:20:35Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1690 2856 2013-05-04T22:20:53Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2857 2856 2013-05-04T22:20:59Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1691 2858 2013-05-04T22:21:22Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2859 2858 2013-05-04T22:21:31Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1692 2860 2013-05-04T22:21:48Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2861 2860 2013-05-04T22:21:55Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1693 2862 2013-05-04T22:22:28Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 1 1693 2863 2862 2013-05-04T22:22:34Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1694 2864 2013-05-04T22:22:59Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2865 2864 2013-05-04T22:23:06Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1695 2866 2013-05-04T22:23:23Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2867 2866 2013-05-04T22:23:30Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1696 2868 2013-05-04T22:24:09Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2869 2868 2013-05-04T22:24:19Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 7 1697 2870 2013-05-04T22:24:51Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2871 2870 2013-05-04T22:24:59Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1698 2872 2013-05-04T22:25:14Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2873 2872 2013-05-04T22:25:21Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1699 2874 2013-05-04T22:25:39Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2875 2874 2013-05-04T22:25:47Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1700 2876 2013-05-04T22:25:58Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2877 2876 2013-05-04T22:26:04Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1701 2878 2013-05-04T22:26:21Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2879 2878 2013-05-04T22:26:34Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1702 2880 2013-05-04T22:26:50Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2881 2880 2013-05-04T22:26:58Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1703 2882 2013-05-04T22:27:14Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2883 2882 2013-05-04T22:27:21Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1704 2884 2013-05-04T22:28:07Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2885 2884 2013-05-04T22:28:14Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1705 2886 2013-05-04T22:28:28Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2887 2886 2013-05-04T22:28:34Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1706 2888 2013-05-04T22:28:56Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2889 2888 2013-05-04T22:29:02Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1707 2890 2013-05-04T22:29:22Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2891 2890 2013-05-04T22:29:28Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1708 2892 2013-05-04T22:29:52Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2893 2892 2013-05-04T22:29:59Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1709 2894 2013-05-04T22:30:13Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2895 2894 2013-05-04T22:30:19Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1710 2896 2013-05-04T22:30:36Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2897 2896 2013-05-04T22:30:44Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1711 2898 2013-05-04T22:31:04Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2899 2898 2013-05-04T22:31:11Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1712 2900 2013-05-04T22:31:23Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2901 2900 2013-05-04T22:31:29Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1713 2902 2013-05-04T22:31:49Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2903 2902 2013-05-04T22:31:56Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1714 2904 2013-05-04T22:32:07Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2905 2904 2013-05-04T22:32:13Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1715 2906 2013-05-04T22:32:36Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2907 2906 2013-05-04T22:32:47Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1716 2908 2013-05-04T22:33:07Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2909 2908 2013-05-04T22:33:15Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1717 2910 2013-05-04T22:33:46Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2911 2910 2013-05-04T22:33:52Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1718 2912 2013-05-04T22:34:24Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 1 1718 2913 2912 2013-05-04T22:34:30Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1719 2914 2013-05-04T22:34:48Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2915 2914 2013-05-04T22:34:54Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1720 2916 2013-05-04T22:35:28Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2917 2916 2013-05-04T22:35:33Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1721 2918 2013-05-04T22:35:48Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2919 2918 2013-05-04T22:36:00Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1722 2920 2013-05-04T22:36:25Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2921 2920 2013-05-04T22:36:31Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1723 2922 2013-05-04T22:36:43Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2923 2922 2013-05-04T22:36:50Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1724 2924 2013-05-04T22:38:20Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2925 2924 2013-05-04T22:38:30Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 3 1725 2926 2013-05-04T22:51:15Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2927 2926 2013-05-04T22:51:31Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1726 2928 2013-05-04T22:52:08Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2929 2928 2013-05-04T22:52:19Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1727 2930 2013-05-04T22:52:38Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2931 2930 2013-05-04T22:52:49Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 5 1728 2932 2013-05-04T22:53:19Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2933 2932 2013-05-04T22:53:27Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 5 1729 2934 2013-05-04T22:53:45Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2935 2934 2013-05-04T22:53:53Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 5 1730 2936 2013-05-04T22:54:08Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2937 2936 2013-05-04T22:54:14Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 5 1731 2938 2013-05-04T22:54:26Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2939 2938 2013-05-04T22:54:33Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 3 1732 2940 2013-05-04T22:54:56Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2941 2940 2013-05-04T22:55:06Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 3 1733 2942 2013-05-04T22:55:23Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2943 2942 2013-05-04T22:55:30Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 3 1734 2944 2013-05-04T22:56:02Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2945 2944 2013-05-04T22:56:10Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 3 1735 2946 2013-05-04T22:56:25Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2947 2946 2013-05-04T22:56:31Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 3 1736 2948 2013-05-04T22:56:44Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2949 2948 2013-05-04T22:56:53Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 3 1737 2950 2013-05-04T22:57:21Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2951 2950 2013-05-04T22:57:28Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 3 1738 2952 2013-05-04T22:57:41Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2953 2952 2013-05-04T22:57:50Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 3 1739 2954 2013-05-04T22:58:03Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2955 2954 2013-05-04T22:58:15Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 3 1740 2956 2013-05-04T22:58:35Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2957 2956 2013-05-04T22:58:51Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 3 1741 2958 2013-05-04T22:59:08Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2959 2958 2013-05-04T22:59:20Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 3 1742 2960 2013-05-04T22:59:35Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2961 2960 2013-05-04T22:59:42Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 3 1743 2962 2013-05-04T22:59:56Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 3 1743 2963 2962 2013-05-04T23:00:09Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 3 1744 2964 2013-05-04T23:00:47Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2965 2964 2013-05-04T23:00:54Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 3 1745 2966 2013-05-04T23:01:07Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2967 2966 2013-05-04T23:01:13Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 3 1746 2968 2013-05-04T23:01:24Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2969 2968 2013-05-04T23:01:32Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 3 1747 2970 2013-05-04T23:01:43Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2971 2970 2013-05-04T23:01:54Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 3 1748 2972 2013-05-04T23:02:07Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2973 2972 2013-05-04T23:02:14Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 3 1749 2974 2013-05-04T23:02:25Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2975 2974 2013-05-04T23:02:32Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1750 2976 2013-05-04T23:03:07Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2977 2976 2013-05-04T23:03:15Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 3 1751 2978 2013-05-04T23:06:04Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2979 2978 2013-05-04T23:06:13Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1752 2980 2013-05-04T23:06:37Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2981 2980 2013-05-04T23:06:48Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 7 1753 2982 2013-05-04T23:07:42Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2983 2982 2013-05-04T23:07:51Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1754 2984 2013-05-04T23:08:30Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2985 2984 2013-05-04T23:08:38Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1755 2986 2013-05-04T23:08:55Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2987 2986 2013-05-04T23:09:03Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1756 2988 2013-05-04T23:09:17Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2989 2988 2013-05-04T23:09:27Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1757 2990 2013-05-04T23:09:42Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2991 2990 2013-05-04T23:09:50Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1758 2992 2013-05-04T23:10:12Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2993 2992 2013-05-04T23:10:20Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1759 2994 2013-05-04T23:10:53Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2995 2994 2013-05-04T23:11:00Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1760 2996 2013-05-04T23:11:14Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2997 2996 2013-05-04T23:11:22Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1761 2998 2013-05-04T23:11:38Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 2999 2998 2013-05-04T23:11:45Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1762 3000 2013-05-04T23:12:33Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 3001 3000 2013-05-04T23:12:42Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1763 3002 2013-05-04T23:13:02Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 3003 3002 2013-05-04T23:13:12Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1764 3004 2013-05-04T23:13:23Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 3005 3004 2013-05-04T23:13:31Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1765 3006 2013-05-04T23:13:44Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 3007 3006 2013-05-04T23:13:55Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 3 1766 3008 2013-05-04T23:15:13Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 3009 3008 2013-05-04T23:15:20Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 7 1767 3010 2013-05-04T23:16:09Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 3011 3010 2013-05-04T23:16:16Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 7 1768 3012 2013-05-04T23:16:29Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 7 1768 3013 3012 2013-05-04T23:16:35Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 7 1769 3014 2013-05-04T23:16:47Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 3015 3014 2013-05-04T23:16:55Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 7 1770 3016 2013-05-04T23:17:07Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 3017 3016 2013-05-04T23:17:14Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1771 3018 2013-05-04T23:17:48Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 3019 3018 2013-05-04T23:17:57Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1772 3020 2013-05-04T23:18:09Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 3021 3020 2013-05-04T23:18:14Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1773 3022 2013-05-04T23:20:27Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 3023 3022 2013-05-04T23:20:34Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1774 3024 2013-05-04T23:21:06Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 3025 3024 2013-05-04T23:21:14Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1775 3026 2013-05-04T23:21:37Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 3027 3026 2013-05-04T23:21:47Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1776 3028 2013-05-04T23:22:28Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 3029 3028 2013-05-04T23:22:34Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1777 3030 2013-05-04T23:22:53Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 3031 3030 2013-05-04T23:23:00Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1778 3032 2013-05-04T23:23:13Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 3033 3032 2013-05-04T23:23:20Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1779 3034 2013-05-04T23:23:37Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 3035 3034 2013-05-04T23:23:45Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1780 3036 2013-05-04T23:24:06Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 3037 3036 2013-05-04T23:24:14Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1781 3038 2013-05-04T23:24:30Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 3039 3038 2013-05-04T23:24:36Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1782 3040 2013-05-04T23:25:17Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 3041 3040 2013-05-04T23:25:25Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1783 3042 2013-05-04T23:25:57Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 3043 3042 2013-05-04T23:26:04Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 3 1784 3044 2013-05-04T23:26:47Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 3045 3044 2013-05-04T23:26:54Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1785 3046 2013-05-05T00:30:36Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 3047 3046 2013-05-05T00:30:47Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1786 3048 2013-05-05T00:31:46Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 3049 3048 2013-05-05T00:32:02Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1787 3050 2013-05-05T00:34:27Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 3051 3050 2013-05-05T00:34:35Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1788 3052 2013-05-05T00:35:12Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 3053 3052 2013-05-05T00:35:23Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 3 1789 3054 2013-05-05T00:36:29Z 216.154.70.149 0 Created page with "." wikitext text/x-wiki . 3a52ce780950d4d969792a2559cd519d7ee8c727 3055 3054 2013-05-05T00:36:46Z 216.154.70.149 0 Blanked the page wikitext text/x-wiki da39a3ee5e6b4b0d3255bfef95601890afd80709 1 1607 3056 2748 2013-05-11T13:14:38Z Saruman! 2 Reverted edits by [[Special:Contributions/216.154.70.149|216.154.70.149]] ([[User talk:216.154.70.149|talk]]) to last revision by [[User:Saruman!|Saruman!]] wikitext text/x-wiki You are most welcome to discuss this wiki, but please keep the discussion relevant --[[User:Saruman!|Saruman!]] 10:02, 29 March 2010 (UTC) bd6c821c17e08fdda5e19137dce60556925c398f 0 1466 3058 2711 2013-06-03T03:54:11Z Saruman! 2 /* MySQL commands */ userdrop wikitext text/x-wiki == MySQL installation == As with any package to be installed: use aptitude, update your APT, then make sure all your (other) software is up-to-date. Then find package ''mysql-server'' - under Debian 5.0 "Lenny" it'll be version 5.0.51a-something. Installing it will also automatically install some dependent packages, like mysql-common, mysql-client etcetera. So after downloading some 40MiB of files, MySQL is installed. The installation script under Debian Lenny asks you for a password for the MySQL root user. Think up a strong password for the MySQL root user; something like ''waYacUbaT2uW''. DON'T use this example password, [http://www.pctools.com/guides/password/ generate your own one!]. DO NOT use the password of the Linux ''root'' user. Should you consult [http://dev.mysql.com/doc/refman/5.0/en/unix-post-installation.html the official MySQL documentation], you might see mention of the ''mysql_install_db'' script - do not worry about that, since Debian has run it for you when it was setting up the database. The standard user accounts that have been created by the installation script are: * 'root'@'localhost' * 'root'@'<hostname>' * 'root'@'127.0.0.1' All three root accounts are secured with the same password, the one you specified when installing the package ''mysql-server''. ---- '''NOTE for Debian 4.0 "Etch"''' When you install MySQL under Etch, there are two root accounts with empty passwords, and two anonymous accounts. NOT safe! You'll want to rectify this in order to secure your MySQL server. Please take the following steps. Start the MySQL client from the command line: mysql -u root Then, from the mysql client prompt, set the password for the MySQL root users. They can be treated as two different accounts, but we don't recommend that. We thus give both accounts the same password: mysql> SET PASSWORD FOR 'root'@'localhost' = PASSWORD('waYacUbaT2uW'); mysql> SET PASSWORD FOR 'root'@'<hostname>' = PASSWORD('waYacUbaT2uW'); Furthermore, there are two anonymous accounts created. These also have no password, and get full permission on the ''test'' database, as well as on any database who's name begins with ''test_''. These accounts can be fitted with a password (like we did for root - just use two quotes with nothing in between them, instead of two quotes with ''root'' in between), or they can be removed - which we recommend. The (single) command for this is: <pre>mysql> DROP USER '';</pre> '''End of NOTE''' ---- To verify the installation you might want to take some of the following steps: * run ''mysqlshow -u root -p'', and see if that command outputs at least two databases (''information_schema'' and ''mysql''); * check out the settings of your MySQL server by running ''mysqladmin -u root -p variables'' (piping the output to ''less'' or a file, if necessary); * have a peek in ''/var/lib/mysql''; the database data files should be there; * check ''/var/log'' for two logfiles ''mysql.err'' and ''mysql.log''. ==Moving the MySQL databases== By default the location of your Debian MySQL databases is ''/var/lib/mysql/<database>''. However, sometimes you wish your databases to be in a different location. E.g. ''/data/mysql'', where ''/data'' is a mounted dedicated RAID array. Or perhaps even ''/data/mysql'' is its own array. Whatever the reason, to move ''all'' MySQL databases from ''/var/lib/mysql'' to another location, you can follow these steps: * Create the new directory, e.g. ''/data/mysql'' * Make this directory owned by user/group ''mysql'' cd /data mkdir mysql chown mysql:mysql mysql * Shut down the database server with one of the following commands: mysqladmin -u root -p shutdown invoke-rc.d mysql stop * Make a backup copy of ''/etc/mysql/my.cnf'', then edit this file. Find the section ''[mysqld]'' and change the line ''datadir = /var/lib/mysql'' to datadir = /data/mysql * As root, move (or better yet: copy) ''all'' of the content of ''/var/lib/mysql'' over to ''/data/mysql''. Make sure you don't accidentally change the ownership or permissions of the files and folders in the ''/var/lib/mysql'' folder. We expect each and every file and folder to be owned by ''mysql:mysql''. Copy command would be (as root): cp -p -r /var/lib/mysql/* /data/mysql * Check and doublecheck your ''my.cnf'' settings and your database file owners, attributes and size. After the next step, there ''may'' be no way back! * Start up your database server: invoke-rc.d mysql start * Check the working of your MySQL server: ** issue the following command to get status information (to see if MySQL is running after your start command): invoke-rc.d mysql status ** look under ''/var/log'' for the default MySQL log files ''mysql.log'' and ''mysql.err'' ** check your SysLog (standard: ''/var/log/syslog'') for MySQL error messages, since the default Debian configuration is to log MySQL errors there, rather than in the previously mentioned MySQL logfiles. == MySQL commands == The following are examples of the most common MySQL commands <pre><nowiki> SELECT User,Host from mysql.user; SHOW GRANTS FOR '<user>'@'<host>'; GRANT <right>, <right2> ON <database>.* TO '<user>'@'<host>'; REVOKE <right>, <right2> ON <database>.* FROM '<user>'@'<host>'; DROP USER '<user>'@'<host>'; SHOW DATABASES; USE <database>; SHOW TABLES; DESCRIBE <table>; SELECT <col1>,<col2>...<col_i> FROM <table> WHERE <column> = '<value>'; INSERT INTO <table> (<col1>,<col2>...<col_i>) VALUES ('<val1>','<val2>'...'<val_i>'); UPDATE <table> set <col1> = '<value1>' WHERE <column> = '<value>'; DELETE FROM <table> WHERE <column> = '<value>'; </nowiki></pre> Ofcourse there are more useful commands, see the MySQL website. a8c5c7470d12c6547258dbdbc8427b209a0ef649 0 1 3059 2738 2014-01-04T09:24:19Z Saruman! 2 rearrange and add ownCloud wikitext text/x-wiki <big>'''Welcome to SaruWiki.'''</big> This Wiki is intended to document bits and bobs about [http://www.kernel.org/ Linux] (and some Unix) in general, and [http://www.debian.org Debian] in particular. In it, [[SaruWiki:About|we]] wish to collect the tips and tricks of both [[SaruWiki:About|our own team of Linux admins]] and those of other interested users. If you are interested in my work on [http://www.dya.info DYA|Infrastructure], please visit the [https://dya-knowledge.sogeti.nl/ SmartMart demo site]. Consult the [http://meta.wikimedia.org/wiki/Help:Contents User's Guide] for information on using this wiki's software. <big>NOTE:</big> '''you must confirm edits''' when you're not logged in with a user account. Thanks to the Mediawiki ConfirmEdit extension we've cut our wikispam considerably. Sorry to make you anonymous contributors jump through this little hoop for every edit, but there you are. ---- <big>'''Main Content'''</big> * Setting up a [[Debian Squeeze base server]] is a howto on the installation of a very basic Linux box under Lenny (it's actually not even a server yet). * Using ''md'' for [[software-based RAID]] contains our ideas and observations on redundancy. * The use of [[APT and aptitude]] is crucial to the concept of a Debian machine. * [[Roll your own kernel]] discusses the pros and cons of compiling your own kernel, and how to do it. * [[Essential system software]] lists all (sets of) packages that we deem, well, essential. * The [[system boot procedure]] section explains what we can customise in the standard ways Debian boots. * The [[networking section]] treats subjects like setting persistent routes. * The [[firewall section]] is where we discuss "IPtables" (netfilter) and how we use it for firewalling. * The [[native IPsec tunnel]] section describes how to configure an IPsec tunnel. * [[Hardware monitoring]] is important for your server's health and reliability. * Make your server a [[Microsoft PPTP server | Microsoft client compatible VPN Server ]]. * Creating a [[backup]] for your server. '''Authentication and security''' * [[Certificate fundamentals | The "certificates" section]] explains how you create your own Certificate Authority (CA) and the neat things you can do with it. * [[OpenLDAP]] is a rudimentary howto about getting OpenLDAP to be your central user repository. * [[Pluggable Authentication Modules (PAM)]] is a great way to secure your server and arrange logins - if you get to understand them '''Your own LAMP server''' * [[Apache2 and PHP5]] are essential packages if you want to light your own little [[LAMP]]. * [[Database 101]] introduces you to MySQL. '''Other server apps''' * The [[Installing SaMBa with OpenLDAP support | SaMBa section]] explains how to install SaMBa with OpenLDAP as user backend. * [[Add an X11 server]] to your server, if you need one. * Of course we have a [[e-mail server section]], where we focus on Postfix and virtual mail domains, and add in a whiff of MySQL and OpenLDAP. * The [[Asterisk section]] is about all things re: telephony on Debian Lenny. * [[Vmware_server|VMware Server basics]] gives some pointers on how to install VMware Server on a Debian server box. * How to install [[Mediawiki Installation | Mediawiki]] on your Debian server - like what you're looking at now. * How to [[DLNA server|create your own multimedia server]], supporting [http://www.dlna.org/ DLNA] (which is [http://hometheater.about.com/od/interactivetelevision/a/Samsung-Allshare-Media-Streaming-basics-bg.htm Samsung's "AllShare"]) * How to create [[your own ownCloud]] server (and here's [http://www.thecomputerkid.com/2013/06/why-you-should-use-owncloud.html why] you should do this) ---- If you'd like to create a new page, please log in and go ahead '''Note''': the Wiki admins reserve the right to edit or remove any content they feel is not suitable for this site, not relevant, (too) inaccurate or otherwise not in line with the intentions and spirit of the admin team. 2f3b832c32210d3d5531df4a1726e547055c4cac 0 1790 3060 2014-01-04T09:59:26Z Saruman! 2 start wikitext text/x-wiki <big>'''ownCloud'''</big> In this day and age where many people are more and more dependant on information, cloud technology offers a way to unlock your information to you, wherever you are, on most any device. However, there's no telling what the cloud companies that you entrust with your information will do with that info - let alone nosy intelligence agencies from various countries around the world. My privacy [https://chronicle.com/article/Why-Privacy-Matters-Even-if/127461/ matters to me]! '''[http://owncloud.org/ ownCloud]''' is a free and open source alternatives for many cloud offerings such as Google Drive and DropBox, as it gives you the ability to share and sync files from your own server, but it does [http://owncloud.org/features/ much more] - added bonus, I say... ___TOC___ ==Introduction== ownCloud broadly comes in two flavours: the open source, free "community edition" and the open source, paid "enterprise edition". We're going to install the community edition here. The goal will be to have a way to share files between groups of people, most of which will have an account on our server. ==Installing ownCloud== ===Preparing your server=== ===Getting ownCloud files on your server=== ===Publishing ownCloud in Apache2=== ==Configuring ownCloud== ===Initial setup=== ===Using OpenLDAP as a backend=== ===Theming ownCloud=== eb750a54840d9f1c6e6ffe84922273270f75d9ad 3062 3060 2014-02-10T14:19:30Z Saruman! 2 /* Installing ownCloud */ fleshed out wikitext text/x-wiki <big>'''ownCloud'''</big> In this day and age where many people are more and more dependant on information, cloud technology offers a way to unlock your information to you, wherever you are, on most any device. However, there's no telling what the cloud companies that you entrust with your information will do with that info - let alone nosy intelligence agencies from various countries around the world. My privacy [https://chronicle.com/article/Why-Privacy-Matters-Even-if/127461/ matters to me]! '''[http://owncloud.org/ ownCloud]''' is a free and open source alternatives for many cloud offerings such as Google Drive and DropBox, as it gives you the ability to share and sync files from your own server, but it does [http://owncloud.org/features/ much more] - added bonus, I say... ___TOC___ ==Introduction== ownCloud broadly comes in two flavours: the open source, free "community edition" and the open source, paid "enterprise edition". We're going to install the community edition here. The goal will be to have a way to share files between groups of people, most of which will have an account on our server. ==Installing ownCloud== In the following we're going to install ownCloud manually, that is to say we're not going to use any Linux package manager such as Debian's [https://wiki.debian.org/Apt apt] or Red Hat/CentOS's [https://access.redhat.com/site/solutions/9934 yum], but we're going to manually put the necessary files on the server. This has the advantage of being able to use the very latest & greatest version of ownCloud, but the disadvantage requiring us to do the heavy lifting, install-wise as well as update-wise. However, as we'll see below, a manual installation takes relatively little effort. ===Preparing your server=== First off we have to ensure that our server complies with ownCloud's requirements, as shown in the [http://doc.owncloud.org/server/6.0/admin_manual/installation/installation_source.html administrator manual]. This means we'll require a working LAMP server with a sufficient recent version of PHP, MySQL and Apache. If we want to secure our ownCloud communications using SSL, we also need to have a good SSL certificate (preferably not a self-signed one as many applications choke on that signature) and have set up our Apache server to correctly use it. Furthermore, ownCloud needs the Apache module mod-rewrite; usually one can enable it with a command such as ''a2enmod rewrite''. ===Getting ownCloud files on your server=== Now we'll choose a directory in which the ownCloud files can live; as it's a manual package, the Linux Standards Base ([http://www.linuxfoundation.org/collaborate/workgroups/lsb LSB]) suggests it goes into ''/opt''. We thus create the directory ''/opt/owncloud''. Next up we download the ownCloud ''tar.bz2'' file from the [http://owncloud.org/install/ ownCloud download page] to a temporary directory and extract it; this could look like cd /tmp wget http://download.owncloud.org/community/owncloud-6.0.1.tar.bz2 tar -xjf owncloud-6.0.1.tar.bz2 Note that the extraction causes the tree of ownCloud files to appear in a directory called ''owncloud''. Strictly speaking you could extract the file directly in /opt without first creating an ''owncloud'' directory by hand. However I like to keep an eye on processes like this. We can now move all the files from the tar into the prepared directory with a command such as cp -pR /tmp/owncloud/* /opt/owncloud Here please note that all files in the tar file are owned by a user with UID and GID 65534, corresponding with ''nobody:nogroup''. If your server or webserver setup require a different user/group, you should use ''chown'' to set this. ===Publishing ownCloud in Apache2=== As we would like all files pertaining to the configuration of our server to live under ''/etc'', we create a directory ''/etc/owncloud''. Now, in this directory we'll create a file named ''apache.conf'' containing Alias /cloud /opt/owncloud <Directory /opt/owncloud> Options Indexes FollowSymLinks MultiViews AllowOverride All Order allow,deny allow from all </Directory> Publishing the ownCloud instance is now as easy as including this file in the relevant Apache (SSL) site configuration file. Under Debian, this means selecting the right file under ''/etc/apache2/sites-available/'' and insert the line Include /etc/owncloud/apache.conf If you now reload Apache with a command such as ''service apache2 reload'', you'll be able to surf to the URL of the pertaining site (e.g. https://www.saruman.biz/owncloud) and verify that the unconfigured owncloud instance is now accessible. ==Configuring ownCloud== We'll need '''a data directory''' for ownCloud. My recommendation is something like ''/data/owncloud'', and since the web server is required to manipulate files in this directory, we'll make it owned by Debian's webserver user/group ''www-data:www-data'' (under other distributions, make sure to use the corresponding user/group). For this directory to be used by ownCloud, we'll symlink to it from ''/opt/owncloud'' with command: ln -s /data/owncloud /opt/owncloud/data We'll also need '''a database''' for ownCloud. To create one, we can start the MySQL client (''mysql -u root -p'' and then the password) and create a database plus database user using mysql> create database owncloud; mysql> create user 'ownclouduser'@'localhost' identified by '<password1>'; mysql> grant all on owncloud.* to 'ownclouduser'@'localhost'; Now we can surf to the ownCloud instance page, and we'll find the startscreen asking for setup details. Provided the following details: * Admin account: '''owncloudadmin/<password2>''' * Data folder: '''/opt/owncloud/data''' * Database user: '''ownclouduser/<password1>''' * Database name: '''owncloud''' * Database host: '''localhost''' Once we've finished the installation wizard, we'll be able to log in to ownCloud using the admin account (here ''owncloudadmin'') and the corresponding password. If logging in works, then the following action will complete the configuration according to the LSB. We'll move the file ''/opt/owncloud/config/config.php'' that the installation wizard has created to our directory ''/etc/owncloud'' (if you like, you can also move the example configuration file ''config.sample.php'' for future reference). Then we symlink to it using ln -s /etc/owncloud/config.php /opt/owncloud/config/config.php ==Configuring ownCloud== ===Initial setup=== ===Using OpenLDAP as a backend=== ===Theming ownCloud=== ae6f077dd31f0c30f1d1fc6991241b773ee672be 3063 3062 2014-02-10T14:20:21Z Saruman! 2 fixed ToC wikitext text/x-wiki <big>'''ownCloud'''</big> In this day and age where many people are more and more dependant on information, cloud technology offers a way to unlock your information to you, wherever you are, on most any device. However, there's no telling what the cloud companies that you entrust with your information will do with that info - let alone nosy intelligence agencies from various countries around the world. My privacy [https://chronicle.com/article/Why-Privacy-Matters-Even-if/127461/ matters to me]! '''[http://owncloud.org/ ownCloud]''' is a free and open source alternatives for many cloud offerings such as Google Drive and DropBox, as it gives you the ability to share and sync files from your own server, but it does [http://owncloud.org/features/ much more] - added bonus, I say... ___TOC___ ==Introduction== ownCloud broadly comes in two flavours: the open source, free "community edition" and the open source, paid "enterprise edition". We're going to install the community edition here. The goal will be to have a way to share files between groups of people, most of which will have an account on our server. ==Installing ownCloud== In the following we're going to install ownCloud manually, that is to say we're not going to use any Linux package manager such as Debian's [https://wiki.debian.org/Apt apt] or Red Hat/CentOS's [https://access.redhat.com/site/solutions/9934 yum], but we're going to manually put the necessary files on the server. This has the advantage of being able to use the very latest & greatest version of ownCloud, but the disadvantage requiring us to do the heavy lifting, install-wise as well as update-wise. However, as we'll see below, a manual installation takes relatively little effort. ===Preparing your server=== First off we have to ensure that our server complies with ownCloud's requirements, as shown in the [http://doc.owncloud.org/server/6.0/admin_manual/installation/installation_source.html administrator manual]. This means we'll require a working LAMP server with a sufficient recent version of PHP, MySQL and Apache. If we want to secure our ownCloud communications using SSL, we also need to have a good SSL certificate (preferably not a self-signed one as many applications choke on that signature) and have set up our Apache server to correctly use it. Furthermore, ownCloud needs the Apache module mod-rewrite; usually one can enable it with a command such as ''a2enmod rewrite''. ===Getting ownCloud files on your server=== Now we'll choose a directory in which the ownCloud files can live; as it's a manual package, the Linux Standards Base ([http://www.linuxfoundation.org/collaborate/workgroups/lsb LSB]) suggests it goes into ''/opt''. We thus create the directory ''/opt/owncloud''. Next up we download the ownCloud ''tar.bz2'' file from the [http://owncloud.org/install/ ownCloud download page] to a temporary directory and extract it; this could look like cd /tmp wget http://download.owncloud.org/community/owncloud-6.0.1.tar.bz2 tar -xjf owncloud-6.0.1.tar.bz2 Note that the extraction causes the tree of ownCloud files to appear in a directory called ''owncloud''. Strictly speaking you could extract the file directly in /opt without first creating an ''owncloud'' directory by hand. However I like to keep an eye on processes like this. We can now move all the files from the tar into the prepared directory with a command such as cp -pR /tmp/owncloud/* /opt/owncloud Here please note that all files in the tar file are owned by a user with UID and GID 65534, corresponding with ''nobody:nogroup''. If your server or webserver setup require a different user/group, you should use ''chown'' to set this. ===Publishing ownCloud in Apache2=== As we would like all files pertaining to the configuration of our server to live under ''/etc'', we create a directory ''/etc/owncloud''. Now, in this directory we'll create a file named ''apache.conf'' containing Alias /cloud /opt/owncloud <Directory /opt/owncloud> Options Indexes FollowSymLinks MultiViews AllowOverride All Order allow,deny allow from all </Directory> Publishing the ownCloud instance is now as easy as including this file in the relevant Apache (SSL) site configuration file. Under Debian, this means selecting the right file under ''/etc/apache2/sites-available/'' and insert the line Include /etc/owncloud/apache.conf If you now reload Apache with a command such as ''service apache2 reload'', you'll be able to surf to the URL of the pertaining site (e.g. https://www.saruman.biz/owncloud) and verify that the unconfigured owncloud instance is now accessible. ==Configuring ownCloud== ===Initial setup=== We'll need '''a data directory''' for ownCloud. My recommendation is something like ''/data/owncloud'', and since the web server is required to manipulate files in this directory, we'll make it owned by Debian's webserver user/group ''www-data:www-data'' (under other distributions, make sure to use the corresponding user/group). For this directory to be used by ownCloud, we'll symlink to it from ''/opt/owncloud'' with command: ln -s /data/owncloud /opt/owncloud/data We'll also need '''a database''' for ownCloud. To create one, we can start the MySQL client (''mysql -u root -p'' and then the password) and create a database plus database user using mysql> create database owncloud; mysql> create user 'ownclouduser'@'localhost' identified by '<password1>'; mysql> grant all on owncloud.* to 'ownclouduser'@'localhost'; Now we can surf to the ownCloud instance page, and we'll find the startscreen asking for setup details. Provided the following details: * Admin account: '''owncloudadmin/<password2>''' * Data folder: '''/opt/owncloud/data''' * Database user: '''ownclouduser/<password1>''' * Database name: '''owncloud''' * Database host: '''localhost''' Once we've finished the installation wizard, we'll be able to log in to ownCloud using the admin account (here ''owncloudadmin'') and the corresponding password. If logging in works, then the following action will complete the configuration according to the LSB. We'll move the file ''/opt/owncloud/config/config.php'' that the installation wizard has created to our directory ''/etc/owncloud'' (if you like, you can also move the example configuration file ''config.sample.php'' for future reference). Then we symlink to it using ln -s /etc/owncloud/config.php /opt/owncloud/config/config.php ===Using OpenLDAP as a backend=== ===Theming ownCloud=== 0918b4fca3016b3c19c8042e3d77ff6ed4eb0321 0 1489 3061 2447 2014-02-04T20:58:37Z Saruman! 2 /* E-mail server setup */ updated link to source article wikitext text/x-wiki ==E-mail server setup== What we want to accomplish here is the setup of a mail server with the following properties: * can serve multiple mail domains * can relay mail for other domains to other mail servers * can have one or more mailboxes per domain * users of these mailboxes can be virtual (do not need to have a Linux user account) * can have multiple aliases per mailbox * can forward mail for certain aliases to multiple mailboxes For this type of mail server setup, we owe a great thankyou to [https://workaround.org/ispmail/squeeze Christoph Haas], whose advise has helped us create flexible and reliable mail servers since 2003. ==Preparation== We'll assume that the server currently has no mailserver installed, at least no other than the default ''exim'' mailserver. Furthermore, the server is already fitted with MySQL, and this database is running without problems. The hostname of the server must be set correctly, so that ''hostname -f'' returns a valid DNS name, like ''lighthouse.saruman.biz.''. It might also be an internal name like ''lighthouse.saruman.lan.'' but that will require us to give extra attention to the name under which Postfix will contact its collegues on the Internet. Also, the server can correctly [Networking_section#DNS_resolution_under_Debian | resolve DNS names] like [http://www.debian.org www.debian.org], preferably by running it's own caching DNS server. The server is kept on the correct date and time using NTP, TCP port 25 is open on the server, the ISP will allow connections from Internet to this port, and if there's a firewall running on this server, then it has port 25 open so as to not block incoming e-mail. ==Software installation== As a first step, we use [[APT and aptitude|apt or aptitude]] to make sure that our server is up-to-date. Then we can install the necessary software packages. Under Debian 5.0 "Lenny", the (single) packages is: * ''postfix'', the mail server itself - this includes the "virtual package" postfix-tls, that we want to use to secure connections to Postfix with the TLS protocol At the same time we can - and must - purge the following packages: * exim4 * exim4-base * exim4-daemon-light * exim4-config In ''aptitude'', only press "go" when you've marked all four of these packages "purge", or you cannot install postfix. When installing the postfix package, the Debian installer script will ask you several questions, which you can answer like this: * General type of mail configuration: Internet site * System mail name: the FQDN of the mail server that you've verified in the previous section. Note that the script will try to guess the DNS name, but that might yield a DNS name with a trailing dot. That is technically correct, but the installation script will barf. Remove the trailing dot before hitting &lt;enter>! * Postmaster mail address: the address that all mail should go to that is addressed to "root" and "postmaster". * Domain list: give the list of all domains that the machine can consider itself the FINAL destination for. This should at a minimum include an empty value, "localhost" and the FQDN of the machine itself (no trailing dots!); however, if you're running your own mail domain, you can also add that (e.g. "saruman.biz"). Thus, the list could look like this: saruman.biz, lighthouse.saruman.lan, localhost.saruman.lan, , localhost * Force synchronous updates? We think that's not necessary, but please read the question and decide for yourself * Local networks: something like ''127.0.0.0/8 [::ffff:127.0.0.0]/104 [::1]/128 192.168.67.0/24'' (the default, augmented with your local IP range) * Mailbox size limits: you can give postfix a limit in bytes, but we're going to use one single big mailbox for all users, so we cannot let Postfix guard it. Leave it at 0 (zero) so we don't have a size limit. * Character for local address extension: we leave it at ''+'' * Internet protocols to use: currently we don't have IPv6 support, so there's no sense in letting Postfix try to serve IPv6. We choose ''ipv4'' only. With the above data, the Debian install script for Postfix can do its job and configure Postfix with some basic settings. Now that Postfix is installed, we can install some dependent packages (we could install them in the same run, but if anything goes amiss with the postfix installation, then these packages are going to remain unconfigured as well): * ''postfix-doc'', the accompanying documentation; * ''postfix-mysql'', necessary to have Postfix talk to our MySQL server; * ''postfix-pcre'' to be able to parse regular expressions, which which we can combat spam; * ''dovecot-imapd'' is a daemon that will provide your users with IMAP access to their mail; * ''dovecot-pop3d'' is another daemon, but for the POP3 protocol. ==Virtual Mailman creation== When we're done, we'll need a "system user", a sort of virtual mailman that is the owner of all mailboxes that we're serving. We suggest the name "vmail" for this user. Note: this user does not get his own mailbox (i.e. there's no mailbox at vmail@saruman.biz). To create this user, and his home directory, we can run the following commands: groupadd -g 120 vmail useradd -g vmail -u 120 vmail -d /data/vmail -m -s /bin/false As you see, we've chosen a group ID and user ID of 120 (after confirming that this ID was not taken by another group or user, by checking ''/etc/passwd'' and ''/etc/group''. Furthermore, we've decided to keep the ''vmail'' user's home directory not under ''/home/vmail'', but in a special place where we're going to expect server data to reside - in our server, the ''/data'' directory (which is a RAID-5 array mounted under root). By adding ''-m'', we've actually created the home directory, and adding ''-s /bin/false'' makes totally sure that the user ''vmail'' can never ever log in - even if we've not created a password for this user, so ''vmail'' shouldn't be able to log in anyway. Better safe than sorry. To tell Postfix that this ''vmail'' user is someone special, we run postconf -e virtual_uid_maps=static:120 postconf -e virtual_gid_maps=static:120 That makes postfix understand that all mail for the virtual mail domains must be written to disk with these specified user and group ID's. ==MySQL configuration== ===Database preparation=== We will use the MySQL database to record data on our mail system, and then give our Postfix access to this database so that it can read its configuration from there. For starters, we'll create a MySQL database named "vmail", and a MySQL user named "vmail_admin" that can read all necessary data from that "vmail" database. Then, we create the necessary tables, and a view that links these tables. We do this with the MySQL client ''mysql''. However, we're quite lazy, so we don't create this database by hand (that's error-prone), but by use of a script [[create.vmail.sql]]. To this end, feed the [[create.vmail.sql]] script into the ''mysql'' client like this: mysql -u root -p < create.vmail.sql (This of course assumes you have ''create.vmail.sql'' in your current working directory; if not you can include the path to the file.) Simply give the MySQL root user password, and the script creates the database, the user, the necessary tables, and the view.<br> A note of caution: it is never a good idea to just run scripts without a proper understanding of what it does. Especially with MySQL, it will be advantageous if you understand the SQL commands. Open the script in a text editor, open the [http://dev.mysql.com/doc/refman/5.0/en/ MySQL command reference], and trace back what the script does exactly. ===Inserting data=== Next up, we fill the database with the first sets of values (either test data or the first of our production data). We'll start off with the virtual domains that we're hosting, by running the mysql client and feeding it information like this: mysql -u root -p vmail mysql> INSERT INTO virtual_domains (id, vdomain) VALUES (1, 'saruman.biz'); mysql> INSERT INTO virtual_domains (vdomain) VALUES ('wiki.saruman.biz'); mysql> INSERT INTO virtual_domains (vdomain) VALUES ('shop.saruman.biz'); This has the effect of creating three entries. You can check that everything worked as planned by executing mysql> select * from virtual_domains; Note: only the first entry needs an ''id'' value, because in MySQL we've defined that field as AUTO_INCREMENT. After creating your first virtual domain in the table, you never have to use a statement like the first INSERT again, only statements like the other two. Now the MySQL database has the information needed by Postfix to recognise that you have three virtual mail domains (namely the three domains in the VALUES section) for which it hosts virtual mailboxes. Postfix cannot read this information yet, but that'll be taken care of in the next section. Whle still within the mysql client, we can now create users: mysql> INSERT INTO virtual_users (id, domain_id, user, passwd) VALUES (1, 1, 'jan', MD5('JanSecret')); mysql> INSERT INTO virtual_users (domain_id, user, passwd) VALUES (1, 'mike', MD5('MikeSecret')); mysql> INSERT INTO virtual_users (domain_id, user, passwd) VALUES (3, 'shopkeeper', MD5('ShopSecret')); This has the effect of creating three users "jan" (in domain saruman.biz), "mike" (in domain saruman.biz) and "shopkeeper" (in domain shop.saruman.biz). Again, the ''id'' value is only ever needed in the first statement, because from now on every user addition will auto-increment ''id''. The passwords shown are encrypted with MD5, and put in the ''passwd'' field. Later on, the users will be able to access their mailboxes using this password; we won't tell Postfix anything about them, because it doesn't need the passwords. You can check the content of the ''virtual_users'' table with the right "select" statement, and you can now also see that the view ''view-users'' works: mysql> select * from virtual_users; mysql> select * from view_users; Next up, we're going to add some aliases, which are alternative e-mail addresses for the users; their primary e-mail address can already be seen in the ''view_users'' view, but perhaps you also want mail to "webmaster@shop.saruman.biz" to arrive at one or more mailboxes, e.g. in the mailbox for user "shopkeeper" (within domain "shop.saruman.biz") and this guy's home address ("j.doe@example.com"). Furthermore, we'll define catchall-addresses for all domains, that'll send all mail for which no mailbox can be found to the mailbox of user Mike (for the first two domains) and Webmaster (for shop.saruman.biz; Webmaster himself is an alias yet again, that points to shopkeeper@shop.saruman.biz). To create the catchall, leave out a value for the source address. This creates the empty value for source that will be expanded (using source@domain) to "@domain". mysql> INSERT INTO virtual_aliases (id, domain_id, source, destination) VALUES (1, 2, 'webmaster', 'shopkeeper@shop.saruman.biz'); mysql> INSERT INTO virtual_aliases (domain_id, source, destination) VALUES (2, 'webmaster', 'j.doe@example.com'); mysql> INSERT INTO virtual_aliases (domain_id, destination) VALUES (1, 'mike@saruman.biz'); mysql> INSERT INTO virtual_aliases (domain_id, destination) VALUES (2, 'mike@saruman.biz'); mysql> INSERT INTO virtual_aliases (domain_id, destination) VALUES (3, 'webmaster@saruman.biz'); Again, we don't need to add the ''id'' value any more after the first ever insertion into this table. We can check the result by running a select statement against the ''virtual_aliases'' table and ''view_aliases'' view: mysql> select * from virtual_aliases; mysql> select * from view_aliases; == Postfix configuration for MySQL lookups== Next, we're going to tell Postfix to use the ''vmail'' database, and also how to read the database (Postfix never writes the MySQL database). To this end, we're going to create three configuration files in directory ''/etc/postfix''. We'll start off with one configuration file, with which Postfix can determine if a domain name is among the domain(s) that it's actually hosting mailboxes for. Then we'll create the config file that checks the table that contains all the users that have a virtual mailbox, and finally we create the lookup for the table with all the aliases. ===Virtual mail domains lookup=== Create file ''/etc/postfix/mysql-virtual-domains.cf'' with the following content: user = vmail_admin password = SuperSecret hosts = 127.0.0.1 dbname = vmail query = SELECT 1 FROM virtual_domains WHERE vdomain='%s' Next, we tell postfix to check this configuration file when it needs to check "virtual_mailbox_domains": postconf -e virtual_mailbox_domains=mysql:/etc/postfix/mysql-virtual-domains.cf Use of this configuration file in postfix has the effect of returning "yes" when checking our database for the domain part of an email address. Naturally, this configuration file has to be fitted with the actual ''vmail_admin'' password rather than our example "SuperSecret". === Virtual mail user lookup=== Create the file ''/etc/postfix/mysql-virtual-mailbox-maps.cf'' with the following content: user = vmail_admin password = SuperSecret hosts = 127.0.0.1 dbname = vmail query = SELECT 1 FROM view_users WHERE email='%s' Next, we tell Postfix that this mapping file is supposed to be used for the ''virtual_mailbox_maps'' mapping: postconf -e virtual_mailbox_maps=mysql:/etc/postfix/mysql-virtual-mailbox-maps.cf The lookup of virtual mailboxes should work with the data we've put into the database previously. i.e. postmap -q jan@saruman.biz mysql:/etc/postfix/mysql-virtual-mailbox-maps.cf should return a '''1''' to acknowledge that "jan@saruman.biz" is indeed a virtual mailbox in our Postfix configuration. === Virtual alias lookup=== Create another cf file at ''/etc/postfix/mysql-virtual-alias-maps.cf'': user = vmail_admin password = SuperSecret hosts = 127.0.0.1 dbname = vmail query = SELECT destination FROM view_aliases WHERE email='%s' And create yet another cf file at ''/etc/postfix/mysql-email2email.cf'': user = vmail_admin password = SuperSecret hosts = 127.0.0.1 dbname = vmail query = SELECT email FROM view_users WHERE email='%s' Again, we tell Postfix that this mapping file is supposed to be used for the ''virtual_alias_maps'' mapping: postconf -e virtual_alias_maps=mysql:/etc/postfix/mysql-virtual-alias-maps.cf,mysql:/etc/postfix/mysql-email2email.cf The lookup of virtual aliases should now work as designed: postmap -q shopkeeper@shop.saruman.biz mysql:/etc/postfix/mysql-virtual-alias-maps.cf postmap -q webmaster@shop.saruman.biz mysql:/etc/postfix/mysql-virtual-alias-maps.cf If you've put in the data from the previous section, then both commands should return the same result: ''shopkeeper@saruman.biz''. This shows that Postfix will deliver mail to shopkeeper or to webmaster to the mailbox of shopkeeper. ===Finishing up configuration files=== When everything works as planned, then we secure the configuration files against prying eyes. Remember, the configuration files contain the user/password combination which which to access the ''vmail'' SQL database. The ''vmail_admin'' user has only read rights, and passwords in there are encrypted, but nevertheless, this is information we need to protect. Thus: chown root:postfix /etc/postfix/mysql-*.cf chmod u=rw,g=r,o= /etc/postfix/mysql-*.cf This protects all four configuration files since only root can write them, members of group ''postfix'' can read them, and the rest of the world cannot access them at all. ==Configuring mail delivery through Dovecot LDA== E-mails get delivered to the virtual mailboxes by means of a Mail Delivery Agent (MDA). With Postfix, the standard MDA for delivery to virtual mailboxes is called ''virtual'', but we're not going to use that; we're going to use ''[http://wiki.dovecot.org/LDA Dovecot LDA]'', which is a program called ''deliver''. By the way, the abbreviation LDA stands for Local Delivery Agent, which of course means more or less the same as MDA. ===Enabling the Dovecot daemon=== To make Postfix use Dovecot LDA, we add the following line to ''/etc/postfix/master.cf'': dovecot unix - n n - - pipe flags=DRhu user=vmail:vmail argv=/usr/lib/dovecot/deliver -d ${recipient} This declares the service "dovecot" to mean using the program ''/usr/lib/dovecot/deliver'' with the right parameters. If we now let Postfix reload its files, it'll learn about this new service. Subsequently we can instruct Postfix to start using it, by declaring service "dovecot" to be the virtual transport of choice, and specifying one Dovecot-specific variable: postfix reload postconf -e virtual_transport=dovecot postconf -e dovecot_destination_recipient_limit=1 ===Dovecot default configuration=== Now to configure Dovecot itself: open ''/etc/dovecot/dovecot.conf'' with your favourite editor [[vim]]; first make sure the ''protocols ='' line reads protocols = imap imaps pop3 pop3s (which it should by default). The second setting is quite crucial. By default, the location of the mail directories is found automatically by Dovecot, but here that won't work. Find the line that reads ''#mail_location ='', and change it to mail_location = maildir:/data/vmail/%d/%n/Maildir This will look for mail in directory ''/data/vmail/'''DOMAIN'''/'''USER'''/Maildir'', and expect this directory to be in "maildir" format. Next look for a section called "auth default". First define the allowed authentication mechanisms: mechanisms = plain login Then inside that same section you need to uncomment: passdb sql { args = /etc/dovecot/dovecot-sql.conf } which tells Dovecot that the passwords are stored in an SQL database (it's obvious that we'll now have to create this conf-file) and: userdb static { args = uid=120 gid=120 home=/data/vmail/%d/%n allow_all_users=yes } to tell Dovecot where the mailboxes are located. This is similar to the ''mail_location'' setting. Next task: comment out the section ''passdb pam'', so that Dovecot doesn't accidentally try to service local users as well. Next up: tell Dovecot to handle IMAP the same as previous versions of this virtual mailserver have - this can prove to be quite tricky if you already have mailboxes full of mail, put there by e.g. Courier-IMAP. What works for us, is namespace private { separator = . prefix = inbox = yes } However, your mileage may vary. You'll also want to comment out the ''passdb pam'' sections, since we're not hosting mail for local users. Next up, we'll edit the section ''socket listen'' so that Dovecot can access the user database (master section), and our Postfix mailserver can access Dovecot (client section): socket listen { master { path = /var/run/dovecot/auth-master mode = 0600 user = vmail } client { path = /var/spool/postfix/private/auth mode = 0660 user = postfix group = postfix } } Finally, the protocol section, where we specify log files, an address to put in mails when we send out nondelivery reports, and a place to store scripts: protocol lda { log_path = /var/log/appslog/mail/dovecot-deliver.log auth_socket_path = /var/run/dovecot/auth-master postmaster_address = postmaster@saruman.biz mail_plugins = cmusieve global_script_path = /data/vmail/globalsieverc } You could change the log path to "log_path =" With a empty logpath syslog will log the events. Now that we've finished the Dovecot configuration file, we need to create a fitting MySQL configuration file for Dovecot. The file is ''/etc/dovecot/dovecot-sql.conf'', and its contents are driver = mysql connect = host=127.0.0.1 dbname=vmail user=vmail_admin password=SuperSecret default_pass_scheme = PLAIN-MD5 password_query = SELECT email as user, passwd as password FROM view_users WHERE email='%u'; When you've created this file (as root), change the attributes of ''dovecot-sql.conf'' and ''dovecot.conf'', and then restart Dovecot to start using the new configuration. Note: ''dovecot.conf'' needs to be read by Postfix, hence the group ownership for the file. chmod u=rw,g=,o= /etc/dovecot/dovecot-sql.conf chgrp vmail /etc/dovecot/dovecot.conf chmod u=rw,g=r,o= /etc/dovecot/dovecot.conf /etc/init.d/dovecot restart To get some more logging in the case something goes wrong. Uncomment the folling and change to yes. auth_verbose = yes auth_debug = yes auth_debug_passwords = yes ===Dovecot SSL configuration=== Out of the (Debian) box, Dovecot is SSL-enabled. We'll now replace the generic SSL-certificate, generated for the host by the Dovecot installation script, by our own certificate. To ths end, we first [[Creating_digital_certificates_with_our_root_certificate | generate an appropriate certificate]], e.g. an SSL wildcard certificate: "*.saruman.biz". This results in a public and a private certificate, both of which must be placed somewhere where Dovecot expects them and can read them. By default, Dovecot expects the following locations/filenames/owner/attributes: /etc/ssl/certs/dovecot.pem -rw-r--r-- root:dovecot 4624 bytes /etc/ssl/private/dovecot.pem -rw------- root:dovecot 1743 bytes If we may make a suggestion: rename the generated certificates in both locations to dovecot.pem.bak, place your generated certificates in their place, and set the owner/permissions like displayed here. However, if you've generated your own keys, you might have used a passphrase on the private key. You'll have to tell dovecot about it in its configuration file /etc/dovecot/dovecot.conf. To this end, edit the corresponding section by uncommenting the "ssl_" lines, and using your private key password (e.g. "zM7Ertq12") in the appropriate line: ssl_cert_file = /etc/ssl/certs/dovecot.pem ssl_key_file = /etc/ssl/private/dovecot.pem # If key file is password protected, give the password here. Alternatively # give it when starting dovecot with -p parameter. ssl_key_password = zM7Ertq12 Naturally you are free to place the keys in a different location, and/or use a different name... ==Finishing up== This is a good moment to test your configuration, if you haven't been able to test your work inbetween. If everything works as expected, you can add bells and whistles to your configuration. ===''smtpd'' TLS encryption=== The first addition we'd like to present covers the way Postfix handles incoming connections. Since authentication works, we can have Postfix distrust every (unauthenticated) connection: postconf -e mynetworks= Furthermore, since a default SSL certificate is installed by the Debian Postfix installation routine, we can encrypt all our connections using TLS; we enforce this using postconf -e smtpd_use_tls=yes postconf -e smtpd_tls_auth_only=yes Of course, you need to adjust the settings of your IMAP client so that it properly uses TLS and properly authenticates itself. If TLS works, you'll probably want to change the certificate as you have for Dovecot in the previous section. This is again pretty easy. If you haven't yet, now is the time to [[Creating_digital_certificates_with_our_root_certificate | creating that custom SSL certificate]] for our mail server - but you have to make sure that you DON'T use a password on the private key. Unlike Dovecot, Postfix cannot be told the password to the private key somewhere. For starters, look at the TLS-section of your ''main.cf'' that you currently have. Chances are a big chunk of it looks like this: # TLS parameters smtpd_tls_cert_file=/etc/ssl/certs/ssl-cert-snakeoil.pem smtpd_tls_key_file=/etc/ssl/private/ssl-cert-snakeoil.key smtpd_use_tls=yes Now all you need to do is replace the name of the snakeoil-keys with those of appropriate ssl-certificates, the private key of which needs to be NOT passphrase-protected. For this you could copy the Dovecot certificates, if you strip that passphrase in the manner described in the [[Creating_digital_certificates_with_our_root_certificate#Creating_an_SSL_certificate | SSL certificate section]]. The ''main.cf'' then would become: # TLS parameters smtpd_tls_cert_file=/etc/ssl/certs/postfix.pem smtpd_tls_key_file=/etc/ssl/private/postfix.key smtpd_use_tls=yes Restart Postfix, and presto. === Other additions === If everything ''still'' works after these changes, then congratulations, you now have a powerful, flexible and pretty secure mail setup. Of course, there are always points for improvements. We'll cover these in separate pages. One page that we want to direct you to now, is * [[Antispam measures]] for our Postfix mailserver ce3bdb6d541d9654b77720953b078ec06382a7dc 6 1791 3064 2014-10-26T10:30:21Z Saruman! 2 PuttyGen interface wikitext text/x-wiki PuttyGen interface 022092d87aec9265883b875b18c5c016d12a4885 3066 3064 2014-10-26T19:59:12Z Saruman! 2 Saruman! uploaded a new version of &quot;[[File:Puttygen.png]]&quot;: correct example username wikitext text/x-wiki PuttyGen interface 022092d87aec9265883b875b18c5c016d12a4885 0 1616 3065 2661 2014-10-26T10:45:38Z Saruman! 2 start ssh key section wikitext text/x-wiki ==OpenSSH Server== This package is essential when you want to be able to (safely) administer your server from another place than the console. To install: simpy use ''sudo aptitude install openssh-server''. This will install the OpenSSH server, plus the OpenSSH client. Since the SSL vulnerbility of may '08, also the ssh-blacklist package is downloaded. After installing, we need to make the following changes to the default settings in file ''/etc/ssh/sshd-config'': * line ''PermitRootLogin yes'' should be set to ''no'', so that user ''root'' CANNOT log in over SSH! ([http://www.debian-administration.org/articles/573 big security gap!]). * add a line ''AllowGroups wheel''; adding this ensures that NOBODY can log in over SSH unless you specifically assigned them to the ''wheel'' group, reducing the attack surface of your SSH user. Should you need more than one group (e.g. you want to add the group "ldapwheel"), then add the groups separated by spaces: ''AllowGroups wheel ldapwheel''. * Change your banner by editing the [[MOTD file]]. Next, make sure the ''wheel'' group exist, and add all users to it that are allowed ssh-access: groupadd -g 117 wheel usermod -a -G wheel jan In the groupadd line, the groupID is explicitly set to 117, but this really is optional. In the usermod line, be sure to use the ''-a'' so that your user gets the ssh-users group added, instead of replacing all supplementary groups with this one ssh-users. If you've added a group that exists in your LDAP server, make sure that those LDAP users are member of that group that you want to give SSH access. This is ofcourse managed from your LDAP management console (be it the commandline ''ldapmodify'' or a graphic tool like [[Filling_an_OpenLDAP_database#Adding_a_user_with_LAM | LDAP Account Manager]] When all this is changed, the service should be restarted with ''sudo /etc/init.d/ssh restart''. One of the nice things of a correctly configured SSH server, is the ability to use [[scp]] to copy files between machines. == Changing RSA keys == Occasionally you'll find the RSA key of one of your machines has changed. This may have a number of reasons, a.o. a reinstall or migration of said machine. In any case, when you try to SSH to the machine you get a message like this: localhost:~# '''ssh insomnia@easton.saruman.biz''' @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @ WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED! @ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ IT IS POSSIBLE THAT SOMEONE IS DOING SOMETHING NASTY! Someone could be eavesdropping on you right now (man-in-the-middle attack)! It is also possible that the RSA host key has just been changed. The fingerprint for the RSA key sent by the remote host is f7:1a:5a:11:ca:20:99:fa:db:1b:b8:75:8e:e5:f1:12. Please contact your system administrator. Add correct host key in /home/sixpacjo/.ssh/known_hosts to get rid of this message. Offending key in /home/sixpacjo/.ssh/known_hosts:4 RSA host key for easton.saruman.biz has changed and you have requested strict checking. Host key verification failed. localhost:~# _ When you get this message it is not possible to connect to the machine mentioned, until you've solved the problem of the RSA key. There are multiple ways to correct the key, but the simplest method seems to be to simply remove the offending key with ''ssh-keygen''. Note that Debian "Lenny" stores the RSA key in ''two'' places: one for the host name, one for the IP number. To prevent annoying messages like this: Warning: the RSA host key for 'easton.saruman.biz' differs from the key for the IP address '192.168.67.5' Offending key for IP in /home/sixpacjo/.ssh/known_hosts:4 you should remove the RSA key for the IP number as well. This you do with the following two commands: localhost:~# '''ssh-keygen -R easton.saruman.biz''' /home/sixpacjo/.ssh/known_hosts updated. Original contents retained as /home/sixpacjo/.ssh/known_hosts.old localhost:~# '''ssh-keygen -R 192.168.67.5''' /home/sixpacjo/.ssh/known_hosts updated. Original contents retained as /home/sixpacjo/.ssh/known_hosts.old localhost:~# _ After deleting the "offending RSA keys" like this, you can SSH to the box in question, and your SSH client will save the (new) RSA key for you in your ''known_hosts'' file. ==Using certificates for SSH login== If your server is open to the Internet, passwords alone may not be safe enough. Plenty of malicious folks will try to brute-force attack your SSH server. Of course you've disabled root login (right? RIGHT?!?) but still... all that attacking clutters your logs, and maybe one day one of your SSH user passwords turns out too weak. That's why it's a good idea to add SSL keys to the mix. ===Generating an SSH key=== You can generate an SSH key from Linux itself (see [https://www.digitalocean.com/community/tutorials/how-to-set-up-ssh-keys--2 DigitalOcean], but in this article we'll use [http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html PuTTy], because PuTTy/WinSCP is the go-to tool set for Linux administration from a Windows workstation, and PuTTy's [http://www.chiark.greenend.org.uk/~sgtatham/putty/wishlist/key-formats-natively.html proprietary key management] provides some nifty tricks for key management. (based on [https://www.digitalocean.com/community/tutorials/how-to-create-ssh-keys-with-putty-to-connect-to-a-vps DigitalOcean howto]) First we start the PuTTYgen utility, by double-clicking on its .exe file. * At the bottom of the interface, for Type of key to generate, select SSH-2 RSA; * In the Number of bits in a generated key field, specify either 2048 or 4096 (the latter is safer); * Now click the Generate button. PuttyGen needs some entropy, so move your mouse pointer around in the blank area of the Key section for a while until the progress bar is full - a private/ public key pair will then be generated; * In the Key comment field, enter your name (or any other comment you'd like), to help you identify this key pair. This is particularly useful in the event you end up creating more than one key pair; * A passphrase is optional but recommended: Type & re-type it in the Key passphrase fields. Really, only leave out the passphrase if you would like to use this particular key pair for automated processes. The above actions should look a bit like this: [[File:Puttygen.png|PuttyGen interface]] * Now click the Save public key button & choose whatever filename you'd like, saving it in a "safe" folder. I'd recommend a filename that corresponds to the Key comment field content; * Then click the Save private key button & choose whatever filename you'd like (you can save it in the same location as the public key, but it should be a location that only you can access and that you will NOT lose!). Keep the file extension to '''.ppk''' ===Putting the key on the server=== ===Configuring the SSH server=== a2878b7c1629f9fc199611ebd1149641c2873d27 3067 3065 2014-10-26T20:06:57Z Saruman! 2 intermediate save wikitext text/x-wiki ==OpenSSH Server== This package is essential when you want to be able to (safely) administer your server from another place than the console. To install: simpy use ''sudo aptitude install openssh-server''. This will install the OpenSSH server, plus the OpenSSH client. Since the SSL vulnerbility of may '08, also the ssh-blacklist package is downloaded. After installing, we need to make the following changes to the default settings in file ''/etc/ssh/sshd-config'': * line ''PermitRootLogin yes'' should be set to ''no'', so that user ''root'' CANNOT log in over SSH! ([http://www.debian-administration.org/articles/573 big security gap!]). * add a line ''AllowGroups wheel''; adding this ensures that NOBODY can log in over SSH unless you specifically assigned them to the ''wheel'' group, reducing the attack surface of your SSH user. Should you need more than one group (e.g. you want to add the group "ldapwheel"), then add the groups separated by spaces: ''AllowGroups wheel ldapwheel''. * Change your banner by editing the [[MOTD file]]. Next, make sure the ''wheel'' group exist, and add all users to it that are allowed ssh-access: groupadd -g 117 wheel usermod -a -G wheel jan In the groupadd line, the groupID is explicitly set to 117, but this really is optional. In the usermod line, be sure to use the ''-a'' so that your user gets the ssh-users group added, instead of replacing all supplementary groups with this one ssh-users. If you've added a group that exists in your LDAP server, make sure that those LDAP users are member of that group that you want to give SSH access. This is ofcourse managed from your LDAP management console (be it the commandline ''ldapmodify'' or a graphic tool like [[Filling_an_OpenLDAP_database#Adding_a_user_with_LAM | LDAP Account Manager]] When all this is changed, the service should be restarted with ''sudo /etc/init.d/ssh restart''. One of the nice things of a correctly configured SSH server, is the ability to use [[scp]] to copy files between machines. == Changing RSA keys == Occasionally you'll find the RSA key of one of your machines has changed. This may have a number of reasons, a.o. a reinstall or migration of said machine. In any case, when you try to SSH to the machine you get a message like this: localhost:~# '''ssh insomnia@easton.saruman.biz''' @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @ WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED! @ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ IT IS POSSIBLE THAT SOMEONE IS DOING SOMETHING NASTY! Someone could be eavesdropping on you right now (man-in-the-middle attack)! It is also possible that the RSA host key has just been changed. The fingerprint for the RSA key sent by the remote host is f7:1a:5a:11:ca:20:99:fa:db:1b:b8:75:8e:e5:f1:12. Please contact your system administrator. Add correct host key in /home/sixpacjo/.ssh/known_hosts to get rid of this message. Offending key in /home/sixpacjo/.ssh/known_hosts:4 RSA host key for easton.saruman.biz has changed and you have requested strict checking. Host key verification failed. localhost:~# _ When you get this message it is not possible to connect to the machine mentioned, until you've solved the problem of the RSA key. There are multiple ways to correct the key, but the simplest method seems to be to simply remove the offending key with ''ssh-keygen''. Note that Debian "Lenny" stores the RSA key in ''two'' places: one for the host name, one for the IP number. To prevent annoying messages like this: Warning: the RSA host key for 'easton.saruman.biz' differs from the key for the IP address '192.168.67.5' Offending key for IP in /home/sixpacjo/.ssh/known_hosts:4 you should remove the RSA key for the IP number as well. This you do with the following two commands: localhost:~# '''ssh-keygen -R easton.saruman.biz''' /home/sixpacjo/.ssh/known_hosts updated. Original contents retained as /home/sixpacjo/.ssh/known_hosts.old localhost:~# '''ssh-keygen -R 192.168.67.5''' /home/sixpacjo/.ssh/known_hosts updated. Original contents retained as /home/sixpacjo/.ssh/known_hosts.old localhost:~# _ After deleting the "offending RSA keys" like this, you can SSH to the box in question, and your SSH client will save the (new) RSA key for you in your ''known_hosts'' file. ==Using certificates for SSH login== If your server is open to the Internet, passwords alone may not be safe enough. Plenty of malicious folks will try to brute-force attack your SSH server. Of course you've disabled root login (right? RIGHT?!?) but still... all that attacking clutters your logs, and maybe one day one of your SSH user passwords turns out too weak. That's why it's a good idea to add SSL keys to the mix. ===Generating an SSH key=== You can generate an SSH key from Linux itself (see [https://www.digitalocean.com/community/tutorials/how-to-set-up-ssh-keys--2 DigitalOcean], but in this article we'll use [http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html PuTTy], because PuTTy/WinSCP is the go-to tool set for Linux administration from a Windows workstation, and PuTTy's [http://www.chiark.greenend.org.uk/~sgtatham/putty/wishlist/key-formats-natively.html proprietary key management] provides some nifty tricks for key management. (based on [https://www.digitalocean.com/community/tutorials/how-to-create-ssh-keys-with-putty-to-connect-to-a-vps DigitalOcean howto]) First we start the PuTTyGen utility, by double-clicking on its .exe file. * At the bottom of the interface, for Type of key to generate, select SSH-2 RSA; * In the Number of bits in a generated key field, specify either 2048 or 4096 (the latter is safer, but takes longer to generate); * Now click the Generate button. PuTTyGen needs some entropy, so move your mouse pointer around in the blank area of the Key section for a while until the progress bar is full - a private/ public key pair will then be generated; * In the Key comment field, enter your name (or any other comment you'd like), to help you identify this key pair. This is particularly useful in the event you end up creating more than one key pair; * A passphrase is optional but recommended: Type & re-type it in the Key passphrase fields. (Really, only leave out the passphrase if you would like to use this particular key pair for automated processes!) The above actions should look a bit like this: [[File:Puttygen.png|PuTTyGen interface]] * Now click the Save public key button & choose whatever filename you'd like, saving it in a "safe" folder. I'd recommend a filename that corresponds to the Key comment field content; * Then click the Save private key button & choose whatever filename you'd like (you can save it in the same location as the public key, but it should be a location that only you can access and that you will NOT lose!). Keep the file extension to '''.ppk''' ===Putting the key on the server=== To put the key on the server, we need to use not the public key file, as the file itself is in a format that OpenSSH doesn't recognize. So we can again open PuTTyGen, click ''load'' to load an existing private key file, and select the private key from the safe folder used below. After entering the passphrase (twice) we see the same information as before (see pic above). From the PuTTyGen interface, we select & copy to clipboard the information in the top window, something like ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAgEAjisviHZ19eU0F5BtN+F32tcjO72Ne 82Br24XS5cQASuYt8EZXBP1bdh0JFX7KvJIBMzH6KXo0gZQv/UtX4q+9jV9xgCgWq IAM+WKEVexAkR1RjFc8Bf8pPK62eNsis959+XD0IuuH7Ge/JKTy6ScxU+nyIfBJr/ a894TNPwdCEAbnBdU6WX/Q7g3P7xVaMu2g5okLRkO1tt7wIlt0zrOx86hMvesmIwX CfZ8qJtp8frmpoxbbCn9akgDPRtmMUEJDDkgrW6oyyMCtCgH0iTEZf3RYq4aOdXAI bJE9Yu402BPmyZCSDBrqwYfEWn0FgtEsjTlc7TTnUq+X35ndCpwE+g4AV3Fle7e18 eNyqvb3ng2+nSj4uNj2fFqlfNrJXfZGVELmk7xnVH1ypP6WamFHxG81wAqkGnBA2q W1ItvJxZ3L3mfHX5LKUxMMXbw5hElXtVQI+ZiDPjFqCIqPXagYzIsh/XzKbXoxZnR abcc14wGdPM+3TuAgyARoVuYyMb6iJz7SMrf1OAvMD6P7AcY5l7PeFG88ABJc67kS fPAyZRrK7uHllh2P3B3lEzIWrXYvKqjMoOOQj0uAhHtmFVtDvu/bHgJ2BWrTYq9AI g7AY59QnzK0LO8BxAoTSTKuUNpj+9WP7FUNL60nejm6A68PXQRddVrAZ2SYUuTUB+ /pU0= Joe Sixpack Note that on pasting this information in e.g. Notepad, then it should be a ''single'' line of information. On a sidenote, if you need the private key in an ''OpenSSH'' or ''ssh.com'' compatible form, you can use the Conversions tab on the toolbar. Next, we open a PuTTy SSH session to the server, change directory to the user's home directory (e.g. ''/home/jsixpack''), and in this home directory go into the ''.ssh'' directory. Inside that directory there should be a file ''authorized_keys''. If it's not there, create it with the user as owner and read/write for the user only. In the example of user ''jsixpack'': cd /home/jsixpack/.ssh touch authorized_keys chmod 600 authorized_keys Then open this file with [[Vim|vi]], and copy the public key in there. Again, it should be a single line, beginning with ''ssh-rsa AAAA'' and ending with the key comment. Save with '':qw'' and the key is stored! ===Configuring the SSH server=== e8797033db28f677c7977455ecfe40986bdfb1ae 3068 3067 2014-10-26T20:29:55Z Saruman! 2 ssh server config wikitext text/x-wiki ==OpenSSH Server== This package is essential when you want to be able to (safely) administer your server from another place than the console. To install: simpy use ''sudo aptitude install openssh-server''. This will install the OpenSSH server, plus the OpenSSH client. Since the SSL vulnerbility of may '08, also the ssh-blacklist package is downloaded. After installing, we need to make the following changes to the default settings in file ''/etc/ssh/sshd-config'': * line ''PermitRootLogin yes'' should be set to ''no'', so that user ''root'' CANNOT log in over SSH! ([http://www.debian-administration.org/articles/573 big security gap!]). * add a line ''AllowGroups wheel''; adding this ensures that NOBODY can log in over SSH unless you specifically assigned them to the ''wheel'' group, reducing the attack surface of your SSH user. Should you need more than one group (e.g. you want to add the group "ldapwheel"), then add the groups separated by spaces: ''AllowGroups wheel ldapwheel''. * Change your banner by editing the [[MOTD file]]. Next, make sure the ''wheel'' group exist, and add all users to it that are allowed ssh-access: groupadd -g 117 wheel usermod -a -G wheel jan In the groupadd line, the groupID is explicitly set to 117, but this really is optional. In the usermod line, be sure to use the ''-a'' so that your user gets the ssh-users group added, instead of replacing all supplementary groups with this one ssh-users. If you've added a group that exists in your LDAP server, make sure that those LDAP users are member of that group that you want to give SSH access. This is ofcourse managed from your LDAP management console (be it the commandline ''ldapmodify'' or a graphic tool like [[Filling_an_OpenLDAP_database#Adding_a_user_with_LAM | LDAP Account Manager]] When all this is changed, the service should be restarted with ''sudo /etc/init.d/ssh restart''. One of the nice things of a correctly configured SSH server, is the ability to use [[scp]] to copy files between machines. == Changing RSA keys == Occasionally you'll find the RSA key of one of your machines has changed. This may have a number of reasons, a.o. a reinstall or migration of said machine. In any case, when you try to SSH to the machine you get a message like this: localhost:~# '''ssh insomnia@easton.saruman.biz''' @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @ WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED! @ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ IT IS POSSIBLE THAT SOMEONE IS DOING SOMETHING NASTY! Someone could be eavesdropping on you right now (man-in-the-middle attack)! It is also possible that the RSA host key has just been changed. The fingerprint for the RSA key sent by the remote host is f7:1a:5a:11:ca:20:99:fa:db:1b:b8:75:8e:e5:f1:12. Please contact your system administrator. Add correct host key in /home/sixpacjo/.ssh/known_hosts to get rid of this message. Offending key in /home/sixpacjo/.ssh/known_hosts:4 RSA host key for easton.saruman.biz has changed and you have requested strict checking. Host key verification failed. localhost:~# _ When you get this message it is not possible to connect to the machine mentioned, until you've solved the problem of the RSA key. There are multiple ways to correct the key, but the simplest method seems to be to simply remove the offending key with ''ssh-keygen''. Note that Debian "Lenny" stores the RSA key in ''two'' places: one for the host name, one for the IP number. To prevent annoying messages like this: Warning: the RSA host key for 'easton.saruman.biz' differs from the key for the IP address '192.168.67.5' Offending key for IP in /home/sixpacjo/.ssh/known_hosts:4 you should remove the RSA key for the IP number as well. This you do with the following two commands: localhost:~# '''ssh-keygen -R easton.saruman.biz''' /home/sixpacjo/.ssh/known_hosts updated. Original contents retained as /home/sixpacjo/.ssh/known_hosts.old localhost:~# '''ssh-keygen -R 192.168.67.5''' /home/sixpacjo/.ssh/known_hosts updated. Original contents retained as /home/sixpacjo/.ssh/known_hosts.old localhost:~# _ After deleting the "offending RSA keys" like this, you can SSH to the box in question, and your SSH client will save the (new) RSA key for you in your ''known_hosts'' file. ==Using certificates for SSH login== If your server is open to the Internet, passwords alone may not be safe enough. Plenty of malicious folks will try to brute-force attack your SSH server. Of course you've disabled root login (right? RIGHT?!?) but still... all that attacking clutters your logs, and maybe one day one of your SSH user passwords turns out too weak. That's why it's a good idea to add SSL keys to the mix. ===Generating an SSH key=== You can generate an SSH key from Linux itself (see [https://www.digitalocean.com/community/tutorials/how-to-set-up-ssh-keys--2 DigitalOcean], but in this article we'll use [http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html PuTTy], because PuTTy/WinSCP is the go-to tool set for Linux administration from a Windows workstation, and PuTTy's [http://www.chiark.greenend.org.uk/~sgtatham/putty/wishlist/key-formats-natively.html proprietary key management] provides some nifty tricks for key management. (based on [https://www.digitalocean.com/community/tutorials/how-to-create-ssh-keys-with-putty-to-connect-to-a-vps DigitalOcean howto]) First we start the PuTTyGen utility, by double-clicking on its .exe file. * At the bottom of the interface, for Type of key to generate, select SSH-2 RSA; * In the Number of bits in a generated key field, specify either 2048 or 4096 (the latter is safer, but takes longer to generate); * Now click the Generate button. PuTTyGen needs some entropy, so move your mouse pointer around in the blank area of the Key section for a while until the progress bar is full - a private/ public key pair will then be generated; * In the Key comment field, enter your name (or any other comment you'd like), to help you identify this key pair. This is particularly useful in the event you end up creating more than one key pair; * A passphrase is optional but recommended: Type & re-type it in the Key passphrase fields. (Really, only leave out the passphrase if you would like to use this particular key pair for automated processes!) The above actions should look a bit like this: [[File:Puttygen.png|PuTTyGen interface]] * Now click the Save public key button & choose whatever filename you'd like, saving it in a "safe" folder. I'd recommend a filename that corresponds to the Key comment field content; * Then click the Save private key button & choose whatever filename you'd like (you can save it in the same location as the public key, but it should be a location that only you can access and that you will NOT lose!). Keep the file extension to '''.ppk''' ===Putting the key on the server=== To put the key on the server, we need to use not the public key file, as the file itself is in a format that OpenSSH doesn't recognize. So we can again open PuTTyGen, click ''load'' to load an existing private key file, and select the private key from the safe folder used below. After entering the passphrase (twice) we see the same information as before (see pic above). From the PuTTyGen interface, we select & copy to clipboard the information in the top window, something like ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAgEAjisviHZ19eU0F5BtN+F32tcjO72Ne 82Br24XS5cQASuYt8EZXBP1bdh0JFX7KvJIBMzH6KXo0gZQv/UtX4q+9jV9xgCgWq IAM+WKEVexAkR1RjFc8Bf8pPK62eNsis959+XD0IuuH7Ge/JKTy6ScxU+nyIfBJr/ a894TNPwdCEAbnBdU6WX/Q7g3P7xVaMu2g5okLRkO1tt7wIlt0zrOx86hMvesmIwX CfZ8qJtp8frmpoxbbCn9akgDPRtmMUEJDDkgrW6oyyMCtCgH0iTEZf3RYq4aOdXAI bJE9Yu402BPmyZCSDBrqwYfEWn0FgtEsjTlc7TTnUq+X35ndCpwE+g4AV3Fle7e18 eNyqvb3ng2+nSj4uNj2fFqlfNrJXfZGVELmk7xnVH1ypP6WamFHxG81wAqkGnBA2q W1ItvJxZ3L3mfHX5LKUxMMXbw5hElXtVQI+ZiDPjFqCIqPXagYzIsh/XzKbXoxZnR abcc14wGdPM+3TuAgyARoVuYyMb6iJz7SMrf1OAvMD6P7AcY5l7PeFG88ABJc67kS fPAyZRrK7uHllh2P3B3lEzIWrXYvKqjMoOOQj0uAhHtmFVtDvu/bHgJ2BWrTYq9AI g7AY59QnzK0LO8BxAoTSTKuUNpj+9WP7FUNL60nejm6A68PXQRddVrAZ2SYUuTUB+ /pU0= Joe Sixpack Note that on pasting this information in e.g. Notepad, then it should be a ''single'' line of information. On a sidenote, if you need the private key in an ''OpenSSH'' or ''ssh.com'' compatible form, you can use the Conversions tab on the toolbar. Next, we open a PuTTy SSH session to the server, change directory to the user's home directory (e.g. ''/home/jsixpack''), and in this home directory go into the ''.ssh'' directory. Inside that directory there should be a file ''authorized_keys''. If it's not there, create it with the user as owner and read/write for the user only. In the example of user ''jsixpack'': cd /home/jsixpack/.ssh touch authorized_keys chmod 600 authorized_keys Then open this file with [[Vim|vi]], and copy the public key in there. Again, it should be a single line, beginning with ''ssh-rsa AAAA'' and ending with the key comment. Save with '':qw'' and the key is stored! ===Configuring the SSH server=== To ensure that the SSH server accepts SSH keys, add the following to ''/etc/ssh/sshd_config'', or at least confirm the lines are already there: RSAAuthentication yes PubkeyAuthentication yes AuthorizedKeysFile %h/.ssh/authorized_keys If you've changed any of these settings, restart the SSH server to ensure they're implemented. Then test if you can log in to the server with your SSH key (see next session). Once you've ensured you can log into the server using only the key and it's associated passphrase, you may wish to disable password-based login. To configure the SSH server to ''not'' accept passwords any more, add the following (or confirm it's already set): ChallengeResponseAuthentication no PasswordAuthentication no Again, restart the server if you've changed these settings. BEWARE! If you haven't properly tested logging in with a key, and you disable password-based login, then you've shut yourself out. Only access to the console can then restore your access... ===Configuring PuTTy to use the SSH key=== You've added your public key to the server, now add your private key to your PuTTy session information. c18fbb2d3f9e5f5a06c33fc7846fd17e39104c62 3069 3068 2014-10-26T20:32:47Z Saruman! 2 typos wikitext text/x-wiki ==OpenSSH Server== This package is essential when you want to be able to (safely) administer your server from another place than the console. To install: simpy use ''sudo aptitude install openssh-server''. This will install the OpenSSH server, plus the OpenSSH client. Since the SSL vulnerbility of may '08, also the ssh-blacklist package is downloaded. After installing, we need to make the following changes to the default settings in file ''/etc/ssh/sshd-config'': * line ''PermitRootLogin yes'' should be set to ''no'', so that user ''root'' CANNOT log in over SSH! ([http://www.debian-administration.org/articles/573 big security gap!]). * add a line ''AllowGroups wheel''; adding this ensures that NOBODY can log in over SSH unless you specifically assigned them to the ''wheel'' group, reducing the attack surface of your SSH user. Should you need more than one group (e.g. you want to add the group "ldapwheel"), then add the groups separated by spaces: ''AllowGroups wheel ldapwheel''. * Change your banner by editing the [[MOTD file]]. Next, make sure the ''wheel'' group exist, and add all users to it that are allowed ssh-access: groupadd -g 117 wheel usermod -a -G wheel jan In the groupadd line, the groupID is explicitly set to 117, but this really is optional. In the usermod line, be sure to use the ''-a'' so that your user gets the ssh-users group added, instead of replacing all supplementary groups with this one ssh-users. If you've added a group that exists in your LDAP server, make sure that those LDAP users are member of that group that you want to give SSH access. This is ofcourse managed from your LDAP management console (be it the commandline ''ldapmodify'' or a graphic tool like [[Filling_an_OpenLDAP_database#Adding_a_user_with_LAM | LDAP Account Manager]] When all this is changed, the service should be restarted with ''sudo /etc/init.d/ssh restart''. One of the nice things of a correctly configured SSH server, is the ability to use [[scp]] to copy files between machines. == Changing RSA keys == Occasionally you'll find the RSA key of one of your machines has changed. This may have a number of reasons, a.o. a reinstall or migration of said machine. In any case, when you try to SSH to the machine you get a message like this: localhost:~# '''ssh insomnia@easton.saruman.biz''' @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @ WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED! @ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ IT IS POSSIBLE THAT SOMEONE IS DOING SOMETHING NASTY! Someone could be eavesdropping on you right now (man-in-the-middle attack)! It is also possible that the RSA host key has just been changed. The fingerprint for the RSA key sent by the remote host is f7:1a:5a:11:ca:20:99:fa:db:1b:b8:75:8e:e5:f1:12. Please contact your system administrator. Add correct host key in /home/sixpacjo/.ssh/known_hosts to get rid of this message. Offending key in /home/sixpacjo/.ssh/known_hosts:4 RSA host key for easton.saruman.biz has changed and you have requested strict checking. Host key verification failed. localhost:~# _ When you get this message it is not possible to connect to the machine mentioned, until you've solved the problem of the RSA key. There are multiple ways to correct the key, but the simplest method seems to be to simply remove the offending key with ''ssh-keygen''. Note that Debian "Lenny" stores the RSA key in ''two'' places: one for the host name, one for the IP number. To prevent annoying messages like this: Warning: the RSA host key for 'easton.saruman.biz' differs from the key for the IP address '192.168.67.5' Offending key for IP in /home/sixpacjo/.ssh/known_hosts:4 you should remove the RSA key for the IP number as well. This you do with the following two commands: localhost:~# '''ssh-keygen -R easton.saruman.biz''' /home/sixpacjo/.ssh/known_hosts updated. Original contents retained as /home/sixpacjo/.ssh/known_hosts.old localhost:~# '''ssh-keygen -R 192.168.67.5''' /home/sixpacjo/.ssh/known_hosts updated. Original contents retained as /home/sixpacjo/.ssh/known_hosts.old localhost:~# _ After deleting the "offending RSA keys" like this, you can SSH to the box in question, and your SSH client will save the (new) RSA key for you in your ''known_hosts'' file. ==Using SSH keys for SSH login== If your server is open to the Internet, passwords alone may not be safe enough. Plenty of malicious folks will try to brute-force attack your SSH server. Of course you've disabled root login (right? RIGHT?!?) but still... all that attacking clutters your logs, and maybe one day one of your SSH user passwords turns out too weak. That's why it's a good idea to add SSH keys to the mix. ===Generating an SSH key=== You can generate an SSH key from Linux itself (see [https://www.digitalocean.com/community/tutorials/how-to-set-up-ssh-keys--2 DigitalOcean], but in this article we'll use [http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html PuTTy], because PuTTy/WinSCP is the go-to tool set for Linux administration from a Windows workstation, and PuTTy's [http://www.chiark.greenend.org.uk/~sgtatham/putty/wishlist/key-formats-natively.html proprietary key management] provides some nifty tricks for key management. (based on [https://www.digitalocean.com/community/tutorials/how-to-create-ssh-keys-with-putty-to-connect-to-a-vps DigitalOcean howto]) First we start the PuTTyGen utility, by double-clicking on its .exe file. * At the bottom of the interface, for Type of key to generate, select SSH-2 RSA; * In the Number of bits in a generated key field, specify either 2048 or 4096 (the latter is safer, but takes longer to generate); * Now click the Generate button. PuTTyGen needs some entropy, so move your mouse pointer around in the blank area of the Key section for a while until the progress bar is full - a private/ public key pair will then be generated; * In the Key comment field, enter your name (or any other comment you'd like), to help you identify this key pair. This is particularly useful in the event you end up creating more than one key pair; * A passphrase is optional but recommended: Type & re-type it in the Key passphrase fields. (Really, only leave out the passphrase if you would like to use this particular key pair for automated processes!) The above actions should look a bit like this: [[File:Puttygen.png|PuTTyGen interface]] * Now click the Save public key button & choose whatever filename you'd like, saving it in a "safe" folder. I'd recommend a filename that corresponds to the Key comment field content; * Then click the Save private key button & choose whatever filename you'd like (you can save it in the same location as the public key, but it should be a location that only you can access and that you will NOT lose!). Keep the file extension to '''.ppk''' ===Putting the key on the server=== To put the key on the server, we need to use not the public key file, as the file itself is in a format that OpenSSH doesn't recognize. So we can again open PuTTyGen, click ''load'' to load an existing private key file, and select the private key from the safe folder used below. After entering the passphrase (twice) we see the same information as before (see pic above). From the PuTTyGen interface, we select & copy to clipboard the information in the top window, something like ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAgEAjisviHZ19eU0F5BtN+F32tcjO72Ne 82Br24XS5cQASuYt8EZXBP1bdh0JFX7KvJIBMzH6KXo0gZQv/UtX4q+9jV9xgCgWq IAM+WKEVexAkR1RjFc8Bf8pPK62eNsis959+XD0IuuH7Ge/JKTy6ScxU+nyIfBJr/ a894TNPwdCEAbnBdU6WX/Q7g3P7xVaMu2g5okLRkO1tt7wIlt0zrOx86hMvesmIwX CfZ8qJtp8frmpoxbbCn9akgDPRtmMUEJDDkgrW6oyyMCtCgH0iTEZf3RYq4aOdXAI bJE9Yu402BPmyZCSDBrqwYfEWn0FgtEsjTlc7TTnUq+X35ndCpwE+g4AV3Fle7e18 eNyqvb3ng2+nSj4uNj2fFqlfNrJXfZGVELmk7xnVH1ypP6WamFHxG81wAqkGnBA2q W1ItvJxZ3L3mfHX5LKUxMMXbw5hElXtVQI+ZiDPjFqCIqPXagYzIsh/XzKbXoxZnR abcc14wGdPM+3TuAgyARoVuYyMb6iJz7SMrf1OAvMD6P7AcY5l7PeFG88ABJc67kS fPAyZRrK7uHllh2P3B3lEzIWrXYvKqjMoOOQj0uAhHtmFVtDvu/bHgJ2BWrTYq9AI g7AY59QnzK0LO8BxAoTSTKuUNpj+9WP7FUNL60nejm6A68PXQRddVrAZ2SYUuTUB+ /pU0= Joe Sixpack Note that on pasting this information in e.g. Notepad, then it should be a ''single'' line of information. On a sidenote, if you need the private key in an ''OpenSSH'' or ''ssh.com'' compatible form, you can use the Conversions tab on the toolbar. Next, we open a PuTTy SSH session to the server, change directory to the user's home directory (e.g. ''/home/jsixpack''), and in this home directory go into the ''.ssh'' directory. Inside that directory there should be a file ''authorized_keys''. If it's not there, create it with the user as owner and read/write for the user only. In the example of user ''jsixpack'': cd /home/jsixpack/.ssh touch authorized_keys chmod 600 authorized_keys Then open this file with [[Vim|vi]], and copy the public key in there. Again, it should be a single line, beginning with ''ssh-rsa AAAA'' and ending with the key comment. Save with '':qw'' and the key is stored! ===Configuring the SSH server=== To ensure that the SSH server accepts SSH keys, add the following to ''/etc/ssh/sshd_config'', or at least confirm the lines are already there: RSAAuthentication yes PubkeyAuthentication yes AuthorizedKeysFile %h/.ssh/authorized_keys If you've changed any of these settings, restart the SSH server to ensure they're implemented. Then test if you can log in to the server with your SSH key (see next session). Once you've ensured you can log into the server using only the key and it's associated passphrase, you may wish to disable password-based login. To configure the SSH server to ''not'' accept passwords any more, add the following (or confirm it's already set): ChallengeResponseAuthentication no PasswordAuthentication no Again, restart the server if you've changed these settings. BEWARE! If you haven't properly tested logging in with a key, and you disable password-based login, then you've shut yourself out. Only access to the console can then restore your access... ===Configuring PuTTy to use the SSH key=== You've added your public key to the server, now add your private key to your PuTTy session information. 8ebdc57c5b1a80cd9f74aff6b6e4a28970275a1a 3076 3069 2015-12-16T15:28:57Z Saruman! 2 typo's wikitext text/x-wiki ==OpenSSH Server== This package is essential when you want to be able to (safely) administer your server from another place than the console. To install: simpy use ''sudo aptitude install openssh-server''. This will install the OpenSSH server, plus the OpenSSH client. Since the SSL vulnerbility of may '08, also the ssh-blacklist package is downloaded. After installing, we need to make the following changes to the default settings in file ''/etc/ssh/sshd-config'': * line ''PermitRootLogin yes'' should be set to ''no'', so that user ''root'' CANNOT log in over SSH! ([http://www.debian-administration.org/articles/573 big security gap!]). * add a line ''AllowGroups wheel''; adding this ensures that NOBODY can log in over SSH unless you specifically assigned them to the ''wheel'' group, reducing the attack surface of your SSH user. Should you need more than one group (e.g. you want to add the group "ldapwheel"), then add the groups separated by spaces: ''AllowGroups wheel ldapwheel''. * Change your banner by editing the [[MOTD file]]. Next, make sure the ''wheel'' group exist, and add all users to it that are allowed ssh-access: groupadd -g 117 wheel usermod -a -G wheel jan In the groupadd line, the groupID is explicitly set to 117, but this really is optional. In the usermod line, be sure to use the ''-a'' so that your user gets the ssh-users group added, instead of replacing all supplementary groups with this one ssh-users. If you've added a group that exists in your LDAP server, make sure that those LDAP users are member of that group that you want to give SSH access. This is ofcourse managed from your LDAP management console (be it the commandline ''ldapmodify'' or a graphic tool like [[Filling_an_OpenLDAP_database#Adding_a_user_with_LAM | LDAP Account Manager]] When all this is changed, the service should be restarted with ''sudo /etc/init.d/ssh restart''. One of the nice things of a correctly configured SSH server, is the ability to use [[scp]] to copy files between machines. == Changing RSA keys == Occasionally you'll find the RSA key of one of your machines has changed. This may have a number of reasons, a.o. a reinstall or migration of said machine. In any case, when you try to SSH to the machine you get a message like this: localhost:~# '''ssh insomnia@easton.saruman.biz''' @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @ WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED! @ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ IT IS POSSIBLE THAT SOMEONE IS DOING SOMETHING NASTY! Someone could be eavesdropping on you right now (man-in-the-middle attack)! It is also possible that the RSA host key has just been changed. The fingerprint for the RSA key sent by the remote host is f7:1a:5a:11:ca:20:99:fa:db:1b:b8:75:8e:e5:f1:12. Please contact your system administrator. Add correct host key in /home/sixpacjo/.ssh/known_hosts to get rid of this message. Offending key in /home/sixpacjo/.ssh/known_hosts:4 RSA host key for easton.saruman.biz has changed and you have requested strict checking. Host key verification failed. localhost:~# _ When you get this message it is not possible to connect to the machine mentioned, until you've solved the problem of the RSA key. There are multiple ways to correct the key, but the simplest method seems to be to simply remove the offending key with ''ssh-keygen''. Note that Debian "Lenny" stores the RSA key in ''two'' places: one for the host name, one for the IP number. To prevent annoying messages like this: Warning: the RSA host key for 'easton.saruman.biz' differs from the key for the IP address '192.168.67.5' Offending key for IP in /home/sixpacjo/.ssh/known_hosts:4 you should remove the RSA key for the IP number as well. This you do with the following two commands: localhost:~# '''ssh-keygen -R easton.saruman.biz''' /home/sixpacjo/.ssh/known_hosts updated. Original contents retained as /home/sixpacjo/.ssh/known_hosts.old localhost:~# '''ssh-keygen -R 192.168.67.5''' /home/sixpacjo/.ssh/known_hosts updated. Original contents retained as /home/sixpacjo/.ssh/known_hosts.old localhost:~# _ After deleting the "offending RSA keys" like this, you can SSH to the box in question, and your SSH client will save the (new) RSA key for you in your ''known_hosts'' file. ==Using SSH keys for SSH login== If your server is open to the Internet, passwords alone may not be safe enough. Plenty of malicious folks will try to brute-force attack your SSH server. Of course you've disabled root login (right? RIGHT?!?) but still... all that attacking clutters your logs, and maybe one day one of your SSH user passwords turns out too weak. That's why it's a good idea to add SSH keys to the mix. What we're going to do is create an SSH key pair: a public key that we can store on the server, and a private key that we'll use on our end when we connect with the server. ===Generating an SSH key=== You can generate an SSH key from Linux itself (see [https://www.digitalocean.com/community/tutorials/how-to-set-up-ssh-keys--2 DigitalOcean], but in this article we'll use [http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html PuTTy], because PuTTy/WinSCP is the go-to tool set for Linux administration from a Windows workstation, and PuTTy's [http://www.chiark.greenend.org.uk/~sgtatham/putty/wishlist/key-formats-natively.html proprietary key management] provides some nifty tricks for key management. (based on [https://www.digitalocean.com/community/tutorials/how-to-create-ssh-keys-with-putty-to-connect-to-a-vps DigitalOcean howto]) First we start the PuTTyGen utility, by double-clicking on its .exe file. * At the bottom of the interface, for Type of key to generate, select SSH-2 RSA; * In the Number of bits in a generated key field, specify either 2048 or 4096 (the latter is safer, but takes longer to generate); * Now click the Generate button. PuTTyGen needs some entropy, so move your mouse pointer around in the blank area of the Key section for a while until the progress bar is full - a private/ public key pair will then be generated; * In the Key comment field, enter your name (or any other comment you'd like), to help you identify this key pair. This is particularly useful in the event you end up creating more than one key pair; * A passphrase is optional but recommended: Type & re-type it in the Key passphrase fields. (Really, only leave out the passphrase if you would like to use this particular key pair for automated processes!) The above actions should look a bit like this: [[File:Puttygen.png|PuTTyGen interface]] * Now click the Save public key button & choose whatever filename you'd like, saving it in a "safe" folder. I'd recommend a filename that corresponds to the Key comment field content; * Then click the Save private key button & choose whatever filename you'd like (you can save it in the same location as the public key, but it should be a location that only you can access and that you will NOT lose!). Keep the file extension to '''.ppk''' ===Putting the public key on the server=== To put the key on the server, we need to use not the public key ''file'', as the file itself is in a format that OpenSSH doesn't recognize. So we can again open PuTTyGen, click ''load'' to load an existing private key file, and select the private key from the safe folder used below. After entering the passphrase (twice) we see the same information as before (see pic above). From the PuTTyGen interface, we select & copy to clipboard the information in the top window - which is the public key, something like ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAgEAjisviHZ19eU0F5BtN+F32tcjO72Ne 82Br24XS5cQASuYt8EZXBP1bdh0JFX7KvJIBMzH6KXo0gZQv/UtX4q+9jV9xgCgWq IAM+WKEVexAkR1RjFc8Bf8pPK62eNsis959+XD0IuuH7Ge/JKTy6ScxU+nyIfBJr/ a894TNPwdCEAbnBdU6WX/Q7g3P7xVaMu2g5okLRkO1tt7wIlt0zrOx86hMvesmIwX CfZ8qJtp8frmpoxbbCn9akgDPRtmMUEJDDkgrW6oyyMCtCgH0iTEZf3RYq4aOdXAI bJE9Yu402BPmyZCSDBrqwYfEWn0FgtEsjTlc7TTnUq+X35ndCpwE+g4AV3Fle7e18 eNyqvb3ng2+nSj4uNj2fFqlfNrJXfZGVELmk7xnVH1ypP6WamFHxG81wAqkGnBA2q W1ItvJxZ3L3mfHX5LKUxMMXbw5hElXtVQI+ZiDPjFqCIqPXagYzIsh/XzKbXoxZnR abcc14wGdPM+3TuAgyARoVuYyMb6iJz7SMrf1OAvMD6P7AcY5l7PeFG88ABJc67kS fPAyZRrK7uHllh2P3B3lEzIWrXYvKqjMoOOQj0uAhHtmFVtDvu/bHgJ2BWrTYq9AI g7AY59QnzK0LO8BxAoTSTKuUNpj+9WP7FUNL60nejm6A68PXQRddVrAZ2SYUuTUB+ /pU0= Joe Sixpack Note that on pasting this information in e.g. Notepad, then it should be a ''single'' line of information. On a side note, if you need the ''private'' key in an ''OpenSSH'' or ''ssh.com'' compatible form, you can use the Conversions tab on the toolbar. Next, we open a PuTTy SSH session to the server, change directory to the user's home directory (e.g. ''/home/jsixpack''), and in this home directory go into the ''.ssh'' directory. Inside that directory there should be a file ''authorized_keys''. If it's not there, create it with the user as owner and read/write for the user only. In the example of user ''jsixpack'': cd /home/jsixpack/.ssh touch authorized_keys chmod 600 authorized_keys Then open this file with [[Vim|vi]], and copy the public key in there. Again, it should be a single line, beginning with ''ssh-rsa AAAA'' and ending with the key comment. Save with '':wq'' and the key is stored! ===Configuring the SSH server=== To ensure that the SSH server accepts SSH keys, add the following to ''/etc/ssh/sshd_config'', or at least confirm the lines are already there: RSAAuthentication yes PubkeyAuthentication yes AuthorizedKeysFile %h/.ssh/authorized_keys If you've changed any of these settings, restart the SSH server to ensure they're implemented. Then test if you can log in to the server with your SSH key (see next section). Once you've ensured you can log into the server using only the key and it's associated passphrase, you may wish to disable password-based login. To configure the SSH server to ''not'' accept passwords any more, add the following (or confirm it's already set): ChallengeResponseAuthentication no PasswordAuthentication no Again, restart the server if you've changed these settings. BEWARE! If you haven't properly tested logging in with a key, and you disable password-based login, then you've shut yourself out. Only access to the console can then restore your access... ===Configuring PuTTy to use the SSH key=== You've added your public key to the server, now add your private key to your PuTTy session information. d18dda828026ba735648f38673682e37b0275336 3078 3076 2016-02-21T15:16:05Z Saruman! 2 /* Configuring PuTTy to use the SSH key */ wikitext text/x-wiki ==OpenSSH Server== This package is essential when you want to be able to (safely) administer your server from another place than the console. To install: simpy use ''sudo aptitude install openssh-server''. This will install the OpenSSH server, plus the OpenSSH client. Since the SSL vulnerbility of may '08, also the ssh-blacklist package is downloaded. After installing, we need to make the following changes to the default settings in file ''/etc/ssh/sshd-config'': * line ''PermitRootLogin yes'' should be set to ''no'', so that user ''root'' CANNOT log in over SSH! ([http://www.debian-administration.org/articles/573 big security gap!]). * add a line ''AllowGroups wheel''; adding this ensures that NOBODY can log in over SSH unless you specifically assigned them to the ''wheel'' group, reducing the attack surface of your SSH user. Should you need more than one group (e.g. you want to add the group "ldapwheel"), then add the groups separated by spaces: ''AllowGroups wheel ldapwheel''. * Change your banner by editing the [[MOTD file]]. Next, make sure the ''wheel'' group exist, and add all users to it that are allowed ssh-access: groupadd -g 117 wheel usermod -a -G wheel jan In the groupadd line, the groupID is explicitly set to 117, but this really is optional. In the usermod line, be sure to use the ''-a'' so that your user gets the ssh-users group added, instead of replacing all supplementary groups with this one ssh-users. If you've added a group that exists in your LDAP server, make sure that those LDAP users are member of that group that you want to give SSH access. This is ofcourse managed from your LDAP management console (be it the commandline ''ldapmodify'' or a graphic tool like [[Filling_an_OpenLDAP_database#Adding_a_user_with_LAM | LDAP Account Manager]] When all this is changed, the service should be restarted with ''sudo /etc/init.d/ssh restart''. One of the nice things of a correctly configured SSH server, is the ability to use [[scp]] to copy files between machines. == Changing RSA keys == Occasionally you'll find the RSA key of one of your machines has changed. This may have a number of reasons, a.o. a reinstall or migration of said machine. In any case, when you try to SSH to the machine you get a message like this: localhost:~# '''ssh insomnia@easton.saruman.biz''' @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @ WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED! @ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ IT IS POSSIBLE THAT SOMEONE IS DOING SOMETHING NASTY! Someone could be eavesdropping on you right now (man-in-the-middle attack)! It is also possible that the RSA host key has just been changed. The fingerprint for the RSA key sent by the remote host is f7:1a:5a:11:ca:20:99:fa:db:1b:b8:75:8e:e5:f1:12. Please contact your system administrator. Add correct host key in /home/sixpacjo/.ssh/known_hosts to get rid of this message. Offending key in /home/sixpacjo/.ssh/known_hosts:4 RSA host key for easton.saruman.biz has changed and you have requested strict checking. Host key verification failed. localhost:~# _ When you get this message it is not possible to connect to the machine mentioned, until you've solved the problem of the RSA key. There are multiple ways to correct the key, but the simplest method seems to be to simply remove the offending key with ''ssh-keygen''. Note that Debian "Lenny" stores the RSA key in ''two'' places: one for the host name, one for the IP number. To prevent annoying messages like this: Warning: the RSA host key for 'easton.saruman.biz' differs from the key for the IP address '192.168.67.5' Offending key for IP in /home/sixpacjo/.ssh/known_hosts:4 you should remove the RSA key for the IP number as well. This you do with the following two commands: localhost:~# '''ssh-keygen -R easton.saruman.biz''' /home/sixpacjo/.ssh/known_hosts updated. Original contents retained as /home/sixpacjo/.ssh/known_hosts.old localhost:~# '''ssh-keygen -R 192.168.67.5''' /home/sixpacjo/.ssh/known_hosts updated. Original contents retained as /home/sixpacjo/.ssh/known_hosts.old localhost:~# _ After deleting the "offending RSA keys" like this, you can SSH to the box in question, and your SSH client will save the (new) RSA key for you in your ''known_hosts'' file. ==Using SSH keys for SSH login== If your server is open to the Internet, passwords alone may not be safe enough. Plenty of malicious folks will try to brute-force attack your SSH server. Of course you've disabled root login (right? RIGHT?!?) but still... all that attacking clutters your logs, and maybe one day one of your SSH user passwords turns out too weak. That's why it's a good idea to add SSH keys to the mix. What we're going to do is create an SSH key pair: a public key that we can store on the server, and a private key that we'll use on our end when we connect with the server. ===Generating an SSH key=== You can generate an SSH key from Linux itself (see [https://www.digitalocean.com/community/tutorials/how-to-set-up-ssh-keys--2 DigitalOcean], but in this article we'll use [http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html PuTTy], because PuTTy/WinSCP is the go-to tool set for Linux administration from a Windows workstation, and PuTTy's [http://www.chiark.greenend.org.uk/~sgtatham/putty/wishlist/key-formats-natively.html proprietary key management] provides some nifty tricks for key management. (based on [https://www.digitalocean.com/community/tutorials/how-to-create-ssh-keys-with-putty-to-connect-to-a-vps DigitalOcean howto]) First we start the PuTTyGen utility, by double-clicking on its .exe file. * At the bottom of the interface, for Type of key to generate, select SSH-2 RSA; * In the Number of bits in a generated key field, specify either 2048 or 4096 (the latter is safer, but takes longer to generate); * Now click the Generate button. PuTTyGen needs some entropy, so move your mouse pointer around in the blank area of the Key section for a while until the progress bar is full - a private/ public key pair will then be generated; * In the Key comment field, enter your name (or any other comment you'd like), to help you identify this key pair. This is particularly useful in the event you end up creating more than one key pair; * A passphrase is optional but recommended: Type & re-type it in the Key passphrase fields. (Really, only leave out the passphrase if you would like to use this particular key pair for automated processes!) The above actions should look a bit like this: [[File:Puttygen.png|PuTTyGen interface]] * Now click the Save public key button & choose whatever filename you'd like, saving it in a "safe" folder. I'd recommend a filename that corresponds to the Key comment field content; * Then click the Save private key button & choose whatever filename you'd like (you can save it in the same location as the public key, but it should be a location that only you can access and that you will NOT lose!). Keep the file extension to '''.ppk''' ===Putting the public key on the server=== To put the key on the server, we need to use not the public key ''file'', as the file itself is in a format that OpenSSH doesn't recognize. So we can again open PuTTyGen, click ''load'' to load an existing private key file, and select the private key from the safe folder used below. After entering the passphrase (twice) we see the same information as before (see pic above). From the PuTTyGen interface, we select & copy to clipboard the information in the top window - which is the public key, something like ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAgEAjisviHZ19eU0F5BtN+F32tcjO72Ne 82Br24XS5cQASuYt8EZXBP1bdh0JFX7KvJIBMzH6KXo0gZQv/UtX4q+9jV9xgCgWq IAM+WKEVexAkR1RjFc8Bf8pPK62eNsis959+XD0IuuH7Ge/JKTy6ScxU+nyIfBJr/ a894TNPwdCEAbnBdU6WX/Q7g3P7xVaMu2g5okLRkO1tt7wIlt0zrOx86hMvesmIwX CfZ8qJtp8frmpoxbbCn9akgDPRtmMUEJDDkgrW6oyyMCtCgH0iTEZf3RYq4aOdXAI bJE9Yu402BPmyZCSDBrqwYfEWn0FgtEsjTlc7TTnUq+X35ndCpwE+g4AV3Fle7e18 eNyqvb3ng2+nSj4uNj2fFqlfNrJXfZGVELmk7xnVH1ypP6WamFHxG81wAqkGnBA2q W1ItvJxZ3L3mfHX5LKUxMMXbw5hElXtVQI+ZiDPjFqCIqPXagYzIsh/XzKbXoxZnR abcc14wGdPM+3TuAgyARoVuYyMb6iJz7SMrf1OAvMD6P7AcY5l7PeFG88ABJc67kS fPAyZRrK7uHllh2P3B3lEzIWrXYvKqjMoOOQj0uAhHtmFVtDvu/bHgJ2BWrTYq9AI g7AY59QnzK0LO8BxAoTSTKuUNpj+9WP7FUNL60nejm6A68PXQRddVrAZ2SYUuTUB+ /pU0= Joe Sixpack Note that on pasting this information in e.g. Notepad, then it should be a ''single'' line of information. On a side note, if you need the ''private'' key in an ''OpenSSH'' or ''ssh.com'' compatible form, you can use the Conversions tab on the toolbar. Next, we open a PuTTy SSH session to the server, change directory to the user's home directory (e.g. ''/home/jsixpack''), and in this home directory go into the ''.ssh'' directory. Inside that directory there should be a file ''authorized_keys''. If it's not there, create it with the user as owner and read/write for the user only. In the example of user ''jsixpack'': cd /home/jsixpack/.ssh touch authorized_keys chmod 600 authorized_keys Then open this file with [[Vim|vi]], and copy the public key in there. Again, it should be a single line, beginning with ''ssh-rsa AAAA'' and ending with the key comment. Save with '':wq'' and the key is stored! ===Configuring the SSH server=== To ensure that the SSH server accepts SSH keys, add the following to ''/etc/ssh/sshd_config'', or at least confirm the lines are already there: RSAAuthentication yes PubkeyAuthentication yes AuthorizedKeysFile %h/.ssh/authorized_keys If you've changed any of these settings, restart the SSH server to ensure they're implemented. Then test if you can log in to the server with your SSH key (see next section). Once you've ensured you can log into the server using only the key and it's associated passphrase, you may wish to disable password-based login. To configure the SSH server to ''not'' accept passwords any more, add the following (or confirm it's already set): ChallengeResponseAuthentication no PasswordAuthentication no Again, restart the server if you've changed these settings. BEWARE! If you haven't properly tested logging in with a key, and you disable password-based login, then you've shut yourself out. Only access to the console can then restore your access... ===Configuring PuTTy to use the SSH key=== You've added your public key to the server, now add your private key to your PuTTy session information. To this end, put your private key in a secure spot accessible from your system. For example, on a secure (encrypted) USB stick. In this example I use a subdirectory of the Documents directory, named Keychain. Now configure your PuTTy connection like you always would, but also go to the settings category Connection, subsection SSH, subsection Auth. There you'll find a Private key file section, from which you can browse to your .ppk private key file. It should look like this: [[File:Puttyprivatekey.png|467px]] That's it. You can now log on to your server using PuTTy, and when connecting Putty will ask for the passphrase, but not for any password local to the server. b9623f0e2c28773f66c2112892770bbc4eb84092 3079 3078 2016-02-21T15:16:20Z Saruman! 2 /* Configuring PuTTy to use the SSH key */ wikitext text/x-wiki ==OpenSSH Server== This package is essential when you want to be able to (safely) administer your server from another place than the console. To install: simpy use ''sudo aptitude install openssh-server''. This will install the OpenSSH server, plus the OpenSSH client. Since the SSL vulnerbility of may '08, also the ssh-blacklist package is downloaded. After installing, we need to make the following changes to the default settings in file ''/etc/ssh/sshd-config'': * line ''PermitRootLogin yes'' should be set to ''no'', so that user ''root'' CANNOT log in over SSH! ([http://www.debian-administration.org/articles/573 big security gap!]). * add a line ''AllowGroups wheel''; adding this ensures that NOBODY can log in over SSH unless you specifically assigned them to the ''wheel'' group, reducing the attack surface of your SSH user. Should you need more than one group (e.g. you want to add the group "ldapwheel"), then add the groups separated by spaces: ''AllowGroups wheel ldapwheel''. * Change your banner by editing the [[MOTD file]]. Next, make sure the ''wheel'' group exist, and add all users to it that are allowed ssh-access: groupadd -g 117 wheel usermod -a -G wheel jan In the groupadd line, the groupID is explicitly set to 117, but this really is optional. In the usermod line, be sure to use the ''-a'' so that your user gets the ssh-users group added, instead of replacing all supplementary groups with this one ssh-users. If you've added a group that exists in your LDAP server, make sure that those LDAP users are member of that group that you want to give SSH access. This is ofcourse managed from your LDAP management console (be it the commandline ''ldapmodify'' or a graphic tool like [[Filling_an_OpenLDAP_database#Adding_a_user_with_LAM | LDAP Account Manager]] When all this is changed, the service should be restarted with ''sudo /etc/init.d/ssh restart''. One of the nice things of a correctly configured SSH server, is the ability to use [[scp]] to copy files between machines. == Changing RSA keys == Occasionally you'll find the RSA key of one of your machines has changed. This may have a number of reasons, a.o. a reinstall or migration of said machine. In any case, when you try to SSH to the machine you get a message like this: localhost:~# '''ssh insomnia@easton.saruman.biz''' @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @ WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED! @ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ IT IS POSSIBLE THAT SOMEONE IS DOING SOMETHING NASTY! Someone could be eavesdropping on you right now (man-in-the-middle attack)! It is also possible that the RSA host key has just been changed. The fingerprint for the RSA key sent by the remote host is f7:1a:5a:11:ca:20:99:fa:db:1b:b8:75:8e:e5:f1:12. Please contact your system administrator. Add correct host key in /home/sixpacjo/.ssh/known_hosts to get rid of this message. Offending key in /home/sixpacjo/.ssh/known_hosts:4 RSA host key for easton.saruman.biz has changed and you have requested strict checking. Host key verification failed. localhost:~# _ When you get this message it is not possible to connect to the machine mentioned, until you've solved the problem of the RSA key. There are multiple ways to correct the key, but the simplest method seems to be to simply remove the offending key with ''ssh-keygen''. Note that Debian "Lenny" stores the RSA key in ''two'' places: one for the host name, one for the IP number. To prevent annoying messages like this: Warning: the RSA host key for 'easton.saruman.biz' differs from the key for the IP address '192.168.67.5' Offending key for IP in /home/sixpacjo/.ssh/known_hosts:4 you should remove the RSA key for the IP number as well. This you do with the following two commands: localhost:~# '''ssh-keygen -R easton.saruman.biz''' /home/sixpacjo/.ssh/known_hosts updated. Original contents retained as /home/sixpacjo/.ssh/known_hosts.old localhost:~# '''ssh-keygen -R 192.168.67.5''' /home/sixpacjo/.ssh/known_hosts updated. Original contents retained as /home/sixpacjo/.ssh/known_hosts.old localhost:~# _ After deleting the "offending RSA keys" like this, you can SSH to the box in question, and your SSH client will save the (new) RSA key for you in your ''known_hosts'' file. ==Using SSH keys for SSH login== If your server is open to the Internet, passwords alone may not be safe enough. Plenty of malicious folks will try to brute-force attack your SSH server. Of course you've disabled root login (right? RIGHT?!?) but still... all that attacking clutters your logs, and maybe one day one of your SSH user passwords turns out too weak. That's why it's a good idea to add SSH keys to the mix. What we're going to do is create an SSH key pair: a public key that we can store on the server, and a private key that we'll use on our end when we connect with the server. ===Generating an SSH key=== You can generate an SSH key from Linux itself (see [https://www.digitalocean.com/community/tutorials/how-to-set-up-ssh-keys--2 DigitalOcean], but in this article we'll use [http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html PuTTy], because PuTTy/WinSCP is the go-to tool set for Linux administration from a Windows workstation, and PuTTy's [http://www.chiark.greenend.org.uk/~sgtatham/putty/wishlist/key-formats-natively.html proprietary key management] provides some nifty tricks for key management. (based on [https://www.digitalocean.com/community/tutorials/how-to-create-ssh-keys-with-putty-to-connect-to-a-vps DigitalOcean howto]) First we start the PuTTyGen utility, by double-clicking on its .exe file. * At the bottom of the interface, for Type of key to generate, select SSH-2 RSA; * In the Number of bits in a generated key field, specify either 2048 or 4096 (the latter is safer, but takes longer to generate); * Now click the Generate button. PuTTyGen needs some entropy, so move your mouse pointer around in the blank area of the Key section for a while until the progress bar is full - a private/ public key pair will then be generated; * In the Key comment field, enter your name (or any other comment you'd like), to help you identify this key pair. This is particularly useful in the event you end up creating more than one key pair; * A passphrase is optional but recommended: Type & re-type it in the Key passphrase fields. (Really, only leave out the passphrase if you would like to use this particular key pair for automated processes!) The above actions should look a bit like this: [[File:Puttygen.png|PuTTyGen interface]] * Now click the Save public key button & choose whatever filename you'd like, saving it in a "safe" folder. I'd recommend a filename that corresponds to the Key comment field content; * Then click the Save private key button & choose whatever filename you'd like (you can save it in the same location as the public key, but it should be a location that only you can access and that you will NOT lose!). Keep the file extension to '''.ppk''' ===Putting the public key on the server=== To put the key on the server, we need to use not the public key ''file'', as the file itself is in a format that OpenSSH doesn't recognize. So we can again open PuTTyGen, click ''load'' to load an existing private key file, and select the private key from the safe folder used below. After entering the passphrase (twice) we see the same information as before (see pic above). From the PuTTyGen interface, we select & copy to clipboard the information in the top window - which is the public key, something like ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAgEAjisviHZ19eU0F5BtN+F32tcjO72Ne 82Br24XS5cQASuYt8EZXBP1bdh0JFX7KvJIBMzH6KXo0gZQv/UtX4q+9jV9xgCgWq IAM+WKEVexAkR1RjFc8Bf8pPK62eNsis959+XD0IuuH7Ge/JKTy6ScxU+nyIfBJr/ a894TNPwdCEAbnBdU6WX/Q7g3P7xVaMu2g5okLRkO1tt7wIlt0zrOx86hMvesmIwX CfZ8qJtp8frmpoxbbCn9akgDPRtmMUEJDDkgrW6oyyMCtCgH0iTEZf3RYq4aOdXAI bJE9Yu402BPmyZCSDBrqwYfEWn0FgtEsjTlc7TTnUq+X35ndCpwE+g4AV3Fle7e18 eNyqvb3ng2+nSj4uNj2fFqlfNrJXfZGVELmk7xnVH1ypP6WamFHxG81wAqkGnBA2q W1ItvJxZ3L3mfHX5LKUxMMXbw5hElXtVQI+ZiDPjFqCIqPXagYzIsh/XzKbXoxZnR abcc14wGdPM+3TuAgyARoVuYyMb6iJz7SMrf1OAvMD6P7AcY5l7PeFG88ABJc67kS fPAyZRrK7uHllh2P3B3lEzIWrXYvKqjMoOOQj0uAhHtmFVtDvu/bHgJ2BWrTYq9AI g7AY59QnzK0LO8BxAoTSTKuUNpj+9WP7FUNL60nejm6A68PXQRddVrAZ2SYUuTUB+ /pU0= Joe Sixpack Note that on pasting this information in e.g. Notepad, then it should be a ''single'' line of information. On a side note, if you need the ''private'' key in an ''OpenSSH'' or ''ssh.com'' compatible form, you can use the Conversions tab on the toolbar. Next, we open a PuTTy SSH session to the server, change directory to the user's home directory (e.g. ''/home/jsixpack''), and in this home directory go into the ''.ssh'' directory. Inside that directory there should be a file ''authorized_keys''. If it's not there, create it with the user as owner and read/write for the user only. In the example of user ''jsixpack'': cd /home/jsixpack/.ssh touch authorized_keys chmod 600 authorized_keys Then open this file with [[Vim|vi]], and copy the public key in there. Again, it should be a single line, beginning with ''ssh-rsa AAAA'' and ending with the key comment. Save with '':wq'' and the key is stored! ===Configuring the SSH server=== To ensure that the SSH server accepts SSH keys, add the following to ''/etc/ssh/sshd_config'', or at least confirm the lines are already there: RSAAuthentication yes PubkeyAuthentication yes AuthorizedKeysFile %h/.ssh/authorized_keys If you've changed any of these settings, restart the SSH server to ensure they're implemented. Then test if you can log in to the server with your SSH key (see next section). Once you've ensured you can log into the server using only the key and it's associated passphrase, you may wish to disable password-based login. To configure the SSH server to ''not'' accept passwords any more, add the following (or confirm it's already set): ChallengeResponseAuthentication no PasswordAuthentication no Again, restart the server if you've changed these settings. BEWARE! If you haven't properly tested logging in with a key, and you disable password-based login, then you've shut yourself out. Only access to the console can then restore your access... ===Configuring PuTTy to use the SSH key=== You've added your public key to the server, now add your private key to your PuTTy session information. To this end, put your private key in a secure spot accessible from your system. For example, on a secure (encrypted) USB stick. In this example I use a subdirectory of the Documents directory, named Keychain. Now configure your PuTTy connection like you always would, but also go to the settings category Connection, subsection SSH, subsection Auth. There you'll find a Private key file section, from which you can browse to your .ppk private key file. It should look like this: [[File:Puttyprivatekey.png|467px]] That's it. You can now log on to your server using PuTTy, and when connecting Putty will ask for the passphrase, but not for any password local to the server. e563f7ad18263d0d7ad1a2b14d3e27ed72251f44 3080 3079 2016-02-21T15:17:51Z Saruman! 2 /* Configuring PuTTy to use the SSH key */ wikitext text/x-wiki ==OpenSSH Server== This package is essential when you want to be able to (safely) administer your server from another place than the console. To install: simpy use ''sudo aptitude install openssh-server''. This will install the OpenSSH server, plus the OpenSSH client. Since the SSL vulnerbility of may '08, also the ssh-blacklist package is downloaded. After installing, we need to make the following changes to the default settings in file ''/etc/ssh/sshd-config'': * line ''PermitRootLogin yes'' should be set to ''no'', so that user ''root'' CANNOT log in over SSH! ([http://www.debian-administration.org/articles/573 big security gap!]). * add a line ''AllowGroups wheel''; adding this ensures that NOBODY can log in over SSH unless you specifically assigned them to the ''wheel'' group, reducing the attack surface of your SSH user. Should you need more than one group (e.g. you want to add the group "ldapwheel"), then add the groups separated by spaces: ''AllowGroups wheel ldapwheel''. * Change your banner by editing the [[MOTD file]]. Next, make sure the ''wheel'' group exist, and add all users to it that are allowed ssh-access: groupadd -g 117 wheel usermod -a -G wheel jan In the groupadd line, the groupID is explicitly set to 117, but this really is optional. In the usermod line, be sure to use the ''-a'' so that your user gets the ssh-users group added, instead of replacing all supplementary groups with this one ssh-users. If you've added a group that exists in your LDAP server, make sure that those LDAP users are member of that group that you want to give SSH access. This is ofcourse managed from your LDAP management console (be it the commandline ''ldapmodify'' or a graphic tool like [[Filling_an_OpenLDAP_database#Adding_a_user_with_LAM | LDAP Account Manager]] When all this is changed, the service should be restarted with ''sudo /etc/init.d/ssh restart''. One of the nice things of a correctly configured SSH server, is the ability to use [[scp]] to copy files between machines. == Changing RSA keys == Occasionally you'll find the RSA key of one of your machines has changed. This may have a number of reasons, a.o. a reinstall or migration of said machine. In any case, when you try to SSH to the machine you get a message like this: localhost:~# '''ssh insomnia@easton.saruman.biz''' @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @ WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED! @ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ IT IS POSSIBLE THAT SOMEONE IS DOING SOMETHING NASTY! Someone could be eavesdropping on you right now (man-in-the-middle attack)! It is also possible that the RSA host key has just been changed. The fingerprint for the RSA key sent by the remote host is f7:1a:5a:11:ca:20:99:fa:db:1b:b8:75:8e:e5:f1:12. Please contact your system administrator. Add correct host key in /home/sixpacjo/.ssh/known_hosts to get rid of this message. Offending key in /home/sixpacjo/.ssh/known_hosts:4 RSA host key for easton.saruman.biz has changed and you have requested strict checking. Host key verification failed. localhost:~# _ When you get this message it is not possible to connect to the machine mentioned, until you've solved the problem of the RSA key. There are multiple ways to correct the key, but the simplest method seems to be to simply remove the offending key with ''ssh-keygen''. Note that Debian "Lenny" stores the RSA key in ''two'' places: one for the host name, one for the IP number. To prevent annoying messages like this: Warning: the RSA host key for 'easton.saruman.biz' differs from the key for the IP address '192.168.67.5' Offending key for IP in /home/sixpacjo/.ssh/known_hosts:4 you should remove the RSA key for the IP number as well. This you do with the following two commands: localhost:~# '''ssh-keygen -R easton.saruman.biz''' /home/sixpacjo/.ssh/known_hosts updated. Original contents retained as /home/sixpacjo/.ssh/known_hosts.old localhost:~# '''ssh-keygen -R 192.168.67.5''' /home/sixpacjo/.ssh/known_hosts updated. Original contents retained as /home/sixpacjo/.ssh/known_hosts.old localhost:~# _ After deleting the "offending RSA keys" like this, you can SSH to the box in question, and your SSH client will save the (new) RSA key for you in your ''known_hosts'' file. ==Using SSH keys for SSH login== If your server is open to the Internet, passwords alone may not be safe enough. Plenty of malicious folks will try to brute-force attack your SSH server. Of course you've disabled root login (right? RIGHT?!?) but still... all that attacking clutters your logs, and maybe one day one of your SSH user passwords turns out too weak. That's why it's a good idea to add SSH keys to the mix. What we're going to do is create an SSH key pair: a public key that we can store on the server, and a private key that we'll use on our end when we connect with the server. ===Generating an SSH key=== You can generate an SSH key from Linux itself (see [https://www.digitalocean.com/community/tutorials/how-to-set-up-ssh-keys--2 DigitalOcean], but in this article we'll use [http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html PuTTy], because PuTTy/WinSCP is the go-to tool set for Linux administration from a Windows workstation, and PuTTy's [http://www.chiark.greenend.org.uk/~sgtatham/putty/wishlist/key-formats-natively.html proprietary key management] provides some nifty tricks for key management. (based on [https://www.digitalocean.com/community/tutorials/how-to-create-ssh-keys-with-putty-to-connect-to-a-vps DigitalOcean howto]) First we start the PuTTyGen utility, by double-clicking on its .exe file. * At the bottom of the interface, for Type of key to generate, select SSH-2 RSA; * In the Number of bits in a generated key field, specify either 2048 or 4096 (the latter is safer, but takes longer to generate); * Now click the Generate button. PuTTyGen needs some entropy, so move your mouse pointer around in the blank area of the Key section for a while until the progress bar is full - a private/ public key pair will then be generated; * In the Key comment field, enter your name (or any other comment you'd like), to help you identify this key pair. This is particularly useful in the event you end up creating more than one key pair; * A passphrase is optional but recommended: Type & re-type it in the Key passphrase fields. (Really, only leave out the passphrase if you would like to use this particular key pair for automated processes!) The above actions should look a bit like this: [[File:Puttygen.png|PuTTyGen interface]] * Now click the Save public key button & choose whatever filename you'd like, saving it in a "safe" folder. I'd recommend a filename that corresponds to the Key comment field content; * Then click the Save private key button & choose whatever filename you'd like (you can save it in the same location as the public key, but it should be a location that only you can access and that you will NOT lose!). Keep the file extension to '''.ppk''' ===Putting the public key on the server=== To put the key on the server, we need to use not the public key ''file'', as the file itself is in a format that OpenSSH doesn't recognize. So we can again open PuTTyGen, click ''load'' to load an existing private key file, and select the private key from the safe folder used below. After entering the passphrase (twice) we see the same information as before (see pic above). From the PuTTyGen interface, we select & copy to clipboard the information in the top window - which is the public key, something like ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAgEAjisviHZ19eU0F5BtN+F32tcjO72Ne 82Br24XS5cQASuYt8EZXBP1bdh0JFX7KvJIBMzH6KXo0gZQv/UtX4q+9jV9xgCgWq IAM+WKEVexAkR1RjFc8Bf8pPK62eNsis959+XD0IuuH7Ge/JKTy6ScxU+nyIfBJr/ a894TNPwdCEAbnBdU6WX/Q7g3P7xVaMu2g5okLRkO1tt7wIlt0zrOx86hMvesmIwX CfZ8qJtp8frmpoxbbCn9akgDPRtmMUEJDDkgrW6oyyMCtCgH0iTEZf3RYq4aOdXAI bJE9Yu402BPmyZCSDBrqwYfEWn0FgtEsjTlc7TTnUq+X35ndCpwE+g4AV3Fle7e18 eNyqvb3ng2+nSj4uNj2fFqlfNrJXfZGVELmk7xnVH1ypP6WamFHxG81wAqkGnBA2q W1ItvJxZ3L3mfHX5LKUxMMXbw5hElXtVQI+ZiDPjFqCIqPXagYzIsh/XzKbXoxZnR abcc14wGdPM+3TuAgyARoVuYyMb6iJz7SMrf1OAvMD6P7AcY5l7PeFG88ABJc67kS fPAyZRrK7uHllh2P3B3lEzIWrXYvKqjMoOOQj0uAhHtmFVtDvu/bHgJ2BWrTYq9AI g7AY59QnzK0LO8BxAoTSTKuUNpj+9WP7FUNL60nejm6A68PXQRddVrAZ2SYUuTUB+ /pU0= Joe Sixpack Note that on pasting this information in e.g. Notepad, then it should be a ''single'' line of information. On a side note, if you need the ''private'' key in an ''OpenSSH'' or ''ssh.com'' compatible form, you can use the Conversions tab on the toolbar. Next, we open a PuTTy SSH session to the server, change directory to the user's home directory (e.g. ''/home/jsixpack''), and in this home directory go into the ''.ssh'' directory. Inside that directory there should be a file ''authorized_keys''. If it's not there, create it with the user as owner and read/write for the user only. In the example of user ''jsixpack'': cd /home/jsixpack/.ssh touch authorized_keys chmod 600 authorized_keys Then open this file with [[Vim|vi]], and copy the public key in there. Again, it should be a single line, beginning with ''ssh-rsa AAAA'' and ending with the key comment. Save with '':wq'' and the key is stored! ===Configuring the SSH server=== To ensure that the SSH server accepts SSH keys, add the following to ''/etc/ssh/sshd_config'', or at least confirm the lines are already there: RSAAuthentication yes PubkeyAuthentication yes AuthorizedKeysFile %h/.ssh/authorized_keys If you've changed any of these settings, restart the SSH server to ensure they're implemented. Then test if you can log in to the server with your SSH key (see next section). Once you've ensured you can log into the server using only the key and it's associated passphrase, you may wish to disable password-based login. To configure the SSH server to ''not'' accept passwords any more, add the following (or confirm it's already set): ChallengeResponseAuthentication no PasswordAuthentication no Again, restart the server if you've changed these settings. BEWARE! If you haven't properly tested logging in with a key, and you disable password-based login, then you've shut yourself out. Only access to the console can then restore your access... ===Configuring PuTTy to use the SSH key=== You've added your public key to the server, now add your private key to your PuTTy session information. To this end, put your private key in a secure spot accessible from your system. For example, on a secure (encrypted) USB stick. In this example I use a subdirectory of the Documents directory, named Keychain. Now configure your PuTTy connection like you always would, but also go to the settings category Connection, subsection SSH, subsection Auth. There you'll find a Private key file section, from which you can browse to your .ppk private key file. It should look like this: [[File:Puttyprivatekey.png|467px]] Then go back to the Session category to get to the PuTTy "main" screen, and hit Save. That's it. You can now log on to your server using PuTTy, and when connecting Putty will ask for the passphrase, but not for any password local to the server. a9fbe7fb7135e54b6088c467da91ce7df343e3b5 0 1792 3070 2015-06-16T20:09:51Z Saruman! 2 branched off of old Wheezy base server page wikitext text/x-wiki __TOC__ ==Hardware preparation== When installing a new server, you must begin with [[Server hardware prep|getting your server hardware right]]. Assuming you've built yourself a new server platform, you can install the operating system following the steps outlined below. Note: it is assumed the server is bare, and the hard disks are completely clean. If they are not, here's how to [[Cleaning a hard disk|clean]] them. ==Planning your network names== If your machine must become a part of an existing network, then it's almost certain that you already have a DNS domain in place; in that case: obtain the DNS suffix your machine will get (the DNS domain your machine will "belong" to). However, it's also possible that this machine is going to be the first machine in your new network, in which case the whole issue of DNS suffixes is wide open. If you need more information on DNS, go [[https://kb.isc.org/article/AA-01031 here]]. For now we'll assume you have (or will quickly obtain) a working knowledge of the DNS system. Here is our tip on choosing a DNS domain for your home network: * do '''not''' use a publicly registered domain name (e.g. "cocacola.com") for any machine that's not primarily intended to serve the public on the Internet; * for machines serving a private network, we urge you to use Top Level Domain name "lan" (to signify your machine is on a Local Area Network or LAN) * for the Domain Name itself, we suggest you use a level 2 name, like "saruman.lan", and not a level 3 name, like "mister.saruman.lan". This is only a short section on DNS, but remember that once a proper DNS system is in place, it's pretty much work to change it. At any rate, this section has most likely showed you that you need to put some thought into the DNS Domain Name design of your home network. OK, with this out of the way, we can get to installing the OS. ==Operating System installation== ===Preparing to boot into the installer=== To install an Operating System (OS), it's kinda instrumental that you have one. Here, we're going to use [http://www.debian.org/intro/about Debian], the biggest [http://www.debian.org/intro/about#free Free] OS that we know of. Free stands for Freedom, but incidentally that Freedom also means it's gratis, an appealing aspect of Free. To get your own copy of Debian, go to their [http://www.debian.org/distrib/ download site] and obtain the latest [http://www.debian.org/releases/ Stable] image - as of april 2015, it's Debian 8, or "Jessie" as it's also known. Besides the choice which release of Debian you want to run, you also have to know for which platform you're downloading (in our case: either ''amd64'' or ''i386'' depending on your hardware platform) and what kind of install you wish - if you have a working, fast Internet connection available at the time of install, then we recommend getting the [https://www.debian.org/CD/netinst/ netinst] CD image; it's a relatively small CD, that'll be able to get you going, but gets most of the software you'll need straight from the 'net at install time. In the example at hand we're installing on an Intel Atom C2000-based server, on which we wish to install 64-bits software. We'll download [http://cdimage.debian.org/debian-cd/8.1.0/amd64/iso-cd/debian-8.1.0-amd64-netinst.iso debian-8.1.0-amd64-netinst.iso], which is Jessie after its first update. If you wish, you can burn this to a CD-recordable and boot your prepared hardware platform from this CD. As it stands, we can boot our server platform from the iso file directly by sharing the image using SaMBa, then mounting that fileshared image in the server hardware console - we're lucky that way not needing physical CDs :-) ===Installer=== After booting from the CD, a friendly graphic screen shows you the Installer boot menu. Your choices are: * Install, the default non-graphical installation; * Graphical install, so you can click things; * Advanced options, where you can select expert options like the rescue mode; * Help; this drops you to a non-graphical screen where you can select help texts by using function keys. The screens explain how you can start the installation with extra parameters to instruct Debian to handle your hardware in a non-standard way, e.g. on an old machine with a problematic videocard you could run "install vga=771" (for some laptops) or "install vga=normal fb=false" (to disable the screen framebuffer). We're going to use the standard Command Line installation, so we choose "Install" and hit &lt;enter&gt;. {| class="wikitable" border="1" |- |We could easily use "Graphic install", in which case we'd have a nice fresh Graphical User Interface for our installation. ''We're'' not going to, because we're real men, and Real Men Don't Click. Also, we've found that from the GUI it's a bit harder to switch to a second console and then back. We could also go to the Advanced options, and opt for "Expert install" or "Graphical expert install" as installation method, because it gives a much finer grain of control; however we usually don't need that control, and can do just fine without the barrage of extra questions that the "expert" installation method pose. |} After the Linux kernel finishes initializing the machine, a simple text-based installer appears that immediately starts asking questions. Answer them according to your needs. Our example system uses the following choices: * Language: English * country: other &gt; Europe &gt; Netherlands * locale (since there's no default locale for the combination Netherlands/English): United States - en_US.UTF-8 * keymap: American English (since we have a keyboard with US layout) Some installation software loads, and we get to the next phase: if you have multiple NICs in your machine (which we believe you ''should'' have), and if they're detected properly, then you're required to indicate which of the detected network interface cards (NIC) is going to be the "primary" NIC. {| class="wikitable" border="1" |- |Here, trouble could begin. If your machine has only network cards that are '''not''' supported, then you'll see '''no''' cards here - but then how are you going to do a NetInstall? A solution would be to (temporarily) install a NIC that ''is'' supported, like a cheap Realtek card, or an ancient 3Com 905 card. Then, when the whole system is installed, up and running, you could compile a new kernel that contains support for your actual NICs, and when these work, remove the temporary NIC. For now, we'll assume that at least one of your NICs is recognised properly by the Debian installation routine. |} Select the card that's connected and has (indirect) access to Internet (again: it should ''not'' be connected straight to the wild wild web, but sit safely behind a firewall, at least until we've installed our own firewall); if at all possible, let it be the NIC that'll be connected to your home network itself, on the ''inside'' of your server. Let's assume that this NIC is designated ''eth0'' by the Debian installation. This card will now be configured using DHCP, so if you're on a network with a DHCP-server, the network will work straight away. If it's not, you can either configure the network configuration manually, or fix your DHCP-server and connection between it and ''eth0''. Next is one of the hardest questions that any OS installation is going to ask you: what will be the host name of the system? You could easily change it at any time in the future, but possibly with lots of hassle, so you better choose wisely. Here are our tips: * do '''not''' name your machine after the user that's going to use it, e.g. "bernie-pc" (at some time in the future, Bernie's machine will be moved to Alice, so then Alice is working on "bernie-pc" which makes the situation quite unclear); * do '''not''' name your machine after the department or workgroup that's using it most, e.g. "accounting-srv" (same reasoning); * do '''not''' name your machine after it's main function, e.g. "printserver" (at some time in the future, the main function is moved to another machine, and/or an alternative function will become the main function of the machine); * do '''not''' name your machine after it's location, e.g. "srv-boston" (at some time in the future, the box will be moved to another location); * do '''not''' name your machine after it's hardware configuration, e.g. "ibmx346" (at some time in the future, either another xSeries x346 will be wheeled in, or the machine will be upgraded to accommodate increased use or overcome hardware problems - your "ibmx346" could suddenly be running on an xSeries x3650). What we feel are safe names for ''any'' machine in your network are true names, perhaps linked to a common theme: names of European cities, names of movie characters, names of countries or holiday destinations et cetera. Less imaginative would be coded names like "server0001". Immediately following comes the question of the Domain Name. This is about a DNS domain, so effectively the installation program is asking which DNS suffix the host name should have; if the DHCP-server already provided something it'll be suggested, but you can override it if need be. In the preparatory phase, you'll have decided on continuation of your current DNS schema, or starting a new one. Either way, put the chosen DNS suffix in and press &lt;enter&gt;. Next comes one '''VERY''' important question: what to use as root password? We cannot stress this enough: choose a SAFE password! Do NOT go for an easy-to-remember one, go for STRONG and SAFE. There are tools to help you generate strong passwords, like [https://identitysafe.norton.com/password-generator/ this page]: use them! We strongly suggest 10 characters or more, including letters, mixed case, and numbers, so something like ''SuCRe4hecH'' (do NOT use this, generate your own!). Next, give the full name of the principal user of this server (your own, we assume), give the login-name (your given name, we assume), and a corresponding password. Again, use a SAFE password. As long as you don't make your principal user equivalent to root, you might go for a slightly weaker password (8 characters instead of 10), but we rather suggest you make the password just as strong (and different from!) the root password. After entering the details of these two users "root" and "you", we get to the server hardware. ===Partitioning=== Now comes the question of partitioning, or how to divide the available disk space into chunks for the server to use. This is a tricky subject, because if you put all storage space into one partition, then some day a runaway process will fill up the entire disk with useless logs, and the system will crash. On the other hand, if you divvy up all space into little chunks, then some application is going to need space in one of those partitions where there is none, even though there may be plenty in other partitions. To minimize the chance of either problem occurring, we're going to use [http://tldp.org/HOWTO/LVM-HOWTO/whatisvolman.html Logical Volume Management (LVM2)] so that we can provision enough space to start our server, but keep some space in reserve to apply when needed, where it'll be needed. So, we at Saruman.biz have put together a recommended standard partitioning scheme. The basis (in accordance with the standard [[Debian directory structure]] is this: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Partition !style="background:#ffdead;"|MD !style="background:#ffdead;"|LVG !style="background:#ffdead;"|LV-name !style="background:#ffdead;"|Size <br> (physical machine) !style="background:#ffdead;"|Size (VM) !style="background:#ffdead;"|File System !style="background:#ffdead;"|Mount point |- | 1 | /dev/md0 | &nbsp; | &nbsp; | 100MiB | 100MiB | ext3 | /boot |- | 2 | /dev/md1 | &nbsp; | &nbsp; | 3GiB | 1GiB | ext3 | / |- | rowspan="8" valign="top" | 3 | rowspan="8" valign="top" | /dev/md2 | rowspan="8" valign="top" style="background:lightgrey"| system | style="background:lightgrey" | swap | 1GiB<ref name="swap">Rule of thumb: twice the size of the machine's RAM, but no less than 256MiB and no more than 2GiB</ref> | 256MiB<ref name="swap"/> | swap | &nbsp; |- | style="background:lightgrey" | var | 1GiB | 512MiB | ext3 | /var |- | style="background:lightgrey" | varlog | 1GiB | 512MiB | ext3 | /var/log |- | style="background:lightgrey" | appslog | 3GiB | -<ref>Yes, we think a separate ''appslog'' is a very good idea, but when creating a minimal VM, we have to save disk space ''somewhere''...</ref> | ext3 | /var/appslog |- | style="background:lightgrey" | home | 1GiB<ref name="home">Note that this heavily depends on the purpose of the machine; if it is not to house any users, then (almost) no space is needed for /home. But on the other hand if e.g. a virtual user is to be used for keeping mailstores, or other service users need home space, then /home needs to be big enough for that.</ref> | 512MiB<ref name="home"/> | ext3 | /home |- | style="background:lightgrey" | usr | 3GiB | 3GiB | ext3 | /usr |- | style="background:lightgrey" | tmp | 1GiB | 512MiB | ext3 | /tmp |- | style="background:lightgrey" | opt | 1GiB | - | ext3 | /opt |- ! colspan="4" style="text-align:right"| Total ! 18.1GiB ! 6.9GiB ! colspan="2" | |- |} As you can see, the partition table works as follows: we assume that we wind up with 3 partitions, either on three separate software RAID arrays (''md0'' through ''md2'') or on one single hardware RAID array (in which case the 2nd column ''MD'' does not apply). The size of the partitions depends on your machine's make: for standard physical machines the 5th column does sensible suggestions, even though you could choose to have different sizes and of course different divisions altogether. If your machine happens to be a virtual one, running inside a [http://www.vmware.com/products/vsphere VMware Server] or something alike, then you might want to start out with more modest partitions. The same holds for small servers that must run off Flash drives. Anyways, we're now at the Debian installation screen that lets us partition our disks. We're ''not'' going to use any of the "guided" partitioning options, we go for "manual". Choosing that brings us to a screen showing all drives that the installation routine has detected, and all partitions on those drives that the installer can "see". We're going to do some assuming here once more: let's assume the drive(s) on which you want to install are visible, and are empty (containing no other partitions). <references/> ===Software RAID partitioning=== If you're to use software RAID, you now have to select the free space on the first drive, press &lt;enter&gt;, and then tell what you want to do with the free space: create a new partition, tell which size you want it to be (see table above), give the type of partition (primary), and give where on the disk it'll sit (the beginning). Next, a screen comes up that details how the partition you're requesting will be created. Here we make some changes: under "use as" we're going to select "physical volume for RAID". This clears all the other options in this screen, except for the "bootable" flag, which must be "on" for the first partition that we'll mount as ''/boot''. Now select "Done setting up the partition". Next, go to the free space on the second disk, and do ''exactly'' the same, to create an identical physical volume for RAID - if it's the first partition, select the "bootable" flag as well (we'll want to be able to boot from this second disk if the first disk fails, right?). Then go back to the rest of the free space on the first disk, make the second physical volume for RAID, duplicate it on the second disk. Then, go back to the rest of the free space on the first disk, make the third physical volume for RAID, and again duplicate it on the second disk. If you now go back to the "partition disks" overview, you'll see all the partitions you've specified listed on their respective disks. But at the top an extra option has appeared, called "configure software RAID". When you now select this option, the installer will ask if it may write the changes you've made to disk. This actually creates the partition tables on the disks. Now you can create RAID devices. The RAID levels that Debian 6.0 offer are 0 (striping), 1 (mirroring), 5 (distributed redundancy), 6 (double distributed redundancy) ant 10 (striped mirrors). For your operating system disk pair, level 1 is the only sane choice. When selecting RAID 1, the installer asks how many active devices to use (2), how many spares (0), and then offers a selection screen where you can mark all members of the array. Select the first partition of both disks (presumably ''/dev/sda1'' and ''/dev/sdb1'') which should correspond to the 100MiB partitions you've created. Then create the other MD devices. Finally, choose &lt;finish&gt;. You'll drop back to the partitioner, but now the three created devices are available in the partitioner as "RAID1 device #0" etc. ===Hardware RAID partitioning=== Now, if you have hardware RAID, then on your first (boot) disk just make 3 partitions, in the following manner: Select the free space on the intended boot disk, press &lt;enter&gt;, select "create a new partition", and fill out the desired size (100MB). Type is primary, location is beginning of the disk, and in the details of the partition, we only need to change the Mount point to "/boot", and set the Bootable flag to "On". Then we're "Done setting up this partition". The second partition is made the same way, but the desired size is 3GB, the Mount point is "/", and the Bootable flag remains off. Again, we're "Done setting up this partition". The third partition is again a primary partition, it takes up the entire rest of the disk, but the type is not ext3, but "physical volume for LVM". Again, we're "Done setting up this partition". But now from the main partitioner screen, we can access "Configure the Logical Volume Manager". The installer asks if it can write out the choices made to the disk, and then enters the LVM setup screen, which begins with a summary explaining that you have one Free Physical Volume, and nothing more. ==Logical Volume creation== We now create a Volume Group (VG), which (in accordance to our partitioning standard) we'll call "system". In this VG, we'll add all Physical Volumes (being the one partition we've designated so in the previous step) using the space bar. To this end, in the volume group creation dialogue, we select that partition (''/dev/md2''). Note that all other selection choices are either unusable (unusable free space) or assigned to other purposes (/boot and /). Now we repeat the following process seven times: * select "Create Logical Volume" * select Volume Group "System" * give the LV Name (from the table, e.g. swap, var etc) * give the LV size (from the table, e.g. 1GB for swap etc) After this, we can select "Finish", the partitioner creates the seven LVs, and we're back at the partitioner screen, where there are now 7 extra "disks", with names such as ''LVM VG system, LV appslog - 3.0GB Linux device mapper (linear)''. Each of these "disks" has one block of empty space, which we now assign: seven times we repeat the following process: * select the unassigned chunk of empty space of an LV (e.g. ''appslog'') and press &lt;enter&gt;; * Change "Use as: do not use" into the desired filesystem (ext3 - only the LV "swap" gets as filesystem type "swap area"); * Change the mount point from "none" to the one corresponding with the name of the LV (note: the swap LV has no mountpoint; the appslog mountpoint must be entered manually as "/var/appslog" and varlog as "/var/log"); * If so desired, a label can be assigned to the partition (we usually don't); * select "Done setting up the partition". Note that sometimes, after creating and assigning the logical volumes, the installer has forgotten to mount the md0 and md1 partitions as /boot and /. In that case you'll have to reassign these partitions to these points in the filesystem. Once all this is done, we can look over the configuration once more, and then select "Finish partitioning and write changes to disk". A summary configuration screen will show, and we'll affirm with "yes" that these partitions can indeed be formatted. After some formatting screens flashing by (unless your partitions are particularly big, your system is particularly slow, or something goes wrong) the installation procedure continues. ==Base system setup== Now the Debian installer loads a base system. It will scan your installation CD/DVD, and ask if it should scan more CD/DVDs. We're going with "no" here. Then it will ask you how it can contact the Debian archives, in the dialogue "configure the package manager". For the NetInstall version of Debian, this is as good as mandatory. So here, we say "yes, use a Network Mirror", and in the following list select the country in which we are (in our case: the Netherlands), so the installer can present us with a number of network mirrors "close by". We select ftp.nl.debian.org. Next screen: should you be behind a proxy server, then it's possible to specify that here. And then the test: the system will say "scanning the mirror..." and try to contact the specified mirror. If it does not succeed, then there is either a network problem, a problem with this box's network card, or you've not specified the mirror or proxy correctly - so fix it. You'll know the network mirror has successfully been contacted when it's saying "Retrieving file 1 of 5". A number of files are retrieved, and the base system is set up. Somewhere early in this setup, the next dialogue appears - currently "configuring popularity-contest". Answer this question as you please. And then one of the last "big" questions: Software Selection. In this dialogue, you can easily select bundles of software to be installed. The choices are currently: * Graphical desktop environment * Web server * Print server * DNS server * File server * Mail server * SQL database * SSH server * Laptop * Standard system utilities (selected by default) We have to make a little confession here: we've never before used this option in the installer. In fact, we even deselect the Standard System, so as to minimize the number of software packages that the base installation of our server contains. This makes it more work to manually add packages later, but we feel it gives us more control and understanding of our systems. So if you're like us: deselect the "Standard system utilities" entry, and select Continue. The next dialogue handles the installation of the [http://www.gnu.org/software/grub/ ''grub'' bootloader]. Unless your disks weren't empty and you're attempting to make this system multiboot, you'll most likely get a question if you'll allow the installer to install ''grub'' into the boot sector of the first hard disk. We'll confirm with "Yes". After the installation of grub is completed, the CD-ROM is ejected, and the system is ready to reboot into Debian Squeeze. Remove the CD and select "Continue" ==Finishing up the installation== The system should reboot into Debian. This means you should see the following boot sequence: * your machine's standard POST messages * briefly a '''welcome to GRUB''' message * then, a blue grub menu on a black screen, with two entries: ** Debian GNU/Linux, with Linux 2.6.32-5-686 ** Debian GNU/Linux, with Linux 2.6.32-5-686 (recovery mode) * then, after a default (short!) time-out, the first grub option will go into effect, and the Linux kernel is started. Lots of cryptic messages in grey-on-black will scroll by, until the last few lines read: Debian GNU/Linux 6.0 easton2 tty1 easton2 login: '''_''' If your system does not reach this login, and/or some horrible error messages appear anywhere in this boot sequence, then you've got some extra work ahead. For now we'll assume you've reached the login prompt without problem. Log in as the principal user (try to avoid logging in as root! That's BAD practice!). Once logged in, save a copy of the boot messages using ''sudo dmesg > boot.txt'' or whatever you like. Then look through the boot messages, e.g. with ''vi -R boot.txt''. Furthermore, [[APT_and_aptitude | use Aptitude]] to make sure ''all'' your software is updated to the latest version. Done! Your base system is ready. You probably now want to [[essential system software | install essential software]], [[roll your own kernel]] and [[connect your server to the Internet]]. Furthermore, you might want to create a couple of [[aliases in every profile]] so that your favourite commands are always available. d370a103f08219f340f6ee65ab475c1f459814d4 0 1 3071 3059 2015-06-16T20:10:39Z Saruman! 2 link to Jessie server wikitext text/x-wiki <big>'''Welcome to SaruWiki.'''</big> This Wiki is intended to document bits and bobs about [http://www.kernel.org/ Linux] (and some Unix) in general, and [http://www.debian.org Debian] in particular. In it, [[SaruWiki:About|we]] wish to collect the tips and tricks of both [[SaruWiki:About|our own team of Linux admins]] and those of other interested users. If you are interested in my work on [http://www.dya.info DYA|Infrastructure], please visit the [https://dya-knowledge.sogeti.nl/ SmartMart demo site]. Consult the [http://meta.wikimedia.org/wiki/Help:Contents User's Guide] for information on using this wiki's software. <big>NOTE:</big> '''you must confirm edits''' when you're not logged in with a user account. Thanks to the Mediawiki ConfirmEdit extension we've cut our wikispam considerably. Sorry to make you anonymous contributors jump through this little hoop for every edit, but there you are. ---- <big>'''Main Content'''</big> * Setting up a [[Debian_Jessie_base_server]] is a howto on the installation of a very basic Linux box under Jessie (it's actually not even a server yet). * Using ''md'' for [[software-based RAID]] contains our ideas and observations on redundancy. * The use of [[APT and aptitude]] is crucial to the concept of a Debian machine. * [[Roll your own kernel]] discusses the pros and cons of compiling your own kernel, and how to do it. * [[Essential system software]] lists all (sets of) packages that we deem, well, essential. * The [[system boot procedure]] section explains what we can customise in the standard ways Debian boots. * The [[networking section]] treats subjects like setting persistent routes. * The [[firewall section]] is where we discuss "IPtables" (netfilter) and how we use it for firewalling. * The [[native IPsec tunnel]] section describes how to configure an IPsec tunnel. * [[Hardware monitoring]] is important for your server's health and reliability. * Make your server a [[Microsoft PPTP server | Microsoft client compatible VPN Server ]]. * Creating a [[backup]] for your server. '''Authentication and security''' * [[Certificate fundamentals | The "certificates" section]] explains how you create your own Certificate Authority (CA) and the neat things you can do with it. * [[OpenLDAP]] is a rudimentary howto about getting OpenLDAP to be your central user repository. * [[Pluggable Authentication Modules (PAM)]] is a great way to secure your server and arrange logins - if you get to understand them '''Your own LAMP server''' * [[Apache2 and PHP5]] are essential packages if you want to light your own little [[LAMP]]. * [[Database 101]] introduces you to MySQL. '''Other server apps''' * The [[Installing SaMBa with OpenLDAP support | SaMBa section]] explains how to install SaMBa with OpenLDAP as user backend. * [[Add an X11 server]] to your server, if you need one. * Of course we have a [[e-mail server section]], where we focus on Postfix and virtual mail domains, and add in a whiff of MySQL and OpenLDAP. * The [[Asterisk section]] is about all things re: telephony on Debian Lenny. * [[Vmware_server|VMware Server basics]] gives some pointers on how to install VMware Server on a Debian server box. * How to install [[Mediawiki Installation | Mediawiki]] on your Debian server - like what you're looking at now. * How to [[DLNA server|create your own multimedia server]], supporting [http://www.dlna.org/ DLNA] (which is [http://hometheater.about.com/od/interactivetelevision/a/Samsung-Allshare-Media-Streaming-basics-bg.htm Samsung's "AllShare"]) * How to create [[your own ownCloud]] server (and here's [http://www.thecomputerkid.com/2013/06/why-you-should-use-owncloud.html why] you should do this) ---- If you'd like to create a new page, please log in and go ahead '''Note''': the Wiki admins reserve the right to edit or remove any content they feel is not suitable for this site, not relevant, (too) inaccurate or otherwise not in line with the intentions and spirit of the admin team. 05d24fee578fa3c29f0198b3c03876742a7ea181 3072 3071 2015-06-16T20:16:42Z Saruman! 2 text wikitext text/x-wiki <big>'''Welcome to SaruWiki.'''</big> This Wiki is intended to document bits and bobs about [http://www.kernel.org/ Linux] (and some Unix) in general, and [http://www.debian.org Debian] in particular. In it, [[SaruWiki:About|we]] wish to collect the tips and tricks of both [[SaruWiki:About|our own team of Linux admins]] and those of other interested users. If you are interested in my work on [http://www.dya.info DYA|Infrastructure], please visit the [https://dya-knowledge.sogeti.nl/ SmartMart demo site]. Consult the [http://meta.wikimedia.org/wiki/Help:Contents User's Guide] for information on using this wiki's software. <big>NOTE:</big> '''you must confirm edits''' when you're not logged in with a user account. Thanks to the Mediawiki ConfirmEdit extension we've cut our wikispam considerably. Sorry to make you anonymous contributors jump through this little hoop for every edit, but there you are. ---- <big>'''Main Content'''</big> * Setting up a [[Debian Jessie base server]] is a howto on the installation of a very basic Linux box under Jessie (it's actually not even a server yet). * Using ''md'' and ''btrfs'' for [[software-based RAID]] contains our ideas and observations on data redundancy. * The use of [[APT and aptitude]] is crucial to the concept of a Debian machine. * [[Roll your own kernel]] discusses the pros and cons of compiling your own kernel, and how to do it. * [[Essential system software]] lists all (sets of) packages that we deem, well, essential. * The [[system boot procedure]] section explains what we can customise in the standard ways Debian boots. * The [[networking section]] treats subjects like setting persistent routes. * The [[firewall section]] is where we discuss "IPtables" (netfilter) and how we use it for firewalling. * The [[native IPsec tunnel]] section describes how to configure an IPsec tunnel. * [[Hardware monitoring]] is important for your server's health and reliability. * Make your server a [[Microsoft PPTP server | Microsoft client compatible VPN Server ]]. * Creating a [[backup]] for your server. '''Authentication and security''' * [[Certificate fundamentals | The "certificates" section]] explains how you create your own Certificate Authority (CA) and the neat things you can do with it. * [[OpenLDAP]] is a rudimentary howto about getting OpenLDAP to be your central user repository. * [[Pluggable Authentication Modules (PAM)]] is a great way to secure your server and arrange logins - if you get to understand them '''Your own LAMP server''' * [[Apache2 and PHP5]] are essential packages if you want to light your own little [[LAMP]]. * [[Database 101]] introduces you to MySQL. '''Other server apps''' * The [[Installing SaMBa with OpenLDAP support | SaMBa section]] explains how to install SaMBa with OpenLDAP as user backend. * [[Add an X11 server]] to your server, if you need one. * Of course we have a [[e-mail server section]], where we focus on Postfix and virtual mail domains, and add in a whiff of MySQL and OpenLDAP. * The [[Asterisk section]] is about all things re: telephony on Debian Lenny. * [[Vmware_server|VMware Server basics]] gives some pointers on how to install VMware Server on a Debian server box. * How to install [[Mediawiki Installation | Mediawiki]] on your Debian server - like what you're looking at now. * How to [[DLNA server|create your own multimedia server]], supporting [http://www.dlna.org/ DLNA] (which is [http://hometheater.about.com/od/interactivetelevision/a/Samsung-Allshare-Media-Streaming-basics-bg.htm Samsung's "AllShare"]) * How to create [[your own ownCloud]] server (and here's [http://www.thecomputerkid.com/2013/06/why-you-should-use-owncloud.html why] you should do this) ---- If you'd like to create a new page, please log in and go ahead '''Note''': the Wiki admins reserve the right to edit or remove any content they feel is not suitable for this site, not relevant, (too) inaccurate or otherwise not in line with the intentions and spirit of the admin team. 86a394a936e5dfb07fe84d4ef53d0cea01020293 3075 3072 2015-09-04T19:07:05Z Saruman! 2 wikitext text/x-wiki <big>'''Welcome to SaruWiki.'''</big> This Wiki is intended to document bits and bobs about [http://www.kernel.org/ Linux] (and some Unix) in general, and [http://www.debian.org Debian] in particular. In it, [[SaruWiki:About|we]] wish to collect the tips and tricks of both [[SaruWiki:About|our own team of Linux admins]] and those of other interested users. If you are interested in my work on [http://www.dya.info DYA|Infrastructure], please visit the [https://dya-knowledge.sogeti.nl/ SmartMart demo site]. Consult the [http://meta.wikimedia.org/wiki/Help:Contents User's Guide] for information on using this wiki's software. <big>NOTE:</big> '''you must confirm edits''' when you're not logged in with a user account. Thanks to the Mediawiki ConfirmEdit extension we've cut our wikispam considerably. Sorry to make you anonymous contributors jump through this little hoop for every edit, but there you are. ---- <big>'''Main Content'''</big> * Setting up a [[Debian Jessie base server|Debian 8 Jessie base server]] is a howto on the installation of a very basic Linux box under Jessie (it's actually not even a server yet). * Using ''md'' and ''btrfs'' for [[software-based RAID]] contains our ideas and observations on data redundancy. * The use of [[APT and aptitude]] is crucial to the concept of a Debian machine. * [[Roll your own kernel]] discusses the pros and cons of compiling your own kernel, and how to do it. * [[Essential system software]] lists all (sets of) packages that we deem, well, essential. * The [[system boot procedure]] section explains what we can customise in the standard ways Debian boots. * The [[networking section]] treats subjects like setting persistent routes. * The [[firewall section]] is where we discuss "IPtables" (netfilter) and how we use it for firewalling. * The [[native IPsec tunnel]] section describes how to configure an IPsec tunnel. * [[Hardware monitoring]] is important for your server's health and reliability. * Make your server a [[Microsoft PPTP server | Microsoft client compatible VPN Server ]]. * Creating a [[backup]] for your server. '''Authentication and security''' * [[Certificate fundamentals | The "certificates" section]] explains how you create your own Certificate Authority (CA) and the neat things you can do with it. * [[OpenLDAP]] is a rudimentary howto about getting OpenLDAP to be your central user repository. * [[Pluggable Authentication Modules (PAM)]] is a great way to secure your server and arrange logins - if you get to understand them '''Your own LAMP server''' * [[Apache2 and PHP5]] are essential packages if you want to light your own little [[LAMP]]. * [[Database 101]] introduces you to MySQL. '''Other server apps''' * The [[Installing SaMBa with OpenLDAP support | SaMBa section]] explains how to install SaMBa with OpenLDAP as user backend. * [[Add an X11 server]] to your server, if you need one. * Of course we have a [[e-mail server section]], where we focus on Postfix and virtual mail domains, and add in a whiff of MySQL and OpenLDAP. * The [[Asterisk section]] is about all things re: telephony on Debian Lenny. * [[Vmware_server|VMware Server basics]] gives some pointers on how to install VMware Server on a Debian server box. * How to install [[Mediawiki Installation | Mediawiki]] on your Debian server - like what you're looking at now. * How to [[DLNA server|create your own multimedia server]], supporting [http://www.dlna.org/ DLNA] (which is [http://hometheater.about.com/od/interactivetelevision/a/Samsung-Allshare-Media-Streaming-basics-bg.htm Samsung's "AllShare"]) * How to create [[your own ownCloud]] server (and here's [http://www.thecomputerkid.com/2013/06/why-you-should-use-owncloud.html why] you should do this) ---- If you'd like to create a new page, please log in and go ahead '''Note''': the Wiki admins reserve the right to edit or remove any content they feel is not suitable for this site, not relevant, (too) inaccurate or otherwise not in line with the intentions and spirit of the admin team. 6ae4a1bd36b20cbcc22cc67df276044b92a2d33c 3110 3075 2021-09-23T15:06:31Z Saruman! 2 wikitext text/x-wiki <big>'''Welcome to SaruWiki.'''</big> This Wiki is intended to document bits and bobs about [http://www.kernel.org/ Linux] (and some Unix) in general, and [http://www.debian.org Debian] in particular. In it, [[SaruWiki:About|we]] wish to collect the tips and tricks of both [[SaruWiki:About|our own team of Linux admins]] and those of other interested users. Consult the [http://meta.wikimedia.org/wiki/Help:Contents User's Guide] for information on using this wiki's software. <big>NOTE:</big> '''you must confirm edits''' when you're not logged in with a user account. Thanks to the Mediawiki ConfirmEdit extension we've cut our wikispam considerably. Sorry to make you anonymous contributors jump through this little hoop for every edit, but there you are. ---- <big>'''Main Content'''</big> * Setting up a [[Debian Jessie base server|Debian 8 Jessie base server]] is a howto on the installation of a very basic Linux box under Jessie (it's actually not even a server yet). * Using ''md'' and ''btrfs'' for [[software-based RAID]] contains our ideas and observations on data redundancy. * The use of [[APT and aptitude]] is crucial to the concept of a Debian machine. * [[Roll your own kernel]] discusses the pros and cons of compiling your own kernel, and how to do it. * [[Essential system software]] lists all (sets of) packages that we deem, well, essential. * The [[system boot procedure]] section explains what we can customise in the standard ways Debian boots. * The [[networking section]] treats subjects like setting persistent routes. * The [[firewall section]] is where we discuss "IPtables" (netfilter) and how we use it for firewalling. * The [[native IPsec tunnel]] section describes how to configure an IPsec tunnel. * [[Hardware monitoring]] is important for your server's health and reliability. * Make your server a [[Microsoft PPTP server | Microsoft client compatible VPN Server ]]. * Creating a [[backup]] for your server. '''Authentication and security''' * [[Certificate fundamentals | The "certificates" section]] explains how you create your own Certificate Authority (CA) and the neat things you can do with it. * [[OpenLDAP]] is a rudimentary howto about getting OpenLDAP to be your central user repository. * [[Pluggable Authentication Modules (PAM)]] is a great way to secure your server and arrange logins - if you get to understand them '''Your own LAMP server''' * [[Apache2 and PHP5]] are essential packages if you want to light your own little [[LAMP]]. * [[Database 101]] introduces you to MySQL. '''Other server apps''' * The [[Installing SaMBa with OpenLDAP support | SaMBa section]] explains how to install SaMBa with OpenLDAP as user backend. * [[Add an X11 server]] to your server, if you need one. * Of course we have a [[e-mail server section]], where we focus on Postfix and virtual mail domains, and add in a whiff of MySQL and OpenLDAP. * The [[Asterisk section]] is about all things re: telephony on Debian Lenny. * [[Vmware_server|VMware Server basics]] gives some pointers on how to install VMware Server on a Debian server box. * How to install [[Mediawiki Installation | Mediawiki]] on your Debian server - like what you're looking at now. * How to [[DLNA server|create your own multimedia server]], supporting [http://www.dlna.org/ DLNA] (which is [http://hometheater.about.com/od/interactivetelevision/a/Samsung-Allshare-Media-Streaming-basics-bg.htm Samsung's "AllShare"]) * How to create [[your own ownCloud]] server (and here's [http://www.thecomputerkid.com/2013/06/why-you-should-use-owncloud.html why] you should do this) ---- If you'd like to create a new page, please log in and go ahead '''Note''': the Wiki admins reserve the right to edit or remove any content they feel is not suitable for this site, not relevant, (too) inaccurate or otherwise not in line with the intentions and spirit of the admin team. 5827924696788c1ff84ccf9f489e63ab8a67412e 0 1431 3073 2401 2015-06-17T10:48:45Z Saruman! 2 added p7zip and xz-utils wikitext text/x-wiki All utilities listed below are command line utilities; install them using ''apt-get install'' or ''aptitude''. ''apticron'' checks your system daily, and mails you when there are updates for packages<br> ''ccze'' can "colorize" output, e.g. ''tail -f /var/log/syslog | ccze''<br> ''[http://packages.debian.org/ethtool ethtool]'' can change settings for ethernet cards, like speed and duplex<br> ''ipcalc'' is an IP address/mask calculator<br> (''[[IProute | iproute]]'' helps viewing and setting the [http://lartc.org/ IP configuration] - under Lenny it's installed by default, under Etch you'll have to do it yourself)<br> ''iptraf'' is an IP traffic monitor<br> ''less'' is a utility [http://blog.platinumsolutions.com/node/47 to view text files];<br> ''lsof'' can show all open files<br> ''multitail'' can follow multiple (log)files in one terminal<br> ''pwgen'' is a password generator<br> ''[[Sudo | sudo]]'' enables you to execute commands with another user's credentials<br> ''[[TCPdump | tcpdump]] is a network sniffer<br> ''pciutils'' contains the ''lspci'' command, which can be useful to review your hardware<br> The following are compression and archiving tools: ''arj'' is a tool for the .arj file format<br> ''bzip2'' is for .bz2 files<br> ''p7zip'' is for .7z archives<br> ''unzip'' is for the .zip file format<br> ''xz-utils'' is a toolkit for LZ/M compression; adding it will make ''tar'' understand .xz files<br> ''zoo'' is for the .zoo file format<br> ec1bae4ba8b5106f30f99f6fffe65046c7c1dde2 3074 3073 2015-06-17T10:51:07Z Saruman! 2 nicer layout wikitext text/x-wiki All utilities listed below are command line utilities; install them using ''apt-get install'' or ''aptitude''. * ''apticron'' checks your system daily, and mails you when there are updates for packages * ''ccze'' can "colorize" output, e.g. ''tail -f /var/log/syslog | ccze'' * ''[http://packages.debian.org/ethtool ethtool]'' can change settings for ethernet cards, like speed and duplex * ''ipcalc'' is an IP address/mask calculator * (''[[IProute | iproute]]'' helps viewing and setting the [http://lartc.org/ IP configuration] - under Lenny it's installed by default, under Etch you'll have to do it yourself) * ''iptraf'' is an IP traffic monitor * ''less'' is a utility [http://blog.platinumsolutions.com/node/47 to view text files]; * ''lsof'' can show all open files * ''multitail'' can follow multiple (log)files in one terminal * ''pwgen'' is a password generator * ''[[Sudo | sudo]]'' enables you to execute commands with another user's credentials * ''[[TCPdump | tcpdump]] is a network sniffer * ''pciutils'' contains the ''lspci'' command, which can be useful to review your hardware <br> The following are compression and archiving tools: * ''arj'' is a tool for the .arj file format * ''bzip2'' is for .bz2 files * ''p7zip'' is for .7z archives * ''unzip'' is for the .zip file format * ''xz-utils'' is a toolkit for LZ/M compression; adding it will make ''tar'' understand .xz files * ''zoo'' is for the .zoo file format cff13df5585abe7fa4ad70c32ef84511580be76a 6 1793 3077 2016-02-21T15:09:28Z Saruman! 2 Example for PuTTy config wikitext text/x-wiki Example for PuTTy config 188c9e60fd2c5e4608b6f9cf0f7e8bcbee690f6b 0 1620 3081 2727 2016-02-21T21:39:39Z Saruman! 2 /* Post-install reconfiguration */ wikitext text/x-wiki Note: if you need information on the OpenLDAP version from Debian 5.0, see this page: [[OpenLDAP 2.4.11]] == OpenLDAP installation== Note: we're going to install OpenLDAP on our server as [http://www.openldap.org/doc/admin24/config.html#Local%20Directory%20Service the local directory service], without replication, referrals or other advanced features. Under Debian Squeeze, this is OpenLDAP 2.4.23. ===Standard installation=== Installing OpenLDAP on your Debian server is ridiculously simple. Just make sure your server is up-to-date (''sudo apt-get update'' followed by ''sudo apt-get upgrade''), and then install the two main components for your OpenLDAP server. First off: the LDAP client and utilities sudo apt-get install ldap-utils This will result in the installation of as much as 8 different packages (''ldap-utils'', ''libgcrypt11'', ''libgnutls26'', ''libgpg-error0'', ''libldap-2.4-2'', ''libsasl2-2'', ''libsasl2-modules'', and ''libtasn1-3''). Next the main component of an LDAP server installation, the stand-alone LDAP daemon "slapd" sudo apt-get install slapd This may also install up to 8 packages (''slapd'', ''libltdl7'', ''libperl5.10'', ''libslp1'', ''odbcinst'', ''odbcinst1debian2'', ''psmisc'' and ''unixodbc''). The Debian configuration script will ask you for only one single thing: an administrator password. As always: generate a strong password! After you've provided the password, the LDAP database is created with the administrator name "admin" and as a base directory, something based on your DNS name. Suppose your internal domain is "amber.lan", then the script will generate ''suffix "dc=amber,dc=lan"''<ref>Should you see a third, empty, domain component (''dc='') then this is caused by a trailing dot in your particular DNS name: the DNS root. You might have specified your domain as "amber.lan.". You ''should'' change your domain name to a name without the DNS root, and you ''must'' regenerate your LDAP directory.</ref>. The above method of configuring yields you an LDAP database with only two objects in it. Suppose your DNS name is "easton2.amber.lan", then the two objects are: * a single Organization (o="amber.lan") with Distinguished Name dn="dc=amber,dc=lan" * a single administrator with Common Name cn="admin", and dn="cn=admin,dc=amber,dc=lan" Note, however, that there's ''also'' a second LDAP database, "cn=config", which on your server is located under ''/etc/ldap/slapd.d''. We'll cover what's in it further on. <references/> ===Testing the installation=== After installation of the package, it should automatically have been started, and should now be operational. This can be checked with a utility like ''nmap'': root@easton2:~# '''nmap -p 389 localhost''' Starting Nmap 5.00 ( <nowiki>http://nmap.org</nowiki> ) at 2011-04-13 21:19 CEST Interesting ports on localhost (127.0.0.1): PORT STATE SERVICE 389/tcp open ldap Nmap done: 1 IP address (1 host up) scanned in 0.40 seconds root@easton2:~#'''_''' Another way to test if the LDAP server is functional, is by querying it with the ''ldapsearch'' utility, part of the package ''ldap-utils''. Let's see if we can find the naming context of the LDAP server: root@easton2:~# '''ldapsearch -x -b <nowiki>''</nowiki> -s base '(objectclass=*)' namingContexts''' # extended LDIF # # LDAPv3 # base <> with scope baseObject # filter: (objectclass=*) # requesting: namingContexts # # dn: namingContexts: dc=amber,dc=lan # search result search: 2 result: 0 Success # numResponses: 2 # numEntries: 1 root@easton2:~# '''_''' With this command, we do a search using * basic authentication (instead of one encrypted with SASL), * searching within the LDAP tree from base <nowiki>''</nowiki> (meaning the absolute root of the tree), * looking for base object only (instead of a one-level search, a subtree search, or a children-search), * filtering for objects of any class, * asking for the naming context of the result. The output shows that the server responds; two objects have been considered, but none match the filter (that the object should have an objectClass). Let's now do the same but with authentication, to see if we can bind to the LDAP server. We'll first use an incorrect password, then the correct one: root@easton2:~# '''ldapsearch -W -D "cn=admin,dc=amber,dc=lan"''' Enter LDAP Password: ldap_bind: Invalid credentials (49) root@easton2:~# '''ldapsearch -W -D "cn=admin,dc=amber,dc=lan"''' Enter LDAP Password: # extended LDIF # # LDAPv3 # base <> (default) with scope subtree # filter: (objectclass=*) # requesting: ALL # # search result search: 2 result: 32 No such object # numResponses: 1 root@easton2:~# '''_''' Finally, you could simply install and run a graphical management tool for LDAP servers, like [http://directory.apache.org/studio/ Apache Directory Studio]. Note however that if this check fails, then this could also mean problems with firewalls, network connections et cetera. ===Post-install reconfiguration=== Since the default configuration with the server's DNS domain as LDAP base might not always be the most convenient configuration, you could run the configuration again using ''dpkg-reconfigure slapd''. However, following this procedure is '''only''' necessary if you want to change any of the default installation values like the backend database type or DNS domain name; things like the organization name can be edited with other means, as will be shown later on. To be able to reconfigure the LDAP service, you can run the reconfiguration command ''sudo dpkg-reconfigure slapd''. Contrary to some older versions of Debian, you do not need to manually stop the ''slapd'' daemon, and you don't need to manually remove the old configuration or database (in fact, if you do, then the ''slapd'' package will break, so you cannot easily remove it with APT tools). Interestingly enough, this reconfiguration asks you many ''more'' questions. The answers could look like this: omit OpenLDAP config: no DNS domain name: saruman.biz Organization name: Saruman Administrator passwd: wEt3udes Database backend: MDB DB remove after purge: yes Move old DB: yes Allow LDAPv2: no As you can see, the reconfiguration yields much more configuration options than plain installation - although really you'll probably answer most questions with their default values anyway. The above method of configuring yields you an LDAP database with only two objects in it: * a single Organization (o="Saruman") with Distinguished Name dn="dc=saruman,dc=biz" * a single administrator with Common Name cn="admin", and dn="cn=admin,dc=saruman,dc=biz" Also note that the reconfiguration creates a backup of the "old" LDAP database in a directory with a name like ''/var/backups/unknown-2.4.23-7.ldapdb''; if you just reconfigured after installation, then you probably don't need this backup, so you can remove it. The database that your OpenLDAP server uses is a standard Berkeley DB (BDB/HDB) database. Now we most likely will require some other databases as well in our server setup, something modern like PostgreSQL or MySQL - so why don't we configure our OpenLDAP to use this same database as well? For the answer, see [http://www.openldap.org/doc/admin24/intro.html#LDAP%20vs%20RDBMS here] - in short, the LDAP tree structure does not lend itself very well to inclusion in a modern relational database. Thus, we advise to stick with the Berkeley database provided with OpenLDAP. Now, for the database backend, we have the choice between two almost identical flavours: * the ''bdb'' backend used to be the recommended primary backend for a normal slapd database. It uses the Oracle Berkeley DB package, referred to as ''BDB'', to store data. It makes extensive use of indexing and caching to speed data access. * the ''hdb'' backend is a variant of the ''bdb'' backend that uses a hierarchical database layout which supports subtree renames. It is otherwise identical to the ''bdb'' behavior, and all the same configuration options apply. In Debian 6.0 "Squeeze" with OpenLDAP 2.4.23, HDB is the default backend. ==OpenLDAP server configuration== <small>(text from http://www.rjsystems.nl/en/2100-d6-openldap-provider.php)</small> As of OpenLDAP 2.4.23-3, the ''slapd'' runtime configuration is fully LDAP-enabled. The default is to manage it using the standard LDAP operations with data in LDIF. The old ''slapd.conf'' format is still supported, but since that file must now be converted to the new ''slapd-config'' format to allow runtime changes to be saved, it seems likely that the developers will eventually phase it out. Therefore, we'll focus only on the new configuration method, the main advantage of which is that any changes made are immediately active, so it is no longer necessary to restart ''slapd'' after making configuration changes. The new configuration format uses a slapd backend database that is found in the ''/etc/ldap/slapd.d/'' directory. The configuration is stored as a special LDAP directory with a predefined schema and DIT, the root of which is called ''cn=config''. If you go look there, you'll find that most parts of this LDAP directory consist of editable flat files. ===Check the current LDAP configuration=== From the command line, there really are several ways to check the current LDAP configuration: * from the server itself, you can use the trusty ''ldapsearch'' command, running under root: this'll authenticate with user ID 0. Filtering only for distinguished names: root@easton2:/etc/ldap# '''ldapsearch -LLL -Y EXTERNAL -H ldapi:/// -b cn=config dn''' SASL/EXTERNAL authentication started SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth SASL SSF: 0 dn: cn=config dn: cn=module{0},cn=config dn: cn=schema,cn=config dn: cn={0}core,cn=schema,cn=config dn: cn={1}cosine,cn=schema,cn=config dn: cn={2}nis,cn=schema,cn=config dn: cn={3}inetorgperson,cn=schema,cn=config dn: olcBackend={0}hdb,cn=config dn: olcDatabase={-1}frontend,cn=config dn: olcDatabase={0}config,cn=config dn: olcDatabase={1}hdb,cn=config root@easton2:/etc/ldap# '''_''' * to get an idea of what the ''cn=config'' database looks like ''within LDAP itself'', you can run this command: root@easton2:/etc/ldap# '''slapcat -b cn=config''' dn: cn=config objectClass: olcGlobal cn: config olcArgsFile: /var/run/slapd/slapd.args olcLogLevel: none olcPidFile: /var/run/slapd/slapd.pid olcToolThreads: 1 '''''(more LDIF texts)''''' entryUUID: f2a8f568-fa40-102f-8b9d-5d4cbccf32a9 creatorsName: cn=admin,cn=config createTimestamp: 20110413174103Z entryCSN: 20110413174103.641065Z#000000#000#000000 modifiersName: cn=admin,cn=config modifyTimestamp: 20110413174103Z root@easton2:/etc/ldap# '''_''' : As you can see, this generates a pretty large LDIF dump of the contents of the ''cn=config'' directory. Much of it consists of schema information. The LDAP configuration directives are attributes of the directory entries (objects) and most them start with the prefix "olc" ('''O'''pen'''L'''DAP '''C'''onfiguration). Also, some of the objects have names with numbers between curly brackets. This is to compensate for the fact that LDAP databases do not store their contents in any particular order; they are inherently unordered. The numbers constitute a numeric index to ensure a consistent order in the configuration database and thereby preserve all ordering dependencies. The index numbers, however, are generated automatically in the order they are created and usually do not have to be provided. * you can see the configuration by browsing through all the plain-text flat files in ''/etc/ldap/slapd.d/'' and its subdirectories. Note that by default there is no way to do this remotely. If you'd like to browse this configuration using a GUI tool like [http://directory.apache.org/studio/ apache directory studio], don't bother. Debian sets the ''cn=config'' part of the database with a root user of ''cn=admin,cn=config'', but without a password, so you cannot bind to the ''cn=config'' database as anything else than the local root user. Thus you cannot access the ''cn=config'' database by GUI. ===Adding or modifying the cn=config admin password=== To add a password to the config RootDN, we first must generate one; for this we can use the ''slappasswd'' command. By default it'll create an SSHA password, but by specifying MD5 as hash (using '' -h {MD5}'') it will create an MD5 encrypted password. The command interactively asks you for the password, and won't show you what you've typed, so be precise: root@easton2:/etc/ldap# '''slappasswd -h {MD5}''' New password: Re-enter new password: {MD5}d5axCh6gYGjhfK4PGs09us== root@easton2:/etc/ldap# '''_''' Now we determine the DN (Distinguished Name) for the database that contains the RootDN password. We'll also check if there isn't a password in place already. To do this we used the following LDAP search command. root@easton2:/etc/ldap# '''ldapsearch -LLL -Y EXTERNAL -H ldapi:/// -b cn=config olcRootDN=cn=admin,cn=config dn olcRootDN olcRootPW''' SASL/EXTERNAL authentication started SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth SASL SSF: 0 dn: olcDatabase={0}config,cn=config olcRootDN: cn=admin,cn=config root@easton2:/etc/ldap# '''_''' Note the olcDatabase line, as it's the result we were looking for; it'll be needed for the ''ldapmodify'' command. Furthermore, note the absence of an olcRootPW entry; this is the starting point for a Debian OpenLDAP server.<br> Now we can stick in a new password. If no password is present, you can use this interactive procedure: root@easton2:/etc/ldap# '''ldapmodify -Y EXTERNAL -H ldapi:///''' SASL/EXTERNAL authentication started SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth SASL SSF: 0 '''dn: olcDatabase={0}config,cn=config''' '''add: olcRootPW''' '''olcRootPW: {MD5}d5axCh6gYGjhfK4PGs09us==''' modifying entry "olcDatabase={0}config,cn=config" root@easton2:/etc/ldap# '''_''' Note the following points: * we use the olcDatabase location as found with the previous ''ldapsearch'' command; * we input the MD5 password that we've generated previously; * as soon as you put in an empty line, the entry gets added; * you have to use CTRL-D to end this interactive mode; * if a password was already in place, we could still use the above, but we'd interactively feed the second line as '''replace: olcRootPW'''. We could also put the password in an ldif file, and feed that to the server. To this end, we'd create an ldif file with the following content: dn: olcDatabase={0}config,cn=config changetype: modify add: olcRootPW olcRootPW: {MD5}d5axCh6gYGjhfK4PGs09us== If this file is called ''addpassword.ldif'' and is created in ''/tmp'', then the addition can be executed using root@easton2:/etc/ldap# '''ldapmodify -Y EXTERNAL -H ldapi:/// -f /tmp/addpassword.ldif''' SASL/EXTERNAL authentication started SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth SASL SSF: 0 modifying entry "olcDatabase={0}config,cn=config" root@easton2:/tmp# '''_''' ==Adding or modifying (configuration) information== The simple way of changing anything in the database goes like this: ===Method 1: interactive CLI tool=== As an example, let's add an index to the configuration. We'll start by seeing which indices already exist, then interactively add two indices. Finally, we check that the indices are there: root@easton2:/tmp# '''ldapsearch -LLLQY EXTERNAL -H ldapi:/// -b cn=config olcDatabase={1}hdb olcDbIndex''' dn: olcDatabase={1}hdb,cn=config olcDbIndex: objectClass eq root@easton2:/tmp# '''ldapmodify -Y EXTERNAL -H ldapi:///''' SASL/EXTERNAL authentication started SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth SASL SSF: 0 '''dn: olcDatabase={1}hdb,cn=config''' '''add: olcDbIndex''' '''olcDbIndex: cn eq''' '''olcDbIndex: uid eq''' modifying entry "olcDatabase={1}hdb,cn=config" root@easton2:/tmp# '''ldapsearch -LLLQY EXTERNAL -H ldapi:/// -b cn=config olcDatabase={1}hdb olcDbIndex''' dn: olcDatabase={1}hdb,cn=config olcDbIndex: objectClass eq olcDbIndex: cn eq olcDbIndex: uid eq root@easton2:/tmp# '''_''' (And ofcourse we press ctrl-D to end interactive mode).<br>Note: we can /modify multiple attributes in one stanza, but we can also add multiple objects/attributes in one ''ldapmodify'' session: * If you input an empty line, you can start another ''dn:'' line, and perform another action; * If you input a minus sign by itself on a line, then OpenLDAP will assume you'll be performing another action in/on the same object. Modifying works almost the same; we only need keyword ''replace'' instead of ''add'': root@easton2:/tmp# '''ldapsearch -LLLQY EXTERNAL -H ldapi:/// -b cn=config -s base olcLogLevel''' dn: cn=config olcLogLevel: none root@easton2:/tmp# '''ldapmodify -Y EXTERNAL -H ldapi:///''' SASL/EXTERNAL authentication started SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth SASL SSF: 0 '''dn: cn=config''' '''changetype: modify''' '''replace: olcLogLevel''' '''olcLogLevel: stats''' modifying entry "cn=config" root@easton2:/tmp# '''ldapsearch -LLLQY EXTERNAL -H ldapi:/// -b cn=config -s base olcLogLevel''' dn: cn=config olcLogLevel: stats root@easton2:/tmp# '''_''' Note the ''-s base'' option that limits the search for the ''olcLogLevel'' attribute to the ''cn=config'' container. Deleting information from an LDAP tree rarely ever happens, because once an attribute is used for anything, you aren't allowed to delete it, only modify it. However, if you want to delete anything, you can use the changetype "modify" with action "delete": root@easton2:/tmp# '''ldapmodify -Y EXTERNAL -H ldapi:///''' SASL/EXTERNAL authentication started SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth SASL SSF: 0 '''dn: olcDatabase={0}config,cn=config''' '''changetype: modify''' '''delete: olcRootPW''' modifying entry "olcDatabase={0}config,cn=config" root@easton2:/tmp# '''_''' ===Method 2: use an ldif file=== ===Method 3: use an LDAP browser=== With this method, you just use your LDAP browser for the addition or modification, according to its specific usage instructions. In the back, the tool will communicate with the LDAP server as you would in the previous methods. Note however, that this method relies on a bind account in the configuration database, which is a serious security risk. ==Adding schemas== A major task in LDAP maintenance is the addition of LDAP schemas. By default, only 4 schemas will be present in your LDAP server: ''core'', ''cosine'', ''nis'' and ''inetorgperson''. Any other schema, -- say, for Samba -- would need to be added. ===Checking existing schemas=== Let's first check which schemas are already installed. Let's try two different methods, and see what they'll show out of the box: root@easton2:/tmp# '''ldapsearch -LLLQY EXTERNAL -H ldapi:/// -b cn=schema,cn=config "(objectClass=olcSchemaConfig)" dn''' dn: cn=schema,cn=config dn: cn={0}core,cn=schema,cn=config dn: cn={1}cosine,cn=schema,cn=config dn: cn={2}nis,cn=schema,cn=config dn: cn={3}inetorgperson,cn=schema,cn=config root@easton2:/tmp# '''ls -l /etc/ldap/slapd.d/cn=config/cn=schema''' total 40 -rw------- 1 openldap openldap 15474 Jun 13 17:39 cn={0}core.ldif -rw------- 1 openldap openldap 11308 Jun 13 17:39 cn={1}cosine.ldif -rw------- 1 openldap openldap 6438 Jun 13 17:39 cn={2}nis.ldif -rw------- 1 openldap openldap 2802 Jun 13 17:39 cn={3}inetorgperson.ldif root@easton2:/tmp# '''_''' ===Creating a suitable LDIF file for the schema=== To add a schema, you need a schema in LDIF format, which you can then add to the LDAP database using the ''ldapadd'' command. Suppose you have a schema file ''samba.schema'' which you've copied to the ''/etc/ldap/schema'' directory. You'd first have to convert this to a suitable LDIF file. This can be done using ''slaptest'', however ''slaptest'' requires access to the other schemas that your new schema is building on. So we now do this: * We create a file ''schema_convert.conf'' with the content shown below. Note that we're including the schema files of all the schemas that are already in our LDAP server. Furthermore, because we may need it again with the next schema addition, it makes sense to save this file under ''/etc/ldap/schema'': include /etc/ldap/schema/core.schema include /etc/ldap/schema/cosine.schema include /etc/ldap/schema/nis.schema include /etc/ldap/schema/inetorgperson.schema include /etc/ldap/schema/samba.schema * now we create a working directory where ''slaptest'' can put our new LDIF file, and have ''slaptest'' create the configuration: root@easton2:/tmp# '''mkdir /tmp/ldif_output''' root@easton2:/tmp# '''slaptest -f /etc/ldap/schema/schema_convert.conf -F /tmp/ldif_output''' config file testing succeeded root@easton2:/tmp# '''_''' * The previous step has created a directory structure under ''/tmp/ldif_output'' that actually mirrors the config directory ''/etc/ldap/slapd.d/cn=config/cn=schema'', but it contains a shiny new ''cn={4}samba.ldif'' file. We need to edit this file a bit before we can actually feed it to the LDAP server. Thus we'll edit it using (note the extra backslashes to escape the equal-sign and curly brackets): root@easton2:/tmp# '''vi /tmp/ldif_output/cn\=config/cn\=schema/cn\=\{4\}samba.ldif''' * We need to change and edit some parts of ''cn={4}samba.ldif'': ** Near the top we find ''dn: cn={4}samba''. We'll change this to the correct distinguished name ''dn: cn=samba,cn=schema,cn=config'' ** Also near the top: ''cn: {4}samba''. We'll change this to ''cn: samba'' ** The last seven lines look like the bit below - we need to remove these lines: structuralObjectClass: olcSchemaConfig entryUUID: f19250ba-1057-1031-88b7-8301a25f1d46 creatorsName: cn=config createTimestamp: 20120401150603Z entryCSN: 20120401150603.478495Z#000000#000#000000 modifiersName: cn=config modifyTimestamp: 20120401150603Z * We'll store the cleaned up LDIF file in ''/etc/ldap/schema'' with the originating schema file root@easton2:/tmp# '''mv /tmp/ldif_output/cn\=config/cn\=schema/cn\=\{4\}samba.ldif /etc/ldap/schema/samba.ldif''' root@easton2:/tmp# '''_''' ===Inserting the LDIF file in the LDAP server=== Time to actually invoke ''ldapadd'' which can put this schema in our LDAP server. root@easton2:/tmp# '''ldapadd -QY EXTERNAL -H ldapi:/// -f /etc/ldap/schema/samba.ldif''' adding new entry "cn=samba,cn=schema,cn=config" root@easton2:/tmp# '''_''' 511648986d39162ee4c4d1b0aa39819f84737f44 3082 3081 2016-02-21T21:44:27Z Saruman! 2 /* Post-install reconfiguration */ wikitext text/x-wiki Note: if you need information on the OpenLDAP version from Debian 5.0, see this page: [[OpenLDAP 2.4.11]] == OpenLDAP installation== Note: we're going to install OpenLDAP on our server as [http://www.openldap.org/doc/admin24/config.html#Local%20Directory%20Service the local directory service], without replication, referrals or other advanced features. Under Debian Squeeze, this is OpenLDAP 2.4.23. ===Standard installation=== Installing OpenLDAP on your Debian server is ridiculously simple. Just make sure your server is up-to-date (''sudo apt-get update'' followed by ''sudo apt-get upgrade''), and then install the two main components for your OpenLDAP server. First off: the LDAP client and utilities sudo apt-get install ldap-utils This will result in the installation of as much as 8 different packages (''ldap-utils'', ''libgcrypt11'', ''libgnutls26'', ''libgpg-error0'', ''libldap-2.4-2'', ''libsasl2-2'', ''libsasl2-modules'', and ''libtasn1-3''). Next the main component of an LDAP server installation, the stand-alone LDAP daemon "slapd" sudo apt-get install slapd This may also install up to 8 packages (''slapd'', ''libltdl7'', ''libperl5.10'', ''libslp1'', ''odbcinst'', ''odbcinst1debian2'', ''psmisc'' and ''unixodbc''). The Debian configuration script will ask you for only one single thing: an administrator password. As always: generate a strong password! After you've provided the password, the LDAP database is created with the administrator name "admin" and as a base directory, something based on your DNS name. Suppose your internal domain is "amber.lan", then the script will generate ''suffix "dc=amber,dc=lan"''<ref>Should you see a third, empty, domain component (''dc='') then this is caused by a trailing dot in your particular DNS name: the DNS root. You might have specified your domain as "amber.lan.". You ''should'' change your domain name to a name without the DNS root, and you ''must'' regenerate your LDAP directory.</ref>. The above method of configuring yields you an LDAP database with only two objects in it. Suppose your DNS name is "easton2.amber.lan", then the two objects are: * a single Organization (o="amber.lan") with Distinguished Name dn="dc=amber,dc=lan" * a single administrator with Common Name cn="admin", and dn="cn=admin,dc=amber,dc=lan" Note, however, that there's ''also'' a second LDAP database, "cn=config", which on your server is located under ''/etc/ldap/slapd.d''. We'll cover what's in it further on. <references/> ===Testing the installation=== After installation of the package, it should automatically have been started, and should now be operational. This can be checked with a utility like ''nmap'': root@easton2:~# '''nmap -p 389 localhost''' Starting Nmap 5.00 ( <nowiki>http://nmap.org</nowiki> ) at 2011-04-13 21:19 CEST Interesting ports on localhost (127.0.0.1): PORT STATE SERVICE 389/tcp open ldap Nmap done: 1 IP address (1 host up) scanned in 0.40 seconds root@easton2:~#'''_''' Another way to test if the LDAP server is functional, is by querying it with the ''ldapsearch'' utility, part of the package ''ldap-utils''. Let's see if we can find the naming context of the LDAP server: root@easton2:~# '''ldapsearch -x -b <nowiki>''</nowiki> -s base '(objectclass=*)' namingContexts''' # extended LDIF # # LDAPv3 # base <> with scope baseObject # filter: (objectclass=*) # requesting: namingContexts # # dn: namingContexts: dc=amber,dc=lan # search result search: 2 result: 0 Success # numResponses: 2 # numEntries: 1 root@easton2:~# '''_''' With this command, we do a search using * basic authentication (instead of one encrypted with SASL), * searching within the LDAP tree from base <nowiki>''</nowiki> (meaning the absolute root of the tree), * looking for base object only (instead of a one-level search, a subtree search, or a children-search), * filtering for objects of any class, * asking for the naming context of the result. The output shows that the server responds; two objects have been considered, but none match the filter (that the object should have an objectClass). Let's now do the same but with authentication, to see if we can bind to the LDAP server. We'll first use an incorrect password, then the correct one: root@easton2:~# '''ldapsearch -W -D "cn=admin,dc=amber,dc=lan"''' Enter LDAP Password: ldap_bind: Invalid credentials (49) root@easton2:~# '''ldapsearch -W -D "cn=admin,dc=amber,dc=lan"''' Enter LDAP Password: # extended LDIF # # LDAPv3 # base <> (default) with scope subtree # filter: (objectclass=*) # requesting: ALL # # search result search: 2 result: 32 No such object # numResponses: 1 root@easton2:~# '''_''' Finally, you could simply install and run a graphical management tool for LDAP servers, like [http://directory.apache.org/studio/ Apache Directory Studio]. Note however that if this check fails, then this could also mean problems with firewalls, network connections et cetera. ===Post-install reconfiguration=== Since the default configuration with the server's DNS domain as LDAP base might not always be the most convenient configuration, you could run the configuration again using ''dpkg-reconfigure slapd''. However, following this procedure is '''only''' necessary if you want to change any of the default installation values like the backend database type or DNS domain name; things like the organization name can be edited with other means, as will be shown later on. To be able to reconfigure the LDAP service, you can run the reconfiguration command ''sudo dpkg-reconfigure slapd''. Contrary to some older versions of Debian, you do not need to manually stop the ''slapd'' daemon, and you don't need to manually remove the old configuration or database (in fact, if you do, then the ''slapd'' package will break, so you cannot easily remove it with APT tools). Interestingly enough, this reconfiguration asks you many ''more'' questions. The answers could look like this: omit OpenLDAP config: no DNS domain name: saruman.biz Organization name: Saruman Administrator passwd: wEt3udes Database backend: MDB DB remove after purge: yes Move old DB: yes Allow LDAPv2: no As you can see, the reconfiguration yields much more configuration options than plain installation - although really you'll probably answer most questions with their default values anyway. The above method of configuring yields you an LDAP database with only two objects in it: * a single Organization (o="Saruman") with Distinguished Name dn="dc=saruman,dc=biz" * a single administrator with Common Name cn="admin", and dn="cn=admin,dc=saruman,dc=biz" Also note that the reconfiguration creates a backup of the "old" LDAP database in a directory with a name like ''/var/backups/unknown-2.4.40+dfsg-1+deb8u2.ldapdb''; if you just reconfigured after installation, then you probably don't need this backup, so you can remove it. The database that your OpenLDAP server uses is a standard Berkeley DB (BDB/HDB) database or something similar. Now we most likely will require some other databases as well in our server setup, something modern like PostgreSQL or MySQL - so why don't we configure our OpenLDAP to use this same database as well? For the answer, see [http://www.openldap.org/doc/admin24/intro.html#LDAP%20vs%20RDBMS here] - in short, the LDAP tree structure does not lend itself very well to inclusion in a modern relational database. Thus, we advise to stick with one of the specialized databases provided with Debian/OpenLDAP. Now, for the database backend, we have the choice between the following flavours: * the ''bdb'' backend used to be the recommended primary backend for a normal slapd database. It uses the Oracle Berkeley DB package, referred to as ''BDB'', to store data. It makes extensive use of indexing and caching to speed data access. * the ''hdb'' backend is a variant of the ''bdb'' backend that uses a hierarchical database layout which supports subtree renames. It is otherwise identical to the ''bdb'' behavior, and all the same configuration options apply. * the ''mdb'' backend is a transactional backend built on OpenLDAP's [https://en.wikipedia.org/wiki/Lightning_Memory-Mapped_Database Lightning Memory-Mapped Database] (LMDB). In Debian 8.0 "Jessie" with OpenLDAP 2.4.40, MDB is the default backend. ==OpenLDAP server configuration== <small>(text from http://www.rjsystems.nl/en/2100-d6-openldap-provider.php)</small> As of OpenLDAP 2.4.23-3, the ''slapd'' runtime configuration is fully LDAP-enabled. The default is to manage it using the standard LDAP operations with data in LDIF. The old ''slapd.conf'' format is still supported, but since that file must now be converted to the new ''slapd-config'' format to allow runtime changes to be saved, it seems likely that the developers will eventually phase it out. Therefore, we'll focus only on the new configuration method, the main advantage of which is that any changes made are immediately active, so it is no longer necessary to restart ''slapd'' after making configuration changes. The new configuration format uses a slapd backend database that is found in the ''/etc/ldap/slapd.d/'' directory. The configuration is stored as a special LDAP directory with a predefined schema and DIT, the root of which is called ''cn=config''. If you go look there, you'll find that most parts of this LDAP directory consist of editable flat files. ===Check the current LDAP configuration=== From the command line, there really are several ways to check the current LDAP configuration: * from the server itself, you can use the trusty ''ldapsearch'' command, running under root: this'll authenticate with user ID 0. Filtering only for distinguished names: root@easton2:/etc/ldap# '''ldapsearch -LLL -Y EXTERNAL -H ldapi:/// -b cn=config dn''' SASL/EXTERNAL authentication started SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth SASL SSF: 0 dn: cn=config dn: cn=module{0},cn=config dn: cn=schema,cn=config dn: cn={0}core,cn=schema,cn=config dn: cn={1}cosine,cn=schema,cn=config dn: cn={2}nis,cn=schema,cn=config dn: cn={3}inetorgperson,cn=schema,cn=config dn: olcBackend={0}hdb,cn=config dn: olcDatabase={-1}frontend,cn=config dn: olcDatabase={0}config,cn=config dn: olcDatabase={1}hdb,cn=config root@easton2:/etc/ldap# '''_''' * to get an idea of what the ''cn=config'' database looks like ''within LDAP itself'', you can run this command: root@easton2:/etc/ldap# '''slapcat -b cn=config''' dn: cn=config objectClass: olcGlobal cn: config olcArgsFile: /var/run/slapd/slapd.args olcLogLevel: none olcPidFile: /var/run/slapd/slapd.pid olcToolThreads: 1 '''''(more LDIF texts)''''' entryUUID: f2a8f568-fa40-102f-8b9d-5d4cbccf32a9 creatorsName: cn=admin,cn=config createTimestamp: 20110413174103Z entryCSN: 20110413174103.641065Z#000000#000#000000 modifiersName: cn=admin,cn=config modifyTimestamp: 20110413174103Z root@easton2:/etc/ldap# '''_''' : As you can see, this generates a pretty large LDIF dump of the contents of the ''cn=config'' directory. Much of it consists of schema information. The LDAP configuration directives are attributes of the directory entries (objects) and most them start with the prefix "olc" ('''O'''pen'''L'''DAP '''C'''onfiguration). Also, some of the objects have names with numbers between curly brackets. This is to compensate for the fact that LDAP databases do not store their contents in any particular order; they are inherently unordered. The numbers constitute a numeric index to ensure a consistent order in the configuration database and thereby preserve all ordering dependencies. The index numbers, however, are generated automatically in the order they are created and usually do not have to be provided. * you can see the configuration by browsing through all the plain-text flat files in ''/etc/ldap/slapd.d/'' and its subdirectories. Note that by default there is no way to do this remotely. If you'd like to browse this configuration using a GUI tool like [http://directory.apache.org/studio/ apache directory studio], don't bother. Debian sets the ''cn=config'' part of the database with a root user of ''cn=admin,cn=config'', but without a password, so you cannot bind to the ''cn=config'' database as anything else than the local root user. Thus you cannot access the ''cn=config'' database by GUI. ===Adding or modifying the cn=config admin password=== To add a password to the config RootDN, we first must generate one; for this we can use the ''slappasswd'' command. By default it'll create an SSHA password, but by specifying MD5 as hash (using '' -h {MD5}'') it will create an MD5 encrypted password. The command interactively asks you for the password, and won't show you what you've typed, so be precise: root@easton2:/etc/ldap# '''slappasswd -h {MD5}''' New password: Re-enter new password: {MD5}d5axCh6gYGjhfK4PGs09us== root@easton2:/etc/ldap# '''_''' Now we determine the DN (Distinguished Name) for the database that contains the RootDN password. We'll also check if there isn't a password in place already. To do this we used the following LDAP search command. root@easton2:/etc/ldap# '''ldapsearch -LLL -Y EXTERNAL -H ldapi:/// -b cn=config olcRootDN=cn=admin,cn=config dn olcRootDN olcRootPW''' SASL/EXTERNAL authentication started SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth SASL SSF: 0 dn: olcDatabase={0}config,cn=config olcRootDN: cn=admin,cn=config root@easton2:/etc/ldap# '''_''' Note the olcDatabase line, as it's the result we were looking for; it'll be needed for the ''ldapmodify'' command. Furthermore, note the absence of an olcRootPW entry; this is the starting point for a Debian OpenLDAP server.<br> Now we can stick in a new password. If no password is present, you can use this interactive procedure: root@easton2:/etc/ldap# '''ldapmodify -Y EXTERNAL -H ldapi:///''' SASL/EXTERNAL authentication started SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth SASL SSF: 0 '''dn: olcDatabase={0}config,cn=config''' '''add: olcRootPW''' '''olcRootPW: {MD5}d5axCh6gYGjhfK4PGs09us==''' modifying entry "olcDatabase={0}config,cn=config" root@easton2:/etc/ldap# '''_''' Note the following points: * we use the olcDatabase location as found with the previous ''ldapsearch'' command; * we input the MD5 password that we've generated previously; * as soon as you put in an empty line, the entry gets added; * you have to use CTRL-D to end this interactive mode; * if a password was already in place, we could still use the above, but we'd interactively feed the second line as '''replace: olcRootPW'''. We could also put the password in an ldif file, and feed that to the server. To this end, we'd create an ldif file with the following content: dn: olcDatabase={0}config,cn=config changetype: modify add: olcRootPW olcRootPW: {MD5}d5axCh6gYGjhfK4PGs09us== If this file is called ''addpassword.ldif'' and is created in ''/tmp'', then the addition can be executed using root@easton2:/etc/ldap# '''ldapmodify -Y EXTERNAL -H ldapi:/// -f /tmp/addpassword.ldif''' SASL/EXTERNAL authentication started SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth SASL SSF: 0 modifying entry "olcDatabase={0}config,cn=config" root@easton2:/tmp# '''_''' ==Adding or modifying (configuration) information== The simple way of changing anything in the database goes like this: ===Method 1: interactive CLI tool=== As an example, let's add an index to the configuration. We'll start by seeing which indices already exist, then interactively add two indices. Finally, we check that the indices are there: root@easton2:/tmp# '''ldapsearch -LLLQY EXTERNAL -H ldapi:/// -b cn=config olcDatabase={1}hdb olcDbIndex''' dn: olcDatabase={1}hdb,cn=config olcDbIndex: objectClass eq root@easton2:/tmp# '''ldapmodify -Y EXTERNAL -H ldapi:///''' SASL/EXTERNAL authentication started SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth SASL SSF: 0 '''dn: olcDatabase={1}hdb,cn=config''' '''add: olcDbIndex''' '''olcDbIndex: cn eq''' '''olcDbIndex: uid eq''' modifying entry "olcDatabase={1}hdb,cn=config" root@easton2:/tmp# '''ldapsearch -LLLQY EXTERNAL -H ldapi:/// -b cn=config olcDatabase={1}hdb olcDbIndex''' dn: olcDatabase={1}hdb,cn=config olcDbIndex: objectClass eq olcDbIndex: cn eq olcDbIndex: uid eq root@easton2:/tmp# '''_''' (And ofcourse we press ctrl-D to end interactive mode).<br>Note: we can /modify multiple attributes in one stanza, but we can also add multiple objects/attributes in one ''ldapmodify'' session: * If you input an empty line, you can start another ''dn:'' line, and perform another action; * If you input a minus sign by itself on a line, then OpenLDAP will assume you'll be performing another action in/on the same object. Modifying works almost the same; we only need keyword ''replace'' instead of ''add'': root@easton2:/tmp# '''ldapsearch -LLLQY EXTERNAL -H ldapi:/// -b cn=config -s base olcLogLevel''' dn: cn=config olcLogLevel: none root@easton2:/tmp# '''ldapmodify -Y EXTERNAL -H ldapi:///''' SASL/EXTERNAL authentication started SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth SASL SSF: 0 '''dn: cn=config''' '''changetype: modify''' '''replace: olcLogLevel''' '''olcLogLevel: stats''' modifying entry "cn=config" root@easton2:/tmp# '''ldapsearch -LLLQY EXTERNAL -H ldapi:/// -b cn=config -s base olcLogLevel''' dn: cn=config olcLogLevel: stats root@easton2:/tmp# '''_''' Note the ''-s base'' option that limits the search for the ''olcLogLevel'' attribute to the ''cn=config'' container. Deleting information from an LDAP tree rarely ever happens, because once an attribute is used for anything, you aren't allowed to delete it, only modify it. However, if you want to delete anything, you can use the changetype "modify" with action "delete": root@easton2:/tmp# '''ldapmodify -Y EXTERNAL -H ldapi:///''' SASL/EXTERNAL authentication started SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth SASL SSF: 0 '''dn: olcDatabase={0}config,cn=config''' '''changetype: modify''' '''delete: olcRootPW''' modifying entry "olcDatabase={0}config,cn=config" root@easton2:/tmp# '''_''' ===Method 2: use an ldif file=== ===Method 3: use an LDAP browser=== With this method, you just use your LDAP browser for the addition or modification, according to its specific usage instructions. In the back, the tool will communicate with the LDAP server as you would in the previous methods. Note however, that this method relies on a bind account in the configuration database, which is a serious security risk. ==Adding schemas== A major task in LDAP maintenance is the addition of LDAP schemas. By default, only 4 schemas will be present in your LDAP server: ''core'', ''cosine'', ''nis'' and ''inetorgperson''. Any other schema, -- say, for Samba -- would need to be added. ===Checking existing schemas=== Let's first check which schemas are already installed. Let's try two different methods, and see what they'll show out of the box: root@easton2:/tmp# '''ldapsearch -LLLQY EXTERNAL -H ldapi:/// -b cn=schema,cn=config "(objectClass=olcSchemaConfig)" dn''' dn: cn=schema,cn=config dn: cn={0}core,cn=schema,cn=config dn: cn={1}cosine,cn=schema,cn=config dn: cn={2}nis,cn=schema,cn=config dn: cn={3}inetorgperson,cn=schema,cn=config root@easton2:/tmp# '''ls -l /etc/ldap/slapd.d/cn=config/cn=schema''' total 40 -rw------- 1 openldap openldap 15474 Jun 13 17:39 cn={0}core.ldif -rw------- 1 openldap openldap 11308 Jun 13 17:39 cn={1}cosine.ldif -rw------- 1 openldap openldap 6438 Jun 13 17:39 cn={2}nis.ldif -rw------- 1 openldap openldap 2802 Jun 13 17:39 cn={3}inetorgperson.ldif root@easton2:/tmp# '''_''' ===Creating a suitable LDIF file for the schema=== To add a schema, you need a schema in LDIF format, which you can then add to the LDAP database using the ''ldapadd'' command. Suppose you have a schema file ''samba.schema'' which you've copied to the ''/etc/ldap/schema'' directory. You'd first have to convert this to a suitable LDIF file. This can be done using ''slaptest'', however ''slaptest'' requires access to the other schemas that your new schema is building on. So we now do this: * We create a file ''schema_convert.conf'' with the content shown below. Note that we're including the schema files of all the schemas that are already in our LDAP server. Furthermore, because we may need it again with the next schema addition, it makes sense to save this file under ''/etc/ldap/schema'': include /etc/ldap/schema/core.schema include /etc/ldap/schema/cosine.schema include /etc/ldap/schema/nis.schema include /etc/ldap/schema/inetorgperson.schema include /etc/ldap/schema/samba.schema * now we create a working directory where ''slaptest'' can put our new LDIF file, and have ''slaptest'' create the configuration: root@easton2:/tmp# '''mkdir /tmp/ldif_output''' root@easton2:/tmp# '''slaptest -f /etc/ldap/schema/schema_convert.conf -F /tmp/ldif_output''' config file testing succeeded root@easton2:/tmp# '''_''' * The previous step has created a directory structure under ''/tmp/ldif_output'' that actually mirrors the config directory ''/etc/ldap/slapd.d/cn=config/cn=schema'', but it contains a shiny new ''cn={4}samba.ldif'' file. We need to edit this file a bit before we can actually feed it to the LDAP server. Thus we'll edit it using (note the extra backslashes to escape the equal-sign and curly brackets): root@easton2:/tmp# '''vi /tmp/ldif_output/cn\=config/cn\=schema/cn\=\{4\}samba.ldif''' * We need to change and edit some parts of ''cn={4}samba.ldif'': ** Near the top we find ''dn: cn={4}samba''. We'll change this to the correct distinguished name ''dn: cn=samba,cn=schema,cn=config'' ** Also near the top: ''cn: {4}samba''. We'll change this to ''cn: samba'' ** The last seven lines look like the bit below - we need to remove these lines: structuralObjectClass: olcSchemaConfig entryUUID: f19250ba-1057-1031-88b7-8301a25f1d46 creatorsName: cn=config createTimestamp: 20120401150603Z entryCSN: 20120401150603.478495Z#000000#000#000000 modifiersName: cn=config modifyTimestamp: 20120401150603Z * We'll store the cleaned up LDIF file in ''/etc/ldap/schema'' with the originating schema file root@easton2:/tmp# '''mv /tmp/ldif_output/cn\=config/cn\=schema/cn\=\{4\}samba.ldif /etc/ldap/schema/samba.ldif''' root@easton2:/tmp# '''_''' ===Inserting the LDIF file in the LDAP server=== Time to actually invoke ''ldapadd'' which can put this schema in our LDAP server. root@easton2:/tmp# '''ldapadd -QY EXTERNAL -H ldapi:/// -f /etc/ldap/schema/samba.ldif''' adding new entry "cn=samba,cn=schema,cn=config" root@easton2:/tmp# '''_''' 95d6d7100bb39682645739900b8cb286c3b11a6c 0 1489 3083 3061 2016-02-22T10:32:40Z Saruman! 2 /* Inserting data */ wikitext text/x-wiki ==E-mail server setup== What we want to accomplish here is the setup of a mail server with the following properties: * can serve multiple mail domains * can relay mail for other domains to other mail servers * can have one or more mailboxes per domain * users of these mailboxes can be virtual (do not need to have a Linux user account) * can have multiple aliases per mailbox * can forward mail for certain aliases to multiple mailboxes For this type of mail server setup, we owe a great thankyou to [https://workaround.org/ispmail/squeeze Christoph Haas], whose advise has helped us create flexible and reliable mail servers since 2003. ==Preparation== We'll assume that the server currently has no mailserver installed, at least no other than the default ''exim'' mailserver. Furthermore, the server is already fitted with MySQL, and this database is running without problems. The hostname of the server must be set correctly, so that ''hostname -f'' returns a valid DNS name, like ''lighthouse.saruman.biz.''. It might also be an internal name like ''lighthouse.saruman.lan.'' but that will require us to give extra attention to the name under which Postfix will contact its collegues on the Internet. Also, the server can correctly [Networking_section#DNS_resolution_under_Debian | resolve DNS names] like [http://www.debian.org www.debian.org], preferably by running it's own caching DNS server. The server is kept on the correct date and time using NTP, TCP port 25 is open on the server, the ISP will allow connections from Internet to this port, and if there's a firewall running on this server, then it has port 25 open so as to not block incoming e-mail. ==Software installation== As a first step, we use [[APT and aptitude|apt or aptitude]] to make sure that our server is up-to-date. Then we can install the necessary software packages. Under Debian 5.0 "Lenny", the (single) packages is: * ''postfix'', the mail server itself - this includes the "virtual package" postfix-tls, that we want to use to secure connections to Postfix with the TLS protocol At the same time we can - and must - purge the following packages: * exim4 * exim4-base * exim4-daemon-light * exim4-config In ''aptitude'', only press "go" when you've marked all four of these packages "purge", or you cannot install postfix. When installing the postfix package, the Debian installer script will ask you several questions, which you can answer like this: * General type of mail configuration: Internet site * System mail name: the FQDN of the mail server that you've verified in the previous section. Note that the script will try to guess the DNS name, but that might yield a DNS name with a trailing dot. That is technically correct, but the installation script will barf. Remove the trailing dot before hitting &lt;enter>! * Postmaster mail address: the address that all mail should go to that is addressed to "root" and "postmaster". * Domain list: give the list of all domains that the machine can consider itself the FINAL destination for. This should at a minimum include an empty value, "localhost" and the FQDN of the machine itself (no trailing dots!); however, if you're running your own mail domain, you can also add that (e.g. "saruman.biz"). Thus, the list could look like this: saruman.biz, lighthouse.saruman.lan, localhost.saruman.lan, , localhost * Force synchronous updates? We think that's not necessary, but please read the question and decide for yourself * Local networks: something like ''127.0.0.0/8 [::ffff:127.0.0.0]/104 [::1]/128 192.168.67.0/24'' (the default, augmented with your local IP range) * Mailbox size limits: you can give postfix a limit in bytes, but we're going to use one single big mailbox for all users, so we cannot let Postfix guard it. Leave it at 0 (zero) so we don't have a size limit. * Character for local address extension: we leave it at ''+'' * Internet protocols to use: currently we don't have IPv6 support, so there's no sense in letting Postfix try to serve IPv6. We choose ''ipv4'' only. With the above data, the Debian install script for Postfix can do its job and configure Postfix with some basic settings. Now that Postfix is installed, we can install some dependent packages (we could install them in the same run, but if anything goes amiss with the postfix installation, then these packages are going to remain unconfigured as well): * ''postfix-doc'', the accompanying documentation; * ''postfix-mysql'', necessary to have Postfix talk to our MySQL server; * ''postfix-pcre'' to be able to parse regular expressions, which which we can combat spam; * ''dovecot-imapd'' is a daemon that will provide your users with IMAP access to their mail; * ''dovecot-pop3d'' is another daemon, but for the POP3 protocol. ==Virtual Mailman creation== When we're done, we'll need a "system user", a sort of virtual mailman that is the owner of all mailboxes that we're serving. We suggest the name "vmail" for this user. Note: this user does not get his own mailbox (i.e. there's no mailbox at vmail@saruman.biz). To create this user, and his home directory, we can run the following commands: groupadd -g 120 vmail useradd -g vmail -u 120 vmail -d /data/vmail -m -s /bin/false As you see, we've chosen a group ID and user ID of 120 (after confirming that this ID was not taken by another group or user, by checking ''/etc/passwd'' and ''/etc/group''. Furthermore, we've decided to keep the ''vmail'' user's home directory not under ''/home/vmail'', but in a special place where we're going to expect server data to reside - in our server, the ''/data'' directory (which is a RAID-5 array mounted under root). By adding ''-m'', we've actually created the home directory, and adding ''-s /bin/false'' makes totally sure that the user ''vmail'' can never ever log in - even if we've not created a password for this user, so ''vmail'' shouldn't be able to log in anyway. Better safe than sorry. To tell Postfix that this ''vmail'' user is someone special, we run postconf -e virtual_uid_maps=static:120 postconf -e virtual_gid_maps=static:120 That makes postfix understand that all mail for the virtual mail domains must be written to disk with these specified user and group ID's. ==MySQL configuration== ===Database preparation=== We will use the MySQL database to record data on our mail system, and then give our Postfix access to this database so that it can read its configuration from there. For starters, we'll create a MySQL database named "vmail", and a MySQL user named "vmail_admin" that can read all necessary data from that "vmail" database. Then, we create the necessary tables, and a view that links these tables. We do this with the MySQL client ''mysql''. However, we're quite lazy, so we don't create this database by hand (that's error-prone), but by use of a script [[create.vmail.sql]]. To this end, feed the [[create.vmail.sql]] script into the ''mysql'' client like this: mysql -u root -p < create.vmail.sql (This of course assumes you have ''create.vmail.sql'' in your current working directory; if not you can include the path to the file.) Simply give the MySQL root user password, and the script creates the database, the user, the necessary tables, and the view.<br> A note of caution: it is never a good idea to just run scripts without a proper understanding of what it does. Especially with MySQL, it will be advantageous if you understand the SQL commands. Open the script in a text editor, open the [http://dev.mysql.com/doc/refman/5.0/en/ MySQL command reference], and trace back what the script does exactly. ===Inserting data=== Next up, we fill the database with the first sets of values (either test data or the first of our production data). We'll start off with the virtual domains that we're hosting, by running the mysql client and feeding it information like this: mysql -u root -p vmail mysql> INSERT INTO virtual_domains (id, vdomain) VALUES (1, 'saruman.biz'); mysql> INSERT INTO virtual_domains (vdomain) VALUES ('wiki.saruman.biz'); mysql> INSERT INTO virtual_domains (vdomain) VALUES ('shop.saruman.biz'); This has the effect of creating three entries. You can check that everything worked as planned by executing mysql> select * from virtual_domains; Note: only the first entry needs an ''id'' value, because in MySQL we've defined that field as AUTO_INCREMENT. After creating your first virtual domain in the table, you never have to use a statement like the first INSERT again, only statements like the other two. Now the MySQL database has the information needed by Postfix to recognise that you have three virtual mail domains (namely the three domains in the VALUES section) for which it hosts virtual mailboxes. Postfix cannot read this information yet, but that'll be taken care of in the next section. Whle still within the mysql client, we can now create users: mysql> INSERT INTO virtual_users (id, domain_id, user, passwd) VALUES (1, 1, 'jan', MD5('JanSecret')); mysql> INSERT INTO virtual_users (domain_id, user, passwd) VALUES (1, 'mike', MD5('MikeSecret')); mysql> INSERT INTO virtual_users (domain_id, user, passwd) VALUES (3, 'shopkeeper', MD5('ShopSecret')); This has the effect of creating three users "jan" (in domain saruman.biz), "mike" (in domain saruman.biz) and "shopkeeper" (in domain shop.saruman.biz). Again, the ''id'' value is only ever needed in the first statement, because from now on every user addition will auto-increment ''id''. The passwords shown are encrypted with MD5, and put in the ''passwd'' field. Later on, the users will be able to access their mailboxes using this password; we won't tell Postfix anything about them, because it doesn't need the passwords. You can check the content of the ''virtual_users'' table with the right "select" statement, and you can now also see that the view ''view-users'' works: mysql> select * from virtual_users; mysql> select * from view_users; Should you need to update a user's password from the command line, you can use the following command, provided you've looked up that user's ''id'' : UPDATE virtual_users set passwd = 'MD5('<password>')' WHERE id = '<id>'; Next up, we're going to add some aliases, which are alternative e-mail addresses for the users; their primary e-mail address can already be seen in the ''view_users'' view, but perhaps you also want mail to "webmaster@shop.saruman.biz" to arrive at one or more mailboxes, e.g. in the mailbox for user "shopkeeper" (within domain "shop.saruman.biz") and this guy's home address ("j.doe@example.com"). Furthermore, we'll define catchall-addresses for all domains, that'll send all mail for which no mailbox can be found to the mailbox of user Mike (for the first two domains) and Webmaster (for shop.saruman.biz; Webmaster himself is an alias yet again, that points to shopkeeper@shop.saruman.biz). To create the catchall, leave out a value for the source address. This creates the empty value for source that will be expanded (using source@domain) to "@domain". mysql> INSERT INTO virtual_aliases (id, domain_id, source, destination) VALUES (1, 2, 'webmaster', 'shopkeeper@shop.saruman.biz'); mysql> INSERT INTO virtual_aliases (domain_id, source, destination) VALUES (2, 'webmaster', 'j.doe@example.com'); mysql> INSERT INTO virtual_aliases (domain_id, destination) VALUES (1, 'mike@saruman.biz'); mysql> INSERT INTO virtual_aliases (domain_id, destination) VALUES (2, 'mike@saruman.biz'); mysql> INSERT INTO virtual_aliases (domain_id, destination) VALUES (3, 'webmaster@saruman.biz'); Again, we don't need to add the ''id'' value any more after the first ever insertion into this table. We can check the result by running a select statement against the ''virtual_aliases'' table and ''view_aliases'' view: mysql> select * from virtual_aliases; mysql> select * from view_aliases; == Postfix configuration for MySQL lookups== Next, we're going to tell Postfix to use the ''vmail'' database, and also how to read the database (Postfix never writes the MySQL database). To this end, we're going to create three configuration files in directory ''/etc/postfix''. We'll start off with one configuration file, with which Postfix can determine if a domain name is among the domain(s) that it's actually hosting mailboxes for. Then we'll create the config file that checks the table that contains all the users that have a virtual mailbox, and finally we create the lookup for the table with all the aliases. ===Virtual mail domains lookup=== Create file ''/etc/postfix/mysql-virtual-domains.cf'' with the following content: user = vmail_admin password = SuperSecret hosts = 127.0.0.1 dbname = vmail query = SELECT 1 FROM virtual_domains WHERE vdomain='%s' Next, we tell postfix to check this configuration file when it needs to check "virtual_mailbox_domains": postconf -e virtual_mailbox_domains=mysql:/etc/postfix/mysql-virtual-domains.cf Use of this configuration file in postfix has the effect of returning "yes" when checking our database for the domain part of an email address. Naturally, this configuration file has to be fitted with the actual ''vmail_admin'' password rather than our example "SuperSecret". === Virtual mail user lookup=== Create the file ''/etc/postfix/mysql-virtual-mailbox-maps.cf'' with the following content: user = vmail_admin password = SuperSecret hosts = 127.0.0.1 dbname = vmail query = SELECT 1 FROM view_users WHERE email='%s' Next, we tell Postfix that this mapping file is supposed to be used for the ''virtual_mailbox_maps'' mapping: postconf -e virtual_mailbox_maps=mysql:/etc/postfix/mysql-virtual-mailbox-maps.cf The lookup of virtual mailboxes should work with the data we've put into the database previously. i.e. postmap -q jan@saruman.biz mysql:/etc/postfix/mysql-virtual-mailbox-maps.cf should return a '''1''' to acknowledge that "jan@saruman.biz" is indeed a virtual mailbox in our Postfix configuration. === Virtual alias lookup=== Create another cf file at ''/etc/postfix/mysql-virtual-alias-maps.cf'': user = vmail_admin password = SuperSecret hosts = 127.0.0.1 dbname = vmail query = SELECT destination FROM view_aliases WHERE email='%s' And create yet another cf file at ''/etc/postfix/mysql-email2email.cf'': user = vmail_admin password = SuperSecret hosts = 127.0.0.1 dbname = vmail query = SELECT email FROM view_users WHERE email='%s' Again, we tell Postfix that this mapping file is supposed to be used for the ''virtual_alias_maps'' mapping: postconf -e virtual_alias_maps=mysql:/etc/postfix/mysql-virtual-alias-maps.cf,mysql:/etc/postfix/mysql-email2email.cf The lookup of virtual aliases should now work as designed: postmap -q shopkeeper@shop.saruman.biz mysql:/etc/postfix/mysql-virtual-alias-maps.cf postmap -q webmaster@shop.saruman.biz mysql:/etc/postfix/mysql-virtual-alias-maps.cf If you've put in the data from the previous section, then both commands should return the same result: ''shopkeeper@saruman.biz''. This shows that Postfix will deliver mail to shopkeeper or to webmaster to the mailbox of shopkeeper. ===Finishing up configuration files=== When everything works as planned, then we secure the configuration files against prying eyes. Remember, the configuration files contain the user/password combination which which to access the ''vmail'' SQL database. The ''vmail_admin'' user has only read rights, and passwords in there are encrypted, but nevertheless, this is information we need to protect. Thus: chown root:postfix /etc/postfix/mysql-*.cf chmod u=rw,g=r,o= /etc/postfix/mysql-*.cf This protects all four configuration files since only root can write them, members of group ''postfix'' can read them, and the rest of the world cannot access them at all. ==Configuring mail delivery through Dovecot LDA== E-mails get delivered to the virtual mailboxes by means of a Mail Delivery Agent (MDA). With Postfix, the standard MDA for delivery to virtual mailboxes is called ''virtual'', but we're not going to use that; we're going to use ''[http://wiki.dovecot.org/LDA Dovecot LDA]'', which is a program called ''deliver''. By the way, the abbreviation LDA stands for Local Delivery Agent, which of course means more or less the same as MDA. ===Enabling the Dovecot daemon=== To make Postfix use Dovecot LDA, we add the following line to ''/etc/postfix/master.cf'': dovecot unix - n n - - pipe flags=DRhu user=vmail:vmail argv=/usr/lib/dovecot/deliver -d ${recipient} This declares the service "dovecot" to mean using the program ''/usr/lib/dovecot/deliver'' with the right parameters. If we now let Postfix reload its files, it'll learn about this new service. Subsequently we can instruct Postfix to start using it, by declaring service "dovecot" to be the virtual transport of choice, and specifying one Dovecot-specific variable: postfix reload postconf -e virtual_transport=dovecot postconf -e dovecot_destination_recipient_limit=1 ===Dovecot default configuration=== Now to configure Dovecot itself: open ''/etc/dovecot/dovecot.conf'' with your favourite editor [[vim]]; first make sure the ''protocols ='' line reads protocols = imap imaps pop3 pop3s (which it should by default). The second setting is quite crucial. By default, the location of the mail directories is found automatically by Dovecot, but here that won't work. Find the line that reads ''#mail_location ='', and change it to mail_location = maildir:/data/vmail/%d/%n/Maildir This will look for mail in directory ''/data/vmail/'''DOMAIN'''/'''USER'''/Maildir'', and expect this directory to be in "maildir" format. Next look for a section called "auth default". First define the allowed authentication mechanisms: mechanisms = plain login Then inside that same section you need to uncomment: passdb sql { args = /etc/dovecot/dovecot-sql.conf } which tells Dovecot that the passwords are stored in an SQL database (it's obvious that we'll now have to create this conf-file) and: userdb static { args = uid=120 gid=120 home=/data/vmail/%d/%n allow_all_users=yes } to tell Dovecot where the mailboxes are located. This is similar to the ''mail_location'' setting. Next task: comment out the section ''passdb pam'', so that Dovecot doesn't accidentally try to service local users as well. Next up: tell Dovecot to handle IMAP the same as previous versions of this virtual mailserver have - this can prove to be quite tricky if you already have mailboxes full of mail, put there by e.g. Courier-IMAP. What works for us, is namespace private { separator = . prefix = inbox = yes } However, your mileage may vary. You'll also want to comment out the ''passdb pam'' sections, since we're not hosting mail for local users. Next up, we'll edit the section ''socket listen'' so that Dovecot can access the user database (master section), and our Postfix mailserver can access Dovecot (client section): socket listen { master { path = /var/run/dovecot/auth-master mode = 0600 user = vmail } client { path = /var/spool/postfix/private/auth mode = 0660 user = postfix group = postfix } } Finally, the protocol section, where we specify log files, an address to put in mails when we send out nondelivery reports, and a place to store scripts: protocol lda { log_path = /var/log/appslog/mail/dovecot-deliver.log auth_socket_path = /var/run/dovecot/auth-master postmaster_address = postmaster@saruman.biz mail_plugins = cmusieve global_script_path = /data/vmail/globalsieverc } You could change the log path to "log_path =" With a empty logpath syslog will log the events. Now that we've finished the Dovecot configuration file, we need to create a fitting MySQL configuration file for Dovecot. The file is ''/etc/dovecot/dovecot-sql.conf'', and its contents are driver = mysql connect = host=127.0.0.1 dbname=vmail user=vmail_admin password=SuperSecret default_pass_scheme = PLAIN-MD5 password_query = SELECT email as user, passwd as password FROM view_users WHERE email='%u'; When you've created this file (as root), change the attributes of ''dovecot-sql.conf'' and ''dovecot.conf'', and then restart Dovecot to start using the new configuration. Note: ''dovecot.conf'' needs to be read by Postfix, hence the group ownership for the file. chmod u=rw,g=,o= /etc/dovecot/dovecot-sql.conf chgrp vmail /etc/dovecot/dovecot.conf chmod u=rw,g=r,o= /etc/dovecot/dovecot.conf /etc/init.d/dovecot restart To get some more logging in the case something goes wrong. Uncomment the folling and change to yes. auth_verbose = yes auth_debug = yes auth_debug_passwords = yes ===Dovecot SSL configuration=== Out of the (Debian) box, Dovecot is SSL-enabled. We'll now replace the generic SSL-certificate, generated for the host by the Dovecot installation script, by our own certificate. To ths end, we first [[Creating_digital_certificates_with_our_root_certificate | generate an appropriate certificate]], e.g. an SSL wildcard certificate: "*.saruman.biz". This results in a public and a private certificate, both of which must be placed somewhere where Dovecot expects them and can read them. By default, Dovecot expects the following locations/filenames/owner/attributes: /etc/ssl/certs/dovecot.pem -rw-r--r-- root:dovecot 4624 bytes /etc/ssl/private/dovecot.pem -rw------- root:dovecot 1743 bytes If we may make a suggestion: rename the generated certificates in both locations to dovecot.pem.bak, place your generated certificates in their place, and set the owner/permissions like displayed here. However, if you've generated your own keys, you might have used a passphrase on the private key. You'll have to tell dovecot about it in its configuration file /etc/dovecot/dovecot.conf. To this end, edit the corresponding section by uncommenting the "ssl_" lines, and using your private key password (e.g. "zM7Ertq12") in the appropriate line: ssl_cert_file = /etc/ssl/certs/dovecot.pem ssl_key_file = /etc/ssl/private/dovecot.pem # If key file is password protected, give the password here. Alternatively # give it when starting dovecot with -p parameter. ssl_key_password = zM7Ertq12 Naturally you are free to place the keys in a different location, and/or use a different name... ==Finishing up== This is a good moment to test your configuration, if you haven't been able to test your work inbetween. If everything works as expected, you can add bells and whistles to your configuration. ===''smtpd'' TLS encryption=== The first addition we'd like to present covers the way Postfix handles incoming connections. Since authentication works, we can have Postfix distrust every (unauthenticated) connection: postconf -e mynetworks= Furthermore, since a default SSL certificate is installed by the Debian Postfix installation routine, we can encrypt all our connections using TLS; we enforce this using postconf -e smtpd_use_tls=yes postconf -e smtpd_tls_auth_only=yes Of course, you need to adjust the settings of your IMAP client so that it properly uses TLS and properly authenticates itself. If TLS works, you'll probably want to change the certificate as you have for Dovecot in the previous section. This is again pretty easy. If you haven't yet, now is the time to [[Creating_digital_certificates_with_our_root_certificate | creating that custom SSL certificate]] for our mail server - but you have to make sure that you DON'T use a password on the private key. Unlike Dovecot, Postfix cannot be told the password to the private key somewhere. For starters, look at the TLS-section of your ''main.cf'' that you currently have. Chances are a big chunk of it looks like this: # TLS parameters smtpd_tls_cert_file=/etc/ssl/certs/ssl-cert-snakeoil.pem smtpd_tls_key_file=/etc/ssl/private/ssl-cert-snakeoil.key smtpd_use_tls=yes Now all you need to do is replace the name of the snakeoil-keys with those of appropriate ssl-certificates, the private key of which needs to be NOT passphrase-protected. For this you could copy the Dovecot certificates, if you strip that passphrase in the manner described in the [[Creating_digital_certificates_with_our_root_certificate#Creating_an_SSL_certificate | SSL certificate section]]. The ''main.cf'' then would become: # TLS parameters smtpd_tls_cert_file=/etc/ssl/certs/postfix.pem smtpd_tls_key_file=/etc/ssl/private/postfix.key smtpd_use_tls=yes Restart Postfix, and presto. === Other additions === If everything ''still'' works after these changes, then congratulations, you now have a powerful, flexible and pretty secure mail setup. Of course, there are always points for improvements. We'll cover these in separate pages. One page that we want to direct you to now, is * [[Antispam measures]] for our Postfix mailserver 25579f8199c0396b841d01ce0de2aba13900be2e 3084 3083 2016-02-22T10:35:02Z Saruman! 2 /* Inserting data */ wikitext text/x-wiki ==E-mail server setup== What we want to accomplish here is the setup of a mail server with the following properties: * can serve multiple mail domains * can relay mail for other domains to other mail servers * can have one or more mailboxes per domain * users of these mailboxes can be virtual (do not need to have a Linux user account) * can have multiple aliases per mailbox * can forward mail for certain aliases to multiple mailboxes For this type of mail server setup, we owe a great thankyou to [https://workaround.org/ispmail/squeeze Christoph Haas], whose advise has helped us create flexible and reliable mail servers since 2003. ==Preparation== We'll assume that the server currently has no mailserver installed, at least no other than the default ''exim'' mailserver. Furthermore, the server is already fitted with MySQL, and this database is running without problems. The hostname of the server must be set correctly, so that ''hostname -f'' returns a valid DNS name, like ''lighthouse.saruman.biz.''. It might also be an internal name like ''lighthouse.saruman.lan.'' but that will require us to give extra attention to the name under which Postfix will contact its collegues on the Internet. Also, the server can correctly [Networking_section#DNS_resolution_under_Debian | resolve DNS names] like [http://www.debian.org www.debian.org], preferably by running it's own caching DNS server. The server is kept on the correct date and time using NTP, TCP port 25 is open on the server, the ISP will allow connections from Internet to this port, and if there's a firewall running on this server, then it has port 25 open so as to not block incoming e-mail. ==Software installation== As a first step, we use [[APT and aptitude|apt or aptitude]] to make sure that our server is up-to-date. Then we can install the necessary software packages. Under Debian 5.0 "Lenny", the (single) packages is: * ''postfix'', the mail server itself - this includes the "virtual package" postfix-tls, that we want to use to secure connections to Postfix with the TLS protocol At the same time we can - and must - purge the following packages: * exim4 * exim4-base * exim4-daemon-light * exim4-config In ''aptitude'', only press "go" when you've marked all four of these packages "purge", or you cannot install postfix. When installing the postfix package, the Debian installer script will ask you several questions, which you can answer like this: * General type of mail configuration: Internet site * System mail name: the FQDN of the mail server that you've verified in the previous section. Note that the script will try to guess the DNS name, but that might yield a DNS name with a trailing dot. That is technically correct, but the installation script will barf. Remove the trailing dot before hitting &lt;enter>! * Postmaster mail address: the address that all mail should go to that is addressed to "root" and "postmaster". * Domain list: give the list of all domains that the machine can consider itself the FINAL destination for. This should at a minimum include an empty value, "localhost" and the FQDN of the machine itself (no trailing dots!); however, if you're running your own mail domain, you can also add that (e.g. "saruman.biz"). Thus, the list could look like this: saruman.biz, lighthouse.saruman.lan, localhost.saruman.lan, , localhost * Force synchronous updates? We think that's not necessary, but please read the question and decide for yourself * Local networks: something like ''127.0.0.0/8 [::ffff:127.0.0.0]/104 [::1]/128 192.168.67.0/24'' (the default, augmented with your local IP range) * Mailbox size limits: you can give postfix a limit in bytes, but we're going to use one single big mailbox for all users, so we cannot let Postfix guard it. Leave it at 0 (zero) so we don't have a size limit. * Character for local address extension: we leave it at ''+'' * Internet protocols to use: currently we don't have IPv6 support, so there's no sense in letting Postfix try to serve IPv6. We choose ''ipv4'' only. With the above data, the Debian install script for Postfix can do its job and configure Postfix with some basic settings. Now that Postfix is installed, we can install some dependent packages (we could install them in the same run, but if anything goes amiss with the postfix installation, then these packages are going to remain unconfigured as well): * ''postfix-doc'', the accompanying documentation; * ''postfix-mysql'', necessary to have Postfix talk to our MySQL server; * ''postfix-pcre'' to be able to parse regular expressions, which which we can combat spam; * ''dovecot-imapd'' is a daemon that will provide your users with IMAP access to their mail; * ''dovecot-pop3d'' is another daemon, but for the POP3 protocol. ==Virtual Mailman creation== When we're done, we'll need a "system user", a sort of virtual mailman that is the owner of all mailboxes that we're serving. We suggest the name "vmail" for this user. Note: this user does not get his own mailbox (i.e. there's no mailbox at vmail@saruman.biz). To create this user, and his home directory, we can run the following commands: groupadd -g 120 vmail useradd -g vmail -u 120 vmail -d /data/vmail -m -s /bin/false As you see, we've chosen a group ID and user ID of 120 (after confirming that this ID was not taken by another group or user, by checking ''/etc/passwd'' and ''/etc/group''. Furthermore, we've decided to keep the ''vmail'' user's home directory not under ''/home/vmail'', but in a special place where we're going to expect server data to reside - in our server, the ''/data'' directory (which is a RAID-5 array mounted under root). By adding ''-m'', we've actually created the home directory, and adding ''-s /bin/false'' makes totally sure that the user ''vmail'' can never ever log in - even if we've not created a password for this user, so ''vmail'' shouldn't be able to log in anyway. Better safe than sorry. To tell Postfix that this ''vmail'' user is someone special, we run postconf -e virtual_uid_maps=static:120 postconf -e virtual_gid_maps=static:120 That makes postfix understand that all mail for the virtual mail domains must be written to disk with these specified user and group ID's. ==MySQL configuration== ===Database preparation=== We will use the MySQL database to record data on our mail system, and then give our Postfix access to this database so that it can read its configuration from there. For starters, we'll create a MySQL database named "vmail", and a MySQL user named "vmail_admin" that can read all necessary data from that "vmail" database. Then, we create the necessary tables, and a view that links these tables. We do this with the MySQL client ''mysql''. However, we're quite lazy, so we don't create this database by hand (that's error-prone), but by use of a script [[create.vmail.sql]]. To this end, feed the [[create.vmail.sql]] script into the ''mysql'' client like this: mysql -u root -p < create.vmail.sql (This of course assumes you have ''create.vmail.sql'' in your current working directory; if not you can include the path to the file.) Simply give the MySQL root user password, and the script creates the database, the user, the necessary tables, and the view.<br> A note of caution: it is never a good idea to just run scripts without a proper understanding of what it does. Especially with MySQL, it will be advantageous if you understand the SQL commands. Open the script in a text editor, open the [http://dev.mysql.com/doc/refman/5.0/en/ MySQL command reference], and trace back what the script does exactly. ===Inserting data=== Next up, we fill the database with the first sets of values (either test data or the first of our production data). We'll start off with the virtual domains that we're hosting, by running the mysql client and feeding it information like this: mysql -u root -p vmail mysql> INSERT INTO virtual_domains (id, vdomain) VALUES (1, 'saruman.biz'); mysql> INSERT INTO virtual_domains (vdomain) VALUES ('wiki.saruman.biz'); mysql> INSERT INTO virtual_domains (vdomain) VALUES ('shop.saruman.biz'); This has the effect of creating three entries. You can check that everything worked as planned by executing mysql> select * from virtual_domains; Note: only the first entry needs an ''id'' value, because in MySQL we've defined that field as AUTO_INCREMENT. After creating your first virtual domain in the table, you never have to use a statement like the first INSERT again, only statements like the other two. Now the MySQL database has the information needed by Postfix to recognise that you have three virtual mail domains (namely the three domains in the VALUES section) for which it hosts virtual mailboxes. Postfix cannot read this information yet, but that'll be taken care of in the next section. Whle still within the mysql client, we can now create users: mysql> INSERT INTO virtual_users (id, domain_id, user, passwd) VALUES (1, 1, 'jan', MD5('JanSecret')); mysql> INSERT INTO virtual_users (domain_id, user, passwd) VALUES (1, 'mike', MD5('MikeSecret')); mysql> INSERT INTO virtual_users (domain_id, user, passwd) VALUES (3, 'shopkeeper', MD5('ShopSecret')); This has the effect of creating three users "jan" (in domain saruman.biz), "mike" (in domain saruman.biz) and "shopkeeper" (in domain shop.saruman.biz). Again, the ''id'' value is only ever needed in the first statement, because from now on every user addition will auto-increment ''id''. The passwords shown are encrypted with MD5, and put in the ''passwd'' field. Later on, the users will be able to access their mailboxes using this password; we won't tell Postfix anything about them, because it doesn't need the passwords. You can check the content of the ''virtual_users'' table with the right "select" statement, and you can now also see that the view ''view-users'' works: mysql> select * from virtual_users; mysql> select * from view_users; Should you need to update a user's password from the command line, you can use the following command, provided you've looked up that user's ''id'' : UPDATE virtual_users set passwd = MD5('<password>') WHERE id = '<id>'; Next up, we're going to add some aliases, which are alternative e-mail addresses for the users; their primary e-mail address can already be seen in the ''view_users'' view, but perhaps you also want mail to "webmaster@shop.saruman.biz" to arrive at one or more mailboxes, e.g. in the mailbox for user "shopkeeper" (within domain "shop.saruman.biz") and this guy's home address ("j.doe@example.com"). Furthermore, we'll define catchall-addresses for all domains, that'll send all mail for which no mailbox can be found to the mailbox of user Mike (for the first two domains) and Webmaster (for shop.saruman.biz; Webmaster himself is an alias yet again, that points to shopkeeper@shop.saruman.biz). To create the catchall, leave out a value for the source address. This creates the empty value for source that will be expanded (using source@domain) to "@domain". mysql> INSERT INTO virtual_aliases (id, domain_id, source, destination) VALUES (1, 2, 'webmaster', 'shopkeeper@shop.saruman.biz'); mysql> INSERT INTO virtual_aliases (domain_id, source, destination) VALUES (2, 'webmaster', 'j.doe@example.com'); mysql> INSERT INTO virtual_aliases (domain_id, destination) VALUES (1, 'mike@saruman.biz'); mysql> INSERT INTO virtual_aliases (domain_id, destination) VALUES (2, 'mike@saruman.biz'); mysql> INSERT INTO virtual_aliases (domain_id, destination) VALUES (3, 'webmaster@saruman.biz'); Again, we don't need to add the ''id'' value any more after the first ever insertion into this table. We can check the result by running a select statement against the ''virtual_aliases'' table and ''view_aliases'' view: mysql> select * from virtual_aliases; mysql> select * from view_aliases; == Postfix configuration for MySQL lookups== Next, we're going to tell Postfix to use the ''vmail'' database, and also how to read the database (Postfix never writes the MySQL database). To this end, we're going to create three configuration files in directory ''/etc/postfix''. We'll start off with one configuration file, with which Postfix can determine if a domain name is among the domain(s) that it's actually hosting mailboxes for. Then we'll create the config file that checks the table that contains all the users that have a virtual mailbox, and finally we create the lookup for the table with all the aliases. ===Virtual mail domains lookup=== Create file ''/etc/postfix/mysql-virtual-domains.cf'' with the following content: user = vmail_admin password = SuperSecret hosts = 127.0.0.1 dbname = vmail query = SELECT 1 FROM virtual_domains WHERE vdomain='%s' Next, we tell postfix to check this configuration file when it needs to check "virtual_mailbox_domains": postconf -e virtual_mailbox_domains=mysql:/etc/postfix/mysql-virtual-domains.cf Use of this configuration file in postfix has the effect of returning "yes" when checking our database for the domain part of an email address. Naturally, this configuration file has to be fitted with the actual ''vmail_admin'' password rather than our example "SuperSecret". === Virtual mail user lookup=== Create the file ''/etc/postfix/mysql-virtual-mailbox-maps.cf'' with the following content: user = vmail_admin password = SuperSecret hosts = 127.0.0.1 dbname = vmail query = SELECT 1 FROM view_users WHERE email='%s' Next, we tell Postfix that this mapping file is supposed to be used for the ''virtual_mailbox_maps'' mapping: postconf -e virtual_mailbox_maps=mysql:/etc/postfix/mysql-virtual-mailbox-maps.cf The lookup of virtual mailboxes should work with the data we've put into the database previously. i.e. postmap -q jan@saruman.biz mysql:/etc/postfix/mysql-virtual-mailbox-maps.cf should return a '''1''' to acknowledge that "jan@saruman.biz" is indeed a virtual mailbox in our Postfix configuration. === Virtual alias lookup=== Create another cf file at ''/etc/postfix/mysql-virtual-alias-maps.cf'': user = vmail_admin password = SuperSecret hosts = 127.0.0.1 dbname = vmail query = SELECT destination FROM view_aliases WHERE email='%s' And create yet another cf file at ''/etc/postfix/mysql-email2email.cf'': user = vmail_admin password = SuperSecret hosts = 127.0.0.1 dbname = vmail query = SELECT email FROM view_users WHERE email='%s' Again, we tell Postfix that this mapping file is supposed to be used for the ''virtual_alias_maps'' mapping: postconf -e virtual_alias_maps=mysql:/etc/postfix/mysql-virtual-alias-maps.cf,mysql:/etc/postfix/mysql-email2email.cf The lookup of virtual aliases should now work as designed: postmap -q shopkeeper@shop.saruman.biz mysql:/etc/postfix/mysql-virtual-alias-maps.cf postmap -q webmaster@shop.saruman.biz mysql:/etc/postfix/mysql-virtual-alias-maps.cf If you've put in the data from the previous section, then both commands should return the same result: ''shopkeeper@saruman.biz''. This shows that Postfix will deliver mail to shopkeeper or to webmaster to the mailbox of shopkeeper. ===Finishing up configuration files=== When everything works as planned, then we secure the configuration files against prying eyes. Remember, the configuration files contain the user/password combination which which to access the ''vmail'' SQL database. The ''vmail_admin'' user has only read rights, and passwords in there are encrypted, but nevertheless, this is information we need to protect. Thus: chown root:postfix /etc/postfix/mysql-*.cf chmod u=rw,g=r,o= /etc/postfix/mysql-*.cf This protects all four configuration files since only root can write them, members of group ''postfix'' can read them, and the rest of the world cannot access them at all. ==Configuring mail delivery through Dovecot LDA== E-mails get delivered to the virtual mailboxes by means of a Mail Delivery Agent (MDA). With Postfix, the standard MDA for delivery to virtual mailboxes is called ''virtual'', but we're not going to use that; we're going to use ''[http://wiki.dovecot.org/LDA Dovecot LDA]'', which is a program called ''deliver''. By the way, the abbreviation LDA stands for Local Delivery Agent, which of course means more or less the same as MDA. ===Enabling the Dovecot daemon=== To make Postfix use Dovecot LDA, we add the following line to ''/etc/postfix/master.cf'': dovecot unix - n n - - pipe flags=DRhu user=vmail:vmail argv=/usr/lib/dovecot/deliver -d ${recipient} This declares the service "dovecot" to mean using the program ''/usr/lib/dovecot/deliver'' with the right parameters. If we now let Postfix reload its files, it'll learn about this new service. Subsequently we can instruct Postfix to start using it, by declaring service "dovecot" to be the virtual transport of choice, and specifying one Dovecot-specific variable: postfix reload postconf -e virtual_transport=dovecot postconf -e dovecot_destination_recipient_limit=1 ===Dovecot default configuration=== Now to configure Dovecot itself: open ''/etc/dovecot/dovecot.conf'' with your favourite editor [[vim]]; first make sure the ''protocols ='' line reads protocols = imap imaps pop3 pop3s (which it should by default). The second setting is quite crucial. By default, the location of the mail directories is found automatically by Dovecot, but here that won't work. Find the line that reads ''#mail_location ='', and change it to mail_location = maildir:/data/vmail/%d/%n/Maildir This will look for mail in directory ''/data/vmail/'''DOMAIN'''/'''USER'''/Maildir'', and expect this directory to be in "maildir" format. Next look for a section called "auth default". First define the allowed authentication mechanisms: mechanisms = plain login Then inside that same section you need to uncomment: passdb sql { args = /etc/dovecot/dovecot-sql.conf } which tells Dovecot that the passwords are stored in an SQL database (it's obvious that we'll now have to create this conf-file) and: userdb static { args = uid=120 gid=120 home=/data/vmail/%d/%n allow_all_users=yes } to tell Dovecot where the mailboxes are located. This is similar to the ''mail_location'' setting. Next task: comment out the section ''passdb pam'', so that Dovecot doesn't accidentally try to service local users as well. Next up: tell Dovecot to handle IMAP the same as previous versions of this virtual mailserver have - this can prove to be quite tricky if you already have mailboxes full of mail, put there by e.g. Courier-IMAP. What works for us, is namespace private { separator = . prefix = inbox = yes } However, your mileage may vary. You'll also want to comment out the ''passdb pam'' sections, since we're not hosting mail for local users. Next up, we'll edit the section ''socket listen'' so that Dovecot can access the user database (master section), and our Postfix mailserver can access Dovecot (client section): socket listen { master { path = /var/run/dovecot/auth-master mode = 0600 user = vmail } client { path = /var/spool/postfix/private/auth mode = 0660 user = postfix group = postfix } } Finally, the protocol section, where we specify log files, an address to put in mails when we send out nondelivery reports, and a place to store scripts: protocol lda { log_path = /var/log/appslog/mail/dovecot-deliver.log auth_socket_path = /var/run/dovecot/auth-master postmaster_address = postmaster@saruman.biz mail_plugins = cmusieve global_script_path = /data/vmail/globalsieverc } You could change the log path to "log_path =" With a empty logpath syslog will log the events. Now that we've finished the Dovecot configuration file, we need to create a fitting MySQL configuration file for Dovecot. The file is ''/etc/dovecot/dovecot-sql.conf'', and its contents are driver = mysql connect = host=127.0.0.1 dbname=vmail user=vmail_admin password=SuperSecret default_pass_scheme = PLAIN-MD5 password_query = SELECT email as user, passwd as password FROM view_users WHERE email='%u'; When you've created this file (as root), change the attributes of ''dovecot-sql.conf'' and ''dovecot.conf'', and then restart Dovecot to start using the new configuration. Note: ''dovecot.conf'' needs to be read by Postfix, hence the group ownership for the file. chmod u=rw,g=,o= /etc/dovecot/dovecot-sql.conf chgrp vmail /etc/dovecot/dovecot.conf chmod u=rw,g=r,o= /etc/dovecot/dovecot.conf /etc/init.d/dovecot restart To get some more logging in the case something goes wrong. Uncomment the folling and change to yes. auth_verbose = yes auth_debug = yes auth_debug_passwords = yes ===Dovecot SSL configuration=== Out of the (Debian) box, Dovecot is SSL-enabled. We'll now replace the generic SSL-certificate, generated for the host by the Dovecot installation script, by our own certificate. To ths end, we first [[Creating_digital_certificates_with_our_root_certificate | generate an appropriate certificate]], e.g. an SSL wildcard certificate: "*.saruman.biz". This results in a public and a private certificate, both of which must be placed somewhere where Dovecot expects them and can read them. By default, Dovecot expects the following locations/filenames/owner/attributes: /etc/ssl/certs/dovecot.pem -rw-r--r-- root:dovecot 4624 bytes /etc/ssl/private/dovecot.pem -rw------- root:dovecot 1743 bytes If we may make a suggestion: rename the generated certificates in both locations to dovecot.pem.bak, place your generated certificates in their place, and set the owner/permissions like displayed here. However, if you've generated your own keys, you might have used a passphrase on the private key. You'll have to tell dovecot about it in its configuration file /etc/dovecot/dovecot.conf. To this end, edit the corresponding section by uncommenting the "ssl_" lines, and using your private key password (e.g. "zM7Ertq12") in the appropriate line: ssl_cert_file = /etc/ssl/certs/dovecot.pem ssl_key_file = /etc/ssl/private/dovecot.pem # If key file is password protected, give the password here. Alternatively # give it when starting dovecot with -p parameter. ssl_key_password = zM7Ertq12 Naturally you are free to place the keys in a different location, and/or use a different name... ==Finishing up== This is a good moment to test your configuration, if you haven't been able to test your work inbetween. If everything works as expected, you can add bells and whistles to your configuration. ===''smtpd'' TLS encryption=== The first addition we'd like to present covers the way Postfix handles incoming connections. Since authentication works, we can have Postfix distrust every (unauthenticated) connection: postconf -e mynetworks= Furthermore, since a default SSL certificate is installed by the Debian Postfix installation routine, we can encrypt all our connections using TLS; we enforce this using postconf -e smtpd_use_tls=yes postconf -e smtpd_tls_auth_only=yes Of course, you need to adjust the settings of your IMAP client so that it properly uses TLS and properly authenticates itself. If TLS works, you'll probably want to change the certificate as you have for Dovecot in the previous section. This is again pretty easy. If you haven't yet, now is the time to [[Creating_digital_certificates_with_our_root_certificate | creating that custom SSL certificate]] for our mail server - but you have to make sure that you DON'T use a password on the private key. Unlike Dovecot, Postfix cannot be told the password to the private key somewhere. For starters, look at the TLS-section of your ''main.cf'' that you currently have. Chances are a big chunk of it looks like this: # TLS parameters smtpd_tls_cert_file=/etc/ssl/certs/ssl-cert-snakeoil.pem smtpd_tls_key_file=/etc/ssl/private/ssl-cert-snakeoil.key smtpd_use_tls=yes Now all you need to do is replace the name of the snakeoil-keys with those of appropriate ssl-certificates, the private key of which needs to be NOT passphrase-protected. For this you could copy the Dovecot certificates, if you strip that passphrase in the manner described in the [[Creating_digital_certificates_with_our_root_certificate#Creating_an_SSL_certificate | SSL certificate section]]. The ''main.cf'' then would become: # TLS parameters smtpd_tls_cert_file=/etc/ssl/certs/postfix.pem smtpd_tls_key_file=/etc/ssl/private/postfix.key smtpd_use_tls=yes Restart Postfix, and presto. === Other additions === If everything ''still'' works after these changes, then congratulations, you now have a powerful, flexible and pretty secure mail setup. Of course, there are always points for improvements. We'll cover these in separate pages. One page that we want to direct you to now, is * [[Antispam measures]] for our Postfix mailserver 25198d3cafe2440619166f5de40a48ebdc9141ca 0 1487 3085 2364 2016-02-22T12:06:31Z Saruman! 2 /* Deciding on CA parameters */ wikitext text/x-wiki ==Certificates, an introduction== Digital certificates are an extremely important means to identify identities (of users, as well as of servers) on the Internet, or indeed on most any network. For instance, we use them to encrypt network traffic when we use the HTTPS protocol. Thus, we really need certificates. Now, as [http://www.debian-administration.org/articles/618 this article] explains, you can either buy your certificates from a certificate authority like [http://www.verisign.com/ VeriSign], [http://www.thawte.com/ Thawte] or [http://www.equifaxsecure.co.uk/index.html Equifax Secure], but these certificates cost more than a couple of Euro's, and also need to be renewed (usually every year). So the other route, the one we'll be taking, is to create our own Certificate Authority (CA), and use that to sign certificates for our needs (secure webserver, secure mailserver etcetera). Now, "creating a CA" sounds like grave installation and configuration work, but in fact a CA does not have to be an actual service, demon or program. A CA is more like a concept, at the heart of which lies the CA "root certificate". So if we obtain a little set of tools and generate our own root certificate, then we're in business. ==Creating the Certificate Authority (CA) - preparations== To generate the root CA for our own little organization, we first need tools. These tools under Debian come with the OpenSSL software - which you'll usually find already installed. Now to generate the CA root certificate, we'll use a shell script from the OpenSSL package: ''/usr/lib/ssl/misc/CA.sh'', which together with the configuration file ''/etc/ssl/openssl.cnf'' can create our CA root certificate. To that end, we'll first need to decide on some parameters. ===Deciding on CA parameters=== '''How strong''' do we want our root certificate? 1024 bits is the default, but the stronger, the better. We suggest 4096 bits - not because 2048 isn't sufficient (even 1024 is still very very good, even in the year 2016), but because it's not necessary to keep a CA's key length very low, and 4096 can be expected to remain pretty secure until after 2030 (see [http://danielpocock.com/rsa-key-sizes-2048-or-4096-bits here]). How long should our '''CA root certificate remain valid'''? The longer, the more convenient - but maybe some day in the future, you feel you don't want certificates from ten years earlies to wander around, expired but otherwise valid. Expiry of the root certificate that goes along with that certificate might help you. So what's an appropriate time for your root CA? That depends. For our home CA, we use 15 years. For a business, the cost of providing new root certificates to all computers, employees, and maybe customers, can be so high that you'd rather have 25 years - or maybe security is paramount, and 5 years is long enough for you. We can't say - but our home CA's use 15 years, because we feel that that's a nice intermediate value. 15 years, including about 4 leap days, comes to 5479 days. '''Where do we want to store''' our CA root certificate? By default, the ''CA.sh'' script feels it must store all generated certificates in ''./demoCA''. That's not very handy for us. We rather have a central location like ''/etc/ssl/ca'' on our central server. How long should '''any generated certificate be valid'''? The default value that the ''CA.sh'' script provides is one year. We find that enough - although we add 7 days to accomodate some overlap when having to regenerate the certificate upon nearing the expiry date (note: we really want to replace certificates ''prior'' to expiry :-) '''What "company" data''' will we enter in the certificate? Several fields must be entered, some of which you could fill out at will. However, it's not exactly clear why you would want to confuse people trying to authenticate you, your webserver or some other connection by filling out, for example, the country with an incorrect or even non-existent code. On the other hand, you can keep your own privacy in mind, and not fill in your full name, but rather your website's name, at the "common name" section of your CA root certificate. Again, this depends on what you're going to use your CA for. We at [https://www.saruman.biz saruman.biz] decided to use the following values: * Organization name: Saruman.biz. We're private persons, not companies, but we want to maintain a minimum of privacy, so we've put this fake entity name here. * Province: Utrecht. Yep, that's a province in the Netherlands, and we live pretty close to it. * Country: NL (that's the Netherlands) Maybe you want to provide more default information to your CA setup; just look further down on how to. So the information we've decided upon is like this: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Parameter !style="background:#ffdead;"|value |- |root certificate encryption |4096 bits |- |root certificate validity |5479 days (15 years) |- |certificate store |''/etc/ssl/ca'' |- |default certificate validity |370 days (1 year) |- |Organization name |Saruman.biz |- |Certificate province/county name (default) |Utrecht |- |Certificate country name (default) |NL |- |} === Editing the ''CA.sh'' script === Actually, you don't need to use the ''CA.sh'' shell script. There's also a ''CA.pl'' perl script. However, if you're more into shell scripting than perl programming, go for the shell script. Now edit ''/usr/lib/ssl/misc/CA.sh''; find the two lines near the top that define the variables ''DAYS'' and ''CADAYS'', and set these to what we want them to be. A little further down, we find the default location ''CATOP=./demoCA''. Change this (relative) path to the (absolute) path we've decided upon. Then, a lot further down, we find the line that's responsible for creating the CA root certificate itself, it's the line that goes ''$REQ -new -keyout ${CATOP}/private/$CAKEY -out ${CATOP}/$CAREQ'' (well actually it's split out over two lines). Here, right after ''-new'' we add ''-newkey rsa:2048''. With all these changes, the three relevant sections in ''CA.sh'' will be changed to something like this: <source lang="bash"> DAYS="-days 370" # 1 year CADAYS="-days 5479" # 15 years ... CATOP=/etc/ssl/ca ... echo "Making CA certificate ..." $REQ -new -newkey rsa:2048 -keyout ${CATOP}/private/$CAKEY \ -out ${CATOP}/$CAREQ </source> === Editing the ''openssl.cnf'' configuration file=== When generating certificates, the OpenSSL tools check the configuration file ''/etc/ssl/openssl.cnf''. It is necessary to match the parameters in there with the choices and changes of the previous sections, and also it's handy to change some of the default parameters that certificates require upon generation. It's important to remember that these parameters will be asked every time you generate a certificate, but it's ofcourse pretty handy if the default value is set for your situation, so you can just hit that big &lt;enter> key. First up, we'll change the ''dir'' variable in section ''[ CA_default ]'' to match the dir from the ''CA.sh'' script. Then we find ''default_days'' and change it to our default certificate lifetime: 370 days. Furthermore, we find the certificate strengt in the ''[ req ]'' section; we can change it to our preferred value of 2048 bits. Now we can put in the optional bits: the default values. Not necessary, but handy. We go to section ''[ req_distinguished_name ]'' and fill them in. For this, we again use the table we've previously compounded. So the changes we've made will amount to something like this: [ CA_default ] dir = /etc/ssl/ca ... default_days = 370 ... [ req ] default_bits = 2048 ... [ req_distinguished_name ] 0.organizationName_default = Saruman.biz stateOrProvinceName_default = Utrecht countryName_default = NL Especially the last section is, again, a pretty arbitrary choice. You could choose not to provide customized default answers (in which case you're stuck with Internet Widgets Pty from Some-State, AU as the default answers). There are more default values in that section of the ''openssl.cnf'' configuration file; go in there and decide what you want. ==the Certificate Authority root certificate== Now with the basic information in place, we can go about generating the certificate itself, and putting it to use. Well, actually we're not going to generate ''one'' certificate, but ''two'': the public one, that we give out to anyone that might want to check the validity of any certificate that claims to have been issued by the Saruman.biz CA, and the private one, with which we can digitally sign certificates so as to prove that they're really issued by said Saruman.biz CA. This is also referred to as a "key pair". ===Creating the CA root certificate key pair=== To generate the CA's public and private root certificate, as root, execute /usr/lib/ssl/misc/CA.sh -newca With the defaults set as given above, you still get some questions. One is "CA certificate filename". This actually requests from you another certificate with which to sign the one we're creating. However, we're generating our root certificate, so we leave this empty and just hit &lt;enter>. Next question is for the PEM passphrase. Make that a strong passphrase or password, keep it very secret, and '''don't forget it!''' (and DON'T write it on a piece of paper; use something like [http://keepass.info keepass] to store your secret passwords). For the next set of questions, you probably have filled in some of the defaults. If you want to leave some entry blank, fill in a period ('''.'''). You'll have to provide the country code, province or state, locality (like city; Saruman.biz leaves this empty), Organization Name, Organizational Unit name (again, empty), and finally the Common Name. This last question is pretty important: the name you put in here is the name under which your CA will go for the next 15 years!! So don't put in a "funny" name, a bland name, or whatever. We put in "Saruman.biz Root CA", somewhat like official root CA's like "Equifax Secure Global eBusiness CA-1" or "Macao Post eSignTrust Root Certification Authority". The script also asks for an email address, which you may or may not provide, a challenge password, and an "optional company name", both of which you can leave blank because we're not sending a certificate signing request out to someone else, but signing it ourselves.<br> Having provided this information, we've actually already created one half of the key pair, namely the private key. It'll be ''/etc/openssl/ca/private/ca.pem'', and is protected by our chosen very strong password. However, we now need the public key, self-signed with the private key. The next step in our CA creation process thus ''again'' asks for the passphrase. Since this is the second step in a two-step process, we again put in the passphrase we've already provided. However, now the shellscript uses this to unlock the private key we've (already) created, and then use it to sign the public key we're now creating. However, the passphrase is ''all'' that it asks. It now generates a signing request (''/etc/openssl/ca/careq.pem''), then uses the private key to sign it, and then generate the public key, to be found in ''/etc/openssl/ca/cacert.pem''. You can remove ''careq.pem'' after you've inspected the ''cacert.pem''. So now we've got two root certificates, namely '''private''' key ''/etc/openssl/ca/private/cakey.pem'' and '''public''' key ''/etc/openssl/ca/cacert.pem''. NEVER send your public key out to ANYONE! Protect that key, and its passphrase, with your life. If you lose the file, lose the passphrase, or the key gets compromised (lost to an unknown party) then you've got to replace your root certificates AND you'll have to re-issue ALL certificates that you've ever signed (we're not going into certificate revocation here). You can inspect your certificates (when you're in directory ''/etc/openssl/ca'') with commands like this: openssl x509 -in cacert.pem -noout -text openssl x509 -in cacert.pem -noout -dates openssl x509 -in cacert.pem -noout -purpose Note from the last command that this certificate is obviously a root certificate: it can sign everything but the kitchen sink. ===We've got the CA certificate, now what?=== With the root CA certificates available to us, we've got two things to do: * guard very carefully the public and (especially) the private key file * sign certificates for our own use The first means we've got to keep a copy of the private key file in some other, safe location, and we've got to secure the private key on the server where it sits - both the machine and the file. It might even be wise to remove the private key, and keep it on a USB stick, and only read it when signing certificates. The second thing means we've got to generate keys for SSL and TLS connections, just as we need them. This is covered in our [[Creating digital certificates with our root certificate | creating digital certificates]] section. 71412d53c189ee81659b867c48bb5a9689563011 3086 3085 2016-02-22T12:11:30Z Saruman! 2 /* Creating the Certificate Authority (CA) - preparations */ wikitext text/x-wiki ==Certificates, an introduction== Digital certificates are an extremely important means to identify identities (of users, as well as of servers) on the Internet, or indeed on most any network. For instance, we use them to encrypt network traffic when we use the HTTPS protocol. Thus, we really need certificates. Now, as [http://www.debian-administration.org/articles/618 this article] explains, you can either buy your certificates from a certificate authority like [http://www.verisign.com/ VeriSign], [http://www.thawte.com/ Thawte] or [http://www.equifaxsecure.co.uk/index.html Equifax Secure], but these certificates cost more than a couple of Euro's, and also need to be renewed (usually every year). So the other route, the one we'll be taking, is to create our own Certificate Authority (CA), and use that to sign certificates for our needs (secure webserver, secure mailserver etcetera). Now, "creating a CA" sounds like grave installation and configuration work, but in fact a CA does not have to be an actual service, demon or program. A CA is more like a concept, at the heart of which lies the CA "root certificate". So if we obtain a little set of tools and generate our own root certificate, then we're in business. ==Creating the Certificate Authority (CA) - preparations== To generate the root CA for our own little organization, we first need tools. These tools under Debian come with the OpenSSL software - which you'll usually find already installed (if not, run ''apt-get install openssl''). Now to generate the CA root certificate, we'll use a shell script from the OpenSSL package: ''/usr/lib/ssl/misc/CA.sh'', which together with the configuration file ''/etc/ssl/openssl.cnf'' can create our CA root certificate. To that end, we'll first need to decide on some parameters. ===Deciding on CA parameters=== '''How strong''' do we want our root certificate? 1024 bits is the default, but the stronger, the better. We suggest 4096 bits - not because 2048 isn't sufficient (even 1024 is still very very good, even in the year 2016), but because it's not necessary to keep a CA's key length very low, and 4096 can be expected to remain pretty secure until after 2030 (see [http://danielpocock.com/rsa-key-sizes-2048-or-4096-bits here]). How long should our '''CA root certificate remain valid'''? The longer, the more convenient - but maybe some day in the future, you feel you don't want certificates from ten years earlies to wander around, expired but otherwise valid. Expiry of the root certificate that goes along with that certificate might help you. So what's an appropriate time for your root CA? That depends. For our home CA, we use 15 years. For a business, the cost of providing new root certificates to all computers, employees, and maybe customers, can be so high that you'd rather have 25 years - or maybe security is paramount, and 5 years is long enough for you. We can't say - but our home CA's use 15 years, because we feel that that's a nice intermediate value. 15 years, including about 4 leap days, comes to 5479 days. '''Where do we want to store''' our CA root certificate? By default, the ''CA.sh'' script feels it must store all generated certificates in ''./demoCA''. That's not very handy for us. We rather have a central location like ''/etc/ssl/ca'' on our central server. How long should '''any generated certificate be valid'''? The default value that the ''CA.sh'' script provides is one year. We find that enough - although we add 7 days to accommodate some overlap when having to regenerate the certificate upon nearing the expiry date (note: we really want to replace certificates ''prior'' to expiry :-) '''What "company" data''' will we enter in the certificate? Several fields must be entered, some of which you could fill out at will. However, it's not exactly clear why you would want to confuse people trying to authenticate you, your webserver or some other connection by filling out, for example, the country with an incorrect or even non-existent code. On the other hand, you can keep your own privacy in mind, and not fill in your full name, but rather your website's name, at the "common name" section of your CA root certificate. Again, this depends on what you're going to use your CA for. We at [https://www.saruman.biz saruman.biz] decided to use the following values: * Organization name: Saruman.biz. We're private persons, not companies, but we want to maintain a minimum of privacy, so we've put this fake entity name here. * Province: Utrecht. Yep, that's a province in the Netherlands, and we live pretty close to it. * Country: NL (that's the Netherlands) Maybe you want to provide more default information to your CA setup; just look further down on how to. So the information we've decided upon is like this: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Parameter !style="background:#ffdead;"|value |- |root certificate encryption |4096 bits |- |root certificate validity |5479 days (15 years) |- |certificate store |''/etc/ssl/ca'' |- |default certificate validity |370 days (1 year) |- |Organization name |Saruman.biz |- |Certificate province/county name (default) |Utrecht |- |Certificate country name (default) |NL |- |} === Editing the ''CA.sh'' script === Actually, you don't need to use the ''CA.sh'' shell script. There's also a ''CA.pl'' perl script. However, if you're more into shell scripting than perl programming, go for the shell script. Now edit ''/usr/lib/ssl/misc/CA.sh''; find the two lines near the top that define the variables ''DAYS'' and ''CADAYS'', and set these to what we want them to be. A little further down, we find the default location ''CATOP=./demoCA''. Change this (relative) path to the (absolute) path we've decided upon. Then, a lot further down, we find the line that's responsible for creating the CA root certificate itself, it's the line that goes ''$REQ -new -keyout ${CATOP}/private/$CAKEY -out ${CATOP}/$CAREQ'' (well actually it's split out over two lines). Here, right after ''-new'' we add ''-newkey rsa:2048''. With all these changes, the three relevant sections in ''CA.sh'' will be changed to something like this: <source lang="bash"> DAYS="-days 370" # 1 year CADAYS="-days 5479" # 15 years ... CATOP=/etc/ssl/ca ... echo "Making CA certificate ..." $REQ -new -newkey rsa:2048 -keyout ${CATOP}/private/$CAKEY \ -out ${CATOP}/$CAREQ </source> === Editing the ''openssl.cnf'' configuration file=== When generating certificates, the OpenSSL tools check the configuration file ''/etc/ssl/openssl.cnf''. It is necessary to match the parameters in there with the choices and changes of the previous sections, and also it's handy to change some of the default parameters that certificates require upon generation. It's important to remember that these parameters will be asked every time you generate a certificate, but it's ofcourse pretty handy if the default value is set for your situation, so you can just hit that big &lt;enter> key. First up, we'll change the ''dir'' variable in section ''[ CA_default ]'' to match the dir from the ''CA.sh'' script. Then we find ''default_days'' and change it to our default certificate lifetime: 370 days. Furthermore, we find the certificate strengt in the ''[ req ]'' section; we can change it to our preferred value of 2048 bits. Now we can put in the optional bits: the default values. Not necessary, but handy. We go to section ''[ req_distinguished_name ]'' and fill them in. For this, we again use the table we've previously compounded. So the changes we've made will amount to something like this: [ CA_default ] dir = /etc/ssl/ca ... default_days = 370 ... [ req ] default_bits = 2048 ... [ req_distinguished_name ] 0.organizationName_default = Saruman.biz stateOrProvinceName_default = Utrecht countryName_default = NL Especially the last section is, again, a pretty arbitrary choice. You could choose not to provide customized default answers (in which case you're stuck with Internet Widgets Pty from Some-State, AU as the default answers). There are more default values in that section of the ''openssl.cnf'' configuration file; go in there and decide what you want. ==the Certificate Authority root certificate== Now with the basic information in place, we can go about generating the certificate itself, and putting it to use. Well, actually we're not going to generate ''one'' certificate, but ''two'': the public one, that we give out to anyone that might want to check the validity of any certificate that claims to have been issued by the Saruman.biz CA, and the private one, with which we can digitally sign certificates so as to prove that they're really issued by said Saruman.biz CA. This is also referred to as a "key pair". ===Creating the CA root certificate key pair=== To generate the CA's public and private root certificate, as root, execute /usr/lib/ssl/misc/CA.sh -newca With the defaults set as given above, you still get some questions. One is "CA certificate filename". This actually requests from you another certificate with which to sign the one we're creating. However, we're generating our root certificate, so we leave this empty and just hit &lt;enter>. Next question is for the PEM passphrase. Make that a strong passphrase or password, keep it very secret, and '''don't forget it!''' (and DON'T write it on a piece of paper; use something like [http://keepass.info keepass] to store your secret passwords). For the next set of questions, you probably have filled in some of the defaults. If you want to leave some entry blank, fill in a period ('''.'''). You'll have to provide the country code, province or state, locality (like city; Saruman.biz leaves this empty), Organization Name, Organizational Unit name (again, empty), and finally the Common Name. This last question is pretty important: the name you put in here is the name under which your CA will go for the next 15 years!! So don't put in a "funny" name, a bland name, or whatever. We put in "Saruman.biz Root CA", somewhat like official root CA's like "Equifax Secure Global eBusiness CA-1" or "Macao Post eSignTrust Root Certification Authority". The script also asks for an email address, which you may or may not provide, a challenge password, and an "optional company name", both of which you can leave blank because we're not sending a certificate signing request out to someone else, but signing it ourselves.<br> Having provided this information, we've actually already created one half of the key pair, namely the private key. It'll be ''/etc/openssl/ca/private/ca.pem'', and is protected by our chosen very strong password. However, we now need the public key, self-signed with the private key. The next step in our CA creation process thus ''again'' asks for the passphrase. Since this is the second step in a two-step process, we again put in the passphrase we've already provided. However, now the shellscript uses this to unlock the private key we've (already) created, and then use it to sign the public key we're now creating. However, the passphrase is ''all'' that it asks. It now generates a signing request (''/etc/openssl/ca/careq.pem''), then uses the private key to sign it, and then generate the public key, to be found in ''/etc/openssl/ca/cacert.pem''. You can remove ''careq.pem'' after you've inspected the ''cacert.pem''. So now we've got two root certificates, namely '''private''' key ''/etc/openssl/ca/private/cakey.pem'' and '''public''' key ''/etc/openssl/ca/cacert.pem''. NEVER send your public key out to ANYONE! Protect that key, and its passphrase, with your life. If you lose the file, lose the passphrase, or the key gets compromised (lost to an unknown party) then you've got to replace your root certificates AND you'll have to re-issue ALL certificates that you've ever signed (we're not going into certificate revocation here). You can inspect your certificates (when you're in directory ''/etc/openssl/ca'') with commands like this: openssl x509 -in cacert.pem -noout -text openssl x509 -in cacert.pem -noout -dates openssl x509 -in cacert.pem -noout -purpose Note from the last command that this certificate is obviously a root certificate: it can sign everything but the kitchen sink. ===We've got the CA certificate, now what?=== With the root CA certificates available to us, we've got two things to do: * guard very carefully the public and (especially) the private key file * sign certificates for our own use The first means we've got to keep a copy of the private key file in some other, safe location, and we've got to secure the private key on the server where it sits - both the machine and the file. It might even be wise to remove the private key, and keep it on a USB stick, and only read it when signing certificates. The second thing means we've got to generate keys for SSL and TLS connections, just as we need them. This is covered in our [[Creating digital certificates with our root certificate | creating digital certificates]] section. 6ba2cce0d3b79943cff1e189045c01d5bae1b14e 3087 3086 2016-02-23T09:02:29Z Saruman! 2 /* Deciding on CA parameters */ wikitext text/x-wiki ==Certificates, an introduction== Digital certificates are an extremely important means to identify identities (of users, as well as of servers) on the Internet, or indeed on most any network. For instance, we use them to encrypt network traffic when we use the HTTPS protocol. Thus, we really need certificates. Now, as [http://www.debian-administration.org/articles/618 this article] explains, you can either buy your certificates from a certificate authority like [http://www.verisign.com/ VeriSign], [http://www.thawte.com/ Thawte] or [http://www.equifaxsecure.co.uk/index.html Equifax Secure], but these certificates cost more than a couple of Euro's, and also need to be renewed (usually every year). So the other route, the one we'll be taking, is to create our own Certificate Authority (CA), and use that to sign certificates for our needs (secure webserver, secure mailserver etcetera). Now, "creating a CA" sounds like grave installation and configuration work, but in fact a CA does not have to be an actual service, demon or program. A CA is more like a concept, at the heart of which lies the CA "root certificate". So if we obtain a little set of tools and generate our own root certificate, then we're in business. ==Creating the Certificate Authority (CA) - preparations== To generate the root CA for our own little organization, we first need tools. These tools under Debian come with the OpenSSL software - which you'll usually find already installed (if not, run ''apt-get install openssl''). Now to generate the CA root certificate, we'll use a shell script from the OpenSSL package: ''/usr/lib/ssl/misc/CA.sh'', which together with the configuration file ''/etc/ssl/openssl.cnf'' can create our CA root certificate. To that end, we'll first need to decide on some parameters. ===Deciding on CA parameters=== '''How strong''' do we want our root certificate? 1024 bits is the default, but the stronger, the better. We suggest 4096 bits - not because 2048 isn't sufficient (even 1024 is still very very good, even in the year 2016), but because it's not necessary to keep a CA's key length very low, and 4096 can be expected to remain pretty secure until after 2030 (see [http://danielpocock.com/rsa-key-sizes-2048-or-4096-bits here]). How long should our '''CA root certificate remain valid'''? The longer, the more convenient - but maybe some day in the future, you feel you don't want certificates issued ten years ago to just lie around, expired but otherwise valid. Expiry of the root certificate that goes along with that certificate might help you. So what's an appropriate time for your root CA? That depends. For our home CA, we use 15 years. For a business, the cost of providing new root certificates to all computers, employees, and maybe customers, can be so high that you'd rather have 25 years - or maybe security is paramount, and 5 years is long enough for you. We can't say - but our home CA's use 15 years, because we feel that that's a nice intermediate value. 15 years, including about 4 leap days, comes to 5479 days. '''Where do we want to store''' our CA root certificate? By default, the ''CA.sh'' script feels it must store all generated certificates in ''./demoCA''. That's not very handy for us. We rather have a central location like ''/etc/ssl/ca'' on our home server. Yes, it's sound advice to keep the root certificate on an offline machine and all that, but this is for a self-signed certificate, and if this particular directory gets compromised, then so is the whole home server, and we've got greater issues than the loss of a self-signed private key. How long should '''any generated certificate be valid'''? The default value that the ''CA.sh'' script provides is one year. We find that enough - although we add 7 days to accommodate some overlap when having to regenerate the certificate upon nearing the expiry date (note: we really want to replace certificates ''prior'' to expiry :-) '''What "company" data''' will we enter in the certificate? Several fields must be entered, some of which you could fill out at will. However, it's not exactly clear why you would want to confuse people trying to authenticate you, your webserver or some other connection by filling out, for example, the country with an incorrect or even non-existent code. On the other hand, you can keep your own privacy in mind, and not fill in your full name, but rather your website's name, at the "common name" section of your CA root certificate. Again, this depends on what you're going to use your CA for. We at [https://www.saruman.biz saruman.biz] decided to use the following values: * Organization name: Saruman.biz. We're private persons, not companies, but we want to maintain a minimum of privacy, so we've put this fake entity name here. * Country: NL (that's the Netherlands) * Province: Utrecht. Yep, that's a province in the Netherlands, and I happen to live in it. Maybe you want to provide more default information to your CA setup; just look further down on how to. So the information we've decided upon is like this: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Parameter !style="background:#ffdead;"|value |- |root certificate encryption |4096 bits |- |root certificate validity |5479 days (15 years) |- |certificate store |''/etc/ssl/ca'' |- |default certificate validity |370 days (1 year) |- |Organization name |Saruman.biz |- |Certificate province/county name (default) |Utrecht |- |Certificate country name (default) |NL |- |} === Editing the ''CA.sh'' script === Actually, you don't need to use the ''CA.sh'' shell script. There's also a ''CA.pl'' perl script. However, if you're more into shell scripting than perl programming, go for the shell script. Now edit ''/usr/lib/ssl/misc/CA.sh''; find the two lines near the top that define the variables ''DAYS'' and ''CADAYS'', and set these to what we want them to be. A little further down, we find the default location ''CATOP=./demoCA''. Change this (relative) path to the (absolute) path we've decided upon. Then, a lot further down, we find the line that's responsible for creating the CA root certificate itself, it's the line that goes ''$REQ -new -keyout ${CATOP}/private/$CAKEY -out ${CATOP}/$CAREQ'' (well actually it's split out over two lines). Here, right after ''-new'' we add ''-newkey rsa:2048''. With all these changes, the three relevant sections in ''CA.sh'' will be changed to something like this: <source lang="bash"> DAYS="-days 370" # 1 year CADAYS="-days 5479" # 15 years ... CATOP=/etc/ssl/ca ... echo "Making CA certificate ..." $REQ -new -newkey rsa:2048 -keyout ${CATOP}/private/$CAKEY \ -out ${CATOP}/$CAREQ </source> === Editing the ''openssl.cnf'' configuration file=== When generating certificates, the OpenSSL tools check the configuration file ''/etc/ssl/openssl.cnf''. It is necessary to match the parameters in there with the choices and changes of the previous sections, and also it's handy to change some of the default parameters that certificates require upon generation. It's important to remember that these parameters will be asked every time you generate a certificate, but it's ofcourse pretty handy if the default value is set for your situation, so you can just hit that big &lt;enter> key. First up, we'll change the ''dir'' variable in section ''[ CA_default ]'' to match the dir from the ''CA.sh'' script. Then we find ''default_days'' and change it to our default certificate lifetime: 370 days. Furthermore, we find the certificate strengt in the ''[ req ]'' section; we can change it to our preferred value of 2048 bits. Now we can put in the optional bits: the default values. Not necessary, but handy. We go to section ''[ req_distinguished_name ]'' and fill them in. For this, we again use the table we've previously compounded. So the changes we've made will amount to something like this: [ CA_default ] dir = /etc/ssl/ca ... default_days = 370 ... [ req ] default_bits = 2048 ... [ req_distinguished_name ] 0.organizationName_default = Saruman.biz stateOrProvinceName_default = Utrecht countryName_default = NL Especially the last section is, again, a pretty arbitrary choice. You could choose not to provide customized default answers (in which case you're stuck with Internet Widgets Pty from Some-State, AU as the default answers). There are more default values in that section of the ''openssl.cnf'' configuration file; go in there and decide what you want. ==the Certificate Authority root certificate== Now with the basic information in place, we can go about generating the certificate itself, and putting it to use. Well, actually we're not going to generate ''one'' certificate, but ''two'': the public one, that we give out to anyone that might want to check the validity of any certificate that claims to have been issued by the Saruman.biz CA, and the private one, with which we can digitally sign certificates so as to prove that they're really issued by said Saruman.biz CA. This is also referred to as a "key pair". ===Creating the CA root certificate key pair=== To generate the CA's public and private root certificate, as root, execute /usr/lib/ssl/misc/CA.sh -newca With the defaults set as given above, you still get some questions. One is "CA certificate filename". This actually requests from you another certificate with which to sign the one we're creating. However, we're generating our root certificate, so we leave this empty and just hit &lt;enter>. Next question is for the PEM passphrase. Make that a strong passphrase or password, keep it very secret, and '''don't forget it!''' (and DON'T write it on a piece of paper; use something like [http://keepass.info keepass] to store your secret passwords). For the next set of questions, you probably have filled in some of the defaults. If you want to leave some entry blank, fill in a period ('''.'''). You'll have to provide the country code, province or state, locality (like city; Saruman.biz leaves this empty), Organization Name, Organizational Unit name (again, empty), and finally the Common Name. This last question is pretty important: the name you put in here is the name under which your CA will go for the next 15 years!! So don't put in a "funny" name, a bland name, or whatever. We put in "Saruman.biz Root CA", somewhat like official root CA's like "Equifax Secure Global eBusiness CA-1" or "Macao Post eSignTrust Root Certification Authority". The script also asks for an email address, which you may or may not provide, a challenge password, and an "optional company name", both of which you can leave blank because we're not sending a certificate signing request out to someone else, but signing it ourselves.<br> Having provided this information, we've actually already created one half of the key pair, namely the private key. It'll be ''/etc/openssl/ca/private/ca.pem'', and is protected by our chosen very strong password. However, we now need the public key, self-signed with the private key. The next step in our CA creation process thus ''again'' asks for the passphrase. Since this is the second step in a two-step process, we again put in the passphrase we've already provided. However, now the shellscript uses this to unlock the private key we've (already) created, and then use it to sign the public key we're now creating. However, the passphrase is ''all'' that it asks. It now generates a signing request (''/etc/openssl/ca/careq.pem''), then uses the private key to sign it, and then generate the public key, to be found in ''/etc/openssl/ca/cacert.pem''. You can remove ''careq.pem'' after you've inspected the ''cacert.pem''. So now we've got two root certificates, namely '''private''' key ''/etc/openssl/ca/private/cakey.pem'' and '''public''' key ''/etc/openssl/ca/cacert.pem''. NEVER send your public key out to ANYONE! Protect that key, and its passphrase, with your life. If you lose the file, lose the passphrase, or the key gets compromised (lost to an unknown party) then you've got to replace your root certificates AND you'll have to re-issue ALL certificates that you've ever signed (we're not going into certificate revocation here). You can inspect your certificates (when you're in directory ''/etc/openssl/ca'') with commands like this: openssl x509 -in cacert.pem -noout -text openssl x509 -in cacert.pem -noout -dates openssl x509 -in cacert.pem -noout -purpose Note from the last command that this certificate is obviously a root certificate: it can sign everything but the kitchen sink. ===We've got the CA certificate, now what?=== With the root CA certificates available to us, we've got two things to do: * guard very carefully the public and (especially) the private key file * sign certificates for our own use The first means we've got to keep a copy of the private key file in some other, safe location, and we've got to secure the private key on the server where it sits - both the machine and the file. It might even be wise to remove the private key, and keep it on a USB stick, and only read it when signing certificates. The second thing means we've got to generate keys for SSL and TLS connections, just as we need them. This is covered in our [[Creating digital certificates with our root certificate | creating digital certificates]] section. ecbe81217000edb4f29f4a7bd89eef8fe696f1d2 3088 3087 2016-02-23T09:19:31Z Saruman! 2 /* Editing the CA.sh script */ wikitext text/x-wiki ==Certificates, an introduction== Digital certificates are an extremely important means to identify identities (of users, as well as of servers) on the Internet, or indeed on most any network. For instance, we use them to encrypt network traffic when we use the HTTPS protocol. Thus, we really need certificates. Now, as [http://www.debian-administration.org/articles/618 this article] explains, you can either buy your certificates from a certificate authority like [http://www.verisign.com/ VeriSign], [http://www.thawte.com/ Thawte] or [http://www.equifaxsecure.co.uk/index.html Equifax Secure], but these certificates cost more than a couple of Euro's, and also need to be renewed (usually every year). So the other route, the one we'll be taking, is to create our own Certificate Authority (CA), and use that to sign certificates for our needs (secure webserver, secure mailserver etcetera). Now, "creating a CA" sounds like grave installation and configuration work, but in fact a CA does not have to be an actual service, demon or program. A CA is more like a concept, at the heart of which lies the CA "root certificate". So if we obtain a little set of tools and generate our own root certificate, then we're in business. ==Creating the Certificate Authority (CA) - preparations== To generate the root CA for our own little organization, we first need tools. These tools under Debian come with the OpenSSL software - which you'll usually find already installed (if not, run ''apt-get install openssl''). Now to generate the CA root certificate, we'll use a shell script from the OpenSSL package: ''/usr/lib/ssl/misc/CA.sh'', which together with the configuration file ''/etc/ssl/openssl.cnf'' can create our CA root certificate. To that end, we'll first need to decide on some parameters. ===Deciding on CA parameters=== '''How strong''' do we want our root certificate? 1024 bits is the default, but the stronger, the better. We suggest 4096 bits - not because 2048 isn't sufficient (even 1024 is still very very good, even in the year 2016), but because it's not necessary to keep a CA's key length very low, and 4096 can be expected to remain pretty secure until after 2030 (see [http://danielpocock.com/rsa-key-sizes-2048-or-4096-bits here]). How long should our '''CA root certificate remain valid'''? The longer, the more convenient - but maybe some day in the future, you feel you don't want certificates issued ten years ago to just lie around, expired but otherwise valid. Expiry of the root certificate that goes along with that certificate might help you. So what's an appropriate time for your root CA? That depends. For our home CA, we use 15 years. For a business, the cost of providing new root certificates to all computers, employees, and maybe customers, can be so high that you'd rather have 25 years - or maybe security is paramount, and 5 years is long enough for you. We can't say - but our home CA's use 15 years, because we feel that that's a nice intermediate value. 15 years, including about 4 leap days, comes to 5479 days. '''Where do we want to store''' our CA root certificate? By default, the ''CA.sh'' script feels it must store all generated certificates in ''./demoCA''. That's not very handy for us. We rather have a central location like ''/etc/ssl/ca'' on our home server. Yes, it's sound advice to keep the root certificate on an offline machine and all that, but this is for a self-signed certificate, and if this particular directory gets compromised, then so is the whole home server, and we've got greater issues than the loss of a self-signed private key. How long should '''any generated certificate be valid'''? The default value that the ''CA.sh'' script provides is one year. We find that enough - although we add 7 days to accommodate some overlap when having to regenerate the certificate upon nearing the expiry date (note: we really want to replace certificates ''prior'' to expiry :-) '''What "company" data''' will we enter in the certificate? Several fields must be entered, some of which you could fill out at will. However, it's not exactly clear why you would want to confuse people trying to authenticate you, your webserver or some other connection by filling out, for example, the country with an incorrect or even non-existent code. On the other hand, you can keep your own privacy in mind, and not fill in your full name, but rather your website's name, at the "common name" section of your CA root certificate. Again, this depends on what you're going to use your CA for. We at [https://www.saruman.biz saruman.biz] decided to use the following values: * Organization name: Saruman.biz. We're private persons, not companies, but we want to maintain a minimum of privacy, so we've put this fake entity name here. * Country: NL (that's the Netherlands) * Province: Utrecht. Yep, that's a province in the Netherlands, and I happen to live in it. Maybe you want to provide more default information to your CA setup; just look further down on how to. So the information we've decided upon is like this: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Parameter !style="background:#ffdead;"|value |- |root certificate encryption |4096 bits |- |root certificate validity |5479 days (15 years) |- |certificate store |''/etc/ssl/ca'' |- |default certificate validity |370 days (1 year) |- |Organization name |Saruman.biz |- |Certificate province/county name (default) |Utrecht |- |Certificate country name (default) |NL |- |} === Editing the ''CA.sh'' script === Actually, you don't need to use the ''CA.sh'' shell script. There's also a ''CA.pl'' perl script. However, if you're more into shell scripting than perl programming, go for the shell script. Unfortunately, not everything we want to change is actually set from the ''openssl.conf'' file. So we edit ''/usr/lib/ssl/misc/CA.sh''; find the two lines near the top that define the variables ''DAYS'' and ''CADAYS'', and set these to what we want them to be. Then, a lot further down, we find the line that's responsible for creating the CA root certificate itself, it's the line that goes ''$REQ -new -keyout ${CATOP}/private/$CAKEY -out ${CATOP}/$CAREQ'' (well actually it's split out over two lines). Here, right after ''-new'' we add ''-newkey rsa:4096''. With all these changes, the three relevant sections in ''CA.sh'' will be changed to something like this: DAYS="-days 370" # 1 year CADAYS="-days 5479" # 15 years ... echo "Making CA certificate ..." $REQ -new -newkey rsa:4096 -keyout ${CATOP}/private/$CAKEY \ -out ${CATOP}/$CAREQ === Editing the ''openssl.cnf'' configuration file=== When generating certificates, the OpenSSL tools check the configuration file ''/etc/ssl/openssl.cnf''. It is necessary to match the parameters in there with the choices and changes of the previous sections, and also it's handy to change some of the default parameters that certificates require upon generation. It's important to remember that these parameters will be asked every time you generate a certificate, but it's ofcourse pretty handy if the default value is set for your situation, so you can just hit that big &lt;enter> key. First up, we'll change the ''dir'' variable in section ''[ CA_default ]'' to match the dir from the ''CA.sh'' script. Then we find ''default_days'' and change it to our default certificate lifetime: 370 days. Furthermore, we find the certificate strengt in the ''[ req ]'' section; we can change it to our preferred value of 2048 bits. Now we can put in the optional bits: the default values. Not necessary, but handy. We go to section ''[ req_distinguished_name ]'' and fill them in. For this, we again use the table we've previously compounded. So the changes we've made will amount to something like this: [ CA_default ] dir = /etc/ssl/ca ... default_days = 370 ... [ req ] default_bits = 2048 ... [ req_distinguished_name ] 0.organizationName_default = Saruman.biz stateOrProvinceName_default = Utrecht countryName_default = NL Especially the last section is, again, a pretty arbitrary choice. You could choose not to provide customized default answers (in which case you're stuck with Internet Widgets Pty from Some-State, AU as the default answers). There are more default values in that section of the ''openssl.cnf'' configuration file; go in there and decide what you want. ==the Certificate Authority root certificate== Now with the basic information in place, we can go about generating the certificate itself, and putting it to use. Well, actually we're not going to generate ''one'' certificate, but ''two'': the public one, that we give out to anyone that might want to check the validity of any certificate that claims to have been issued by the Saruman.biz CA, and the private one, with which we can digitally sign certificates so as to prove that they're really issued by said Saruman.biz CA. This is also referred to as a "key pair". ===Creating the CA root certificate key pair=== To generate the CA's public and private root certificate, as root, execute /usr/lib/ssl/misc/CA.sh -newca With the defaults set as given above, you still get some questions. One is "CA certificate filename". This actually requests from you another certificate with which to sign the one we're creating. However, we're generating our root certificate, so we leave this empty and just hit &lt;enter>. Next question is for the PEM passphrase. Make that a strong passphrase or password, keep it very secret, and '''don't forget it!''' (and DON'T write it on a piece of paper; use something like [http://keepass.info keepass] to store your secret passwords). For the next set of questions, you probably have filled in some of the defaults. If you want to leave some entry blank, fill in a period ('''.'''). You'll have to provide the country code, province or state, locality (like city; Saruman.biz leaves this empty), Organization Name, Organizational Unit name (again, empty), and finally the Common Name. This last question is pretty important: the name you put in here is the name under which your CA will go for the next 15 years!! So don't put in a "funny" name, a bland name, or whatever. We put in "Saruman.biz Root CA", somewhat like official root CA's like "Equifax Secure Global eBusiness CA-1" or "Macao Post eSignTrust Root Certification Authority". The script also asks for an email address, which you may or may not provide, a challenge password, and an "optional company name", both of which you can leave blank because we're not sending a certificate signing request out to someone else, but signing it ourselves.<br> Having provided this information, we've actually already created one half of the key pair, namely the private key. It'll be ''/etc/openssl/ca/private/ca.pem'', and is protected by our chosen very strong password. However, we now need the public key, self-signed with the private key. The next step in our CA creation process thus ''again'' asks for the passphrase. Since this is the second step in a two-step process, we again put in the passphrase we've already provided. However, now the shellscript uses this to unlock the private key we've (already) created, and then use it to sign the public key we're now creating. However, the passphrase is ''all'' that it asks. It now generates a signing request (''/etc/openssl/ca/careq.pem''), then uses the private key to sign it, and then generate the public key, to be found in ''/etc/openssl/ca/cacert.pem''. You can remove ''careq.pem'' after you've inspected the ''cacert.pem''. So now we've got two root certificates, namely '''private''' key ''/etc/openssl/ca/private/cakey.pem'' and '''public''' key ''/etc/openssl/ca/cacert.pem''. NEVER send your public key out to ANYONE! Protect that key, and its passphrase, with your life. If you lose the file, lose the passphrase, or the key gets compromised (lost to an unknown party) then you've got to replace your root certificates AND you'll have to re-issue ALL certificates that you've ever signed (we're not going into certificate revocation here). You can inspect your certificates (when you're in directory ''/etc/openssl/ca'') with commands like this: openssl x509 -in cacert.pem -noout -text openssl x509 -in cacert.pem -noout -dates openssl x509 -in cacert.pem -noout -purpose Note from the last command that this certificate is obviously a root certificate: it can sign everything but the kitchen sink. ===We've got the CA certificate, now what?=== With the root CA certificates available to us, we've got two things to do: * guard very carefully the public and (especially) the private key file * sign certificates for our own use The first means we've got to keep a copy of the private key file in some other, safe location, and we've got to secure the private key on the server where it sits - both the machine and the file. It might even be wise to remove the private key, and keep it on a USB stick, and only read it when signing certificates. The second thing means we've got to generate keys for SSL and TLS connections, just as we need them. This is covered in our [[Creating digital certificates with our root certificate | creating digital certificates]] section. 03989d60b8f5e427027e129ab2e6aec8875c5765 3089 3088 2016-02-23T09:23:28Z Saruman! 2 reordered wikitext text/x-wiki ==Certificates, an introduction== Digital certificates are an extremely important means to identify identities (of users, as well as of servers) on the Internet, or indeed on most any network. For instance, we use them to encrypt network traffic when we use the HTTPS protocol. Thus, we really need certificates. Now, as [http://www.debian-administration.org/articles/618 this article] explains, you can either buy your certificates from a certificate authority like [http://www.verisign.com/ VeriSign], [http://www.thawte.com/ Thawte] or [http://www.equifaxsecure.co.uk/index.html Equifax Secure], but these certificates cost more than a couple of Euro's, and also need to be renewed (usually every year). So the other route, the one we'll be taking, is to create our own Certificate Authority (CA), and use that to sign certificates for our needs (secure webserver, secure mailserver etcetera). Now, "creating a CA" sounds like grave installation and configuration work, but in fact a CA does not have to be an actual service, demon or program. A CA is more like a concept, at the heart of which lies the CA "root certificate". So if we obtain a little set of tools and generate our own root certificate, then we're in business. ==Creating the Certificate Authority (CA) - preparations== To generate the root CA for our own little organization, we first need tools. These tools under Debian come with the OpenSSL software - which you'll usually find already installed (if not, run ''apt-get install openssl''). Now to generate the CA root certificate, we'll use a shell script from the OpenSSL package: ''/usr/lib/ssl/misc/CA.sh'', which together with the configuration file ''/etc/ssl/openssl.cnf'' can create our CA root certificate. To that end, we'll first need to decide on some parameters. ===Deciding on CA parameters=== '''How strong''' do we want our root certificate? 1024 bits is the default, but the stronger, the better. We suggest 4096 bits - not because 2048 isn't sufficient (even 1024 is still very very good, even in the year 2016), but because it's not necessary to keep a CA's key length very low, and 4096 can be expected to remain pretty secure until after 2030 (see [http://danielpocock.com/rsa-key-sizes-2048-or-4096-bits here]). How long should our '''CA root certificate remain valid'''? The longer, the more convenient - but maybe some day in the future, you feel you don't want certificates issued ten years ago to just lie around, expired but otherwise valid. Expiry of the root certificate that goes along with that certificate might help you. So what's an appropriate time for your root CA? That depends. For our home CA, we use 15 years. For a business, the cost of providing new root certificates to all computers, employees, and maybe customers, can be so high that you'd rather have 25 years - or maybe security is paramount, and 5 years is long enough for you. We can't say - but our home CA's use 15 years, because we feel that that's a nice intermediate value. 15 years, including about 4 leap days, comes to 5479 days. '''Where do we want to store''' our CA root certificate? By default, the ''CA.sh'' script feels it must store all generated certificates in ''./demoCA''. That's not very handy for us. We rather have a central location like ''/etc/ssl/ca'' on our home server. Yes, it's sound advice to keep the root certificate on an offline machine and all that, but this is for a self-signed certificate, and if this particular directory gets compromised, then so is the whole home server, and we've got greater issues than the loss of a self-signed private key. How long should '''any generated certificate be valid'''? The default value that the ''CA.sh'' script provides is one year. We find that enough - although we add 7 days to accommodate some overlap when having to regenerate the certificate upon nearing the expiry date (note: we really want to replace certificates ''prior'' to expiry :-) '''What "company" data''' will we enter in the certificate? Several fields must be entered, some of which you could fill out at will. However, it's not exactly clear why you would want to confuse people trying to authenticate you, your webserver or some other connection by filling out, for example, the country with an incorrect or even non-existent code. On the other hand, you can keep your own privacy in mind, and not fill in your full name, but rather your website's name, at the "common name" section of your CA root certificate. Again, this depends on what you're going to use your CA for. We at [https://www.saruman.biz saruman.biz] decided to use the following values: * Organization name: Saruman.biz. We're private persons, not companies, but we want to maintain a minimum of privacy, so we've put this fake entity name here. * Country: NL (that's the Netherlands) * Province: Utrecht. Yep, that's a province in the Netherlands, and I happen to live in it. Maybe you want to provide more default information to your CA setup; just look further down on how to. So the information we've decided upon is like this: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Parameter !style="background:#ffdead;"|value |- |root certificate encryption |4096 bits |- |root certificate validity |5479 days (15 years) |- |certificate store |''/etc/ssl/ca'' |- |default certificate validity |370 days (1 year) |- |Organization name |Saruman.biz |- |Certificate province/county name (default) |Utrecht |- |Certificate country name (default) |NL |- |} === Editing the ''openssl.cnf'' configuration file=== When generating certificates, the OpenSSL tools check the configuration file ''/etc/ssl/openssl.cnf''. It is necessary to match the parameters in there with the choices and changes of the previous sections, and also it's handy to change some of the default parameters that certificates require upon generation. It's important to remember that these parameters will be asked every time you generate a certificate, but it's ofcourse pretty handy if the default value is set for your situation, so you can just hit that big &lt;enter> key. First up, we'll change the ''dir'' variable in section ''[ CA_default ]'' to match the dir from the ''CA.sh'' script. Then we find ''default_days'' and change it to our default certificate lifetime: 370 days. Furthermore, we find the certificate strengt in the ''[ req ]'' section; we can change it to our preferred value of 2048 bits. Now we can put in the optional bits: the default values. Not necessary, but handy. We go to section ''[ req_distinguished_name ]'' and fill them in. For this, we again use the table we've previously compounded. So the changes we've made will amount to something like this: [ CA_default ] dir = /etc/ssl/ca ... default_days = 370 ... [ req ] default_bits = 2048 ... [ req_distinguished_name ] 0.organizationName_default = Saruman.biz stateOrProvinceName_default = Utrecht countryName_default = NL Especially the last section is, again, a pretty arbitrary choice. You could choose not to provide customized default answers (in which case you're stuck with Internet Widgets Pty from Some-State, AU as the default answers). There are more default values in that section of the ''openssl.cnf'' configuration file; go in there and decide what you want. === Editing the ''CA.sh'' script === Unfortunately, not everything we want to change is actually set from the ''openssl.conf'' file: we'll need to alter some parameters for the root certificate that are hard-coded in the setup scripts. We find the scripts in ''/usr/lib/ssl/misc/''. Note that there are two different scripts: ''CA.sh'', a shell script, and ''CA.pl'', a perl script. Since we're more into shell scripting than perl programming, we go for the shell script. So we edit ''/usr/lib/ssl/misc/CA.sh''; find the two lines near the top that define the variables ''DAYS'' and ''CADAYS'', and set these to what we want them to be. Then, a lot further down, we find the line that's responsible for creating the CA root certificate itself, it's the line that goes ''$REQ -new -keyout ${CATOP}/private/$CAKEY -out ${CATOP}/$CAREQ'' (well actually it's split out over two lines). Here, right after ''-new'' we add ''-newkey rsa:4096''. With all these changes, the three relevant sections in ''CA.sh'' will be changed to something like this: DAYS="-days 370" # 1 year CADAYS="-days 5479" # 15 years ... echo "Making CA certificate ..." $REQ -new -newkey rsa:4096 -keyout ${CATOP}/private/$CAKEY \ -out ${CATOP}/$CAREQ ==the Certificate Authority root certificate== Now with the basic information in place, we can go about generating the certificate itself, and putting it to use. Well, actually we're not going to generate ''one'' certificate, but ''two'': the public one, that we give out to anyone that might want to check the validity of any certificate that claims to have been issued by the Saruman.biz CA, and the private one, with which we can digitally sign certificates so as to prove that they're really issued by said Saruman.biz CA. This is also referred to as a "key pair". ===Creating the CA root certificate key pair=== To generate the CA's public and private root certificate, as root, execute /usr/lib/ssl/misc/CA.sh -newca With the defaults set as given above, you still get some questions. One is "CA certificate filename". This actually requests from you another certificate with which to sign the one we're creating. However, we're generating our root certificate, so we leave this empty and just hit &lt;enter>. Next question is for the PEM passphrase. Make that a strong passphrase or password, keep it very secret, and '''don't forget it!''' (and DON'T write it on a piece of paper; use something like [http://keepass.info keepass] to store your secret passwords). For the next set of questions, you probably have filled in some of the defaults. If you want to leave some entry blank, fill in a period ('''.'''). You'll have to provide the country code, province or state, locality (like city; Saruman.biz leaves this empty), Organization Name, Organizational Unit name (again, empty), and finally the Common Name. This last question is pretty important: the name you put in here is the name under which your CA will go for the next 15 years!! So don't put in a "funny" name, a bland name, or whatever. We put in "Saruman.biz Root CA", somewhat like official root CA's like "Equifax Secure Global eBusiness CA-1" or "Macao Post eSignTrust Root Certification Authority". The script also asks for an email address, which you may or may not provide, a challenge password, and an "optional company name", both of which you can leave blank because we're not sending a certificate signing request out to someone else, but signing it ourselves.<br> Having provided this information, we've actually already created one half of the key pair, namely the private key. It'll be ''/etc/openssl/ca/private/ca.pem'', and is protected by our chosen very strong password. However, we now need the public key, self-signed with the private key. The next step in our CA creation process thus ''again'' asks for the passphrase. Since this is the second step in a two-step process, we again put in the passphrase we've already provided. However, now the shellscript uses this to unlock the private key we've (already) created, and then use it to sign the public key we're now creating. However, the passphrase is ''all'' that it asks. It now generates a signing request (''/etc/openssl/ca/careq.pem''), then uses the private key to sign it, and then generate the public key, to be found in ''/etc/openssl/ca/cacert.pem''. You can remove ''careq.pem'' after you've inspected the ''cacert.pem''. So now we've got two root certificates, namely '''private''' key ''/etc/openssl/ca/private/cakey.pem'' and '''public''' key ''/etc/openssl/ca/cacert.pem''. NEVER send your public key out to ANYONE! Protect that key, and its passphrase, with your life. If you lose the file, lose the passphrase, or the key gets compromised (lost to an unknown party) then you've got to replace your root certificates AND you'll have to re-issue ALL certificates that you've ever signed (we're not going into certificate revocation here). You can inspect your certificates (when you're in directory ''/etc/openssl/ca'') with commands like this: openssl x509 -in cacert.pem -noout -text openssl x509 -in cacert.pem -noout -dates openssl x509 -in cacert.pem -noout -purpose Note from the last command that this certificate is obviously a root certificate: it can sign everything but the kitchen sink. ===We've got the CA certificate, now what?=== With the root CA certificates available to us, we've got two things to do: * guard very carefully the public and (especially) the private key file * sign certificates for our own use The first means we've got to keep a copy of the private key file in some other, safe location, and we've got to secure the private key on the server where it sits - both the machine and the file. It might even be wise to remove the private key, and keep it on a USB stick, and only read it when signing certificates. The second thing means we've got to generate keys for SSL and TLS connections, just as we need them. This is covered in our [[Creating digital certificates with our root certificate | creating digital certificates]] section. 1fe0b6f1ec0fc86aa8816145682773ffdb54cdd6 3090 3089 2016-10-29T19:40:20Z Saruman! 2 /* Creating the CA root certificate key pair */ expanded with checks wikitext text/x-wiki ==Certificates, an introduction== Digital certificates are an extremely important means to identify identities (of users, as well as of servers) on the Internet, or indeed on most any network. For instance, we use them to encrypt network traffic when we use the HTTPS protocol. Thus, we really need certificates. Now, as [http://www.debian-administration.org/articles/618 this article] explains, you can either buy your certificates from a certificate authority like [http://www.verisign.com/ VeriSign], [http://www.thawte.com/ Thawte] or [http://www.equifaxsecure.co.uk/index.html Equifax Secure], but these certificates cost more than a couple of Euro's, and also need to be renewed (usually every year). So the other route, the one we'll be taking, is to create our own Certificate Authority (CA), and use that to sign certificates for our needs (secure webserver, secure mailserver etcetera). Now, "creating a CA" sounds like grave installation and configuration work, but in fact a CA does not have to be an actual service, demon or program. A CA is more like a concept, at the heart of which lies the CA "root certificate". So if we obtain a little set of tools and generate our own root certificate, then we're in business. ==Creating the Certificate Authority (CA) - preparations== To generate the root CA for our own little organization, we first need tools. These tools under Debian come with the OpenSSL software - which you'll usually find already installed (if not, run ''apt-get install openssl''). Now to generate the CA root certificate, we'll use a shell script from the OpenSSL package: ''/usr/lib/ssl/misc/CA.sh'', which together with the configuration file ''/etc/ssl/openssl.cnf'' can create our CA root certificate. To that end, we'll first need to decide on some parameters. ===Deciding on CA parameters=== '''How strong''' do we want our root certificate? 1024 bits is the default, but the stronger, the better. We suggest 4096 bits - not because 2048 isn't sufficient (even 1024 is still very very good, even in the year 2016), but because it's not necessary to keep a CA's key length very low, and 4096 can be expected to remain pretty secure until after 2030 (see [http://danielpocock.com/rsa-key-sizes-2048-or-4096-bits here]). How long should our '''CA root certificate remain valid'''? The longer, the more convenient - but maybe some day in the future, you feel you don't want certificates issued ten years ago to just lie around, expired but otherwise valid. Expiry of the root certificate that goes along with that certificate might help you. So what's an appropriate time for your root CA? That depends. For our home CA, we use 15 years. For a business, the cost of providing new root certificates to all computers, employees, and maybe customers, can be so high that you'd rather have 25 years - or maybe security is paramount, and 5 years is long enough for you. We can't say - but our home CA's use 15 years, because we feel that that's a nice intermediate value. 15 years, including about 4 leap days, comes to 5479 days. '''Where do we want to store''' our CA root certificate? By default, the ''CA.sh'' script feels it must store all generated certificates in ''./demoCA''. That's not very handy for us. We rather have a central location like ''/etc/ssl/ca'' on our home server. Yes, it's sound advice to keep the root certificate on an offline machine and all that, but this is for a self-signed certificate, and if this particular directory gets compromised, then so is the whole home server, and we've got greater issues than the loss of a self-signed private key. How long should '''any generated certificate be valid'''? The default value that the ''CA.sh'' script provides is one year. We find that enough - although we add 7 days to accommodate some overlap when having to regenerate the certificate upon nearing the expiry date (note: we really want to replace certificates ''prior'' to expiry :-) '''What "company" data''' will we enter in the certificate? Several fields must be entered, some of which you could fill out at will. However, it's not exactly clear why you would want to confuse people trying to authenticate you, your webserver or some other connection by filling out, for example, the country with an incorrect or even non-existent code. On the other hand, you can keep your own privacy in mind, and not fill in your full name, but rather your website's name, at the "common name" section of your CA root certificate. Again, this depends on what you're going to use your CA for. We at [https://www.saruman.biz saruman.biz] decided to use the following values: * Organization name: Saruman.biz. We're private persons, not companies, but we want to maintain a minimum of privacy, so we've put this fake entity name here. * Country: NL (that's the Netherlands) * Province: Utrecht. Yep, that's a province in the Netherlands, and I happen to live in it. Maybe you want to provide more default information to your CA setup; just look further down on how to. So the information we've decided upon is like this: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Parameter !style="background:#ffdead;"|value |- |root certificate encryption |4096 bits |- |root certificate validity |5479 days (15 years) |- |certificate store |''/etc/ssl/ca'' |- |default certificate validity |370 days (1 year) |- |Organization name |Saruman.biz |- |Certificate province/county name (default) |Utrecht |- |Certificate country name (default) |NL |- |} === Editing the ''openssl.cnf'' configuration file=== When generating certificates, the OpenSSL tools check the configuration file ''/etc/ssl/openssl.cnf''. It is necessary to match the parameters in there with the choices and changes of the previous sections, and also it's handy to change some of the default parameters that certificates require upon generation. It's important to remember that these parameters will be asked every time you generate a certificate, but it's ofcourse pretty handy if the default value is set for your situation, so you can just hit that big &lt;enter> key. First up, we'll change the ''dir'' variable in section ''[ CA_default ]'' to match the dir from the ''CA.sh'' script. Then we find ''default_days'' and change it to our default certificate lifetime: 370 days. Furthermore, we find the certificate strengt in the ''[ req ]'' section; we can change it to our preferred value of 2048 bits. Now we can put in the optional bits: the default values. Not necessary, but handy. We go to section ''[ req_distinguished_name ]'' and fill them in. For this, we again use the table we've previously compounded. So the changes we've made will amount to something like this: [ CA_default ] dir = /etc/ssl/ca ... default_days = 370 ... [ req ] default_bits = 2048 ... [ req_distinguished_name ] 0.organizationName_default = Saruman.biz stateOrProvinceName_default = Utrecht countryName_default = NL Especially the last section is, again, a pretty arbitrary choice. You could choose not to provide customized default answers (in which case you're stuck with Internet Widgets Pty from Some-State, AU as the default answers). There are more default values in that section of the ''openssl.cnf'' configuration file; go in there and decide what you want. === Editing the ''CA.sh'' script === Unfortunately, not everything we want to change is actually set from the ''openssl.conf'' file: we'll need to alter some parameters for the root certificate that are hard-coded in the setup scripts. We find the scripts in ''/usr/lib/ssl/misc/''. Note that there are two different scripts: ''CA.sh'', a shell script, and ''CA.pl'', a perl script. Since we're more into shell scripting than perl programming, we go for the shell script. So we edit ''/usr/lib/ssl/misc/CA.sh''; find the two lines near the top that define the variables ''DAYS'' and ''CADAYS'', and set these to what we want them to be. Then, a lot further down, we find the line that's responsible for creating the CA root certificate itself, it's the line that goes ''$REQ -new -keyout ${CATOP}/private/$CAKEY -out ${CATOP}/$CAREQ'' (well actually it's split out over two lines). Here, right after ''-new'' we add ''-newkey rsa:4096''. With all these changes, the three relevant sections in ''CA.sh'' will be changed to something like this: DAYS="-days 370" # 1 year CADAYS="-days 5479" # 15 years ... echo "Making CA certificate ..." $REQ -new -newkey rsa:4096 -keyout ${CATOP}/private/$CAKEY \ -out ${CATOP}/$CAREQ ==the Certificate Authority root certificate== Now with the basic information in place, we can go about generating the certificate itself, and putting it to use. Well, actually we're not going to generate ''one'' certificate, but ''two'': the public one, that we give out to anyone that might want to check the validity of any certificate that claims to have been issued by the Saruman.biz CA, and the private one, with which we can digitally sign certificates so as to prove that they're really issued by said Saruman.biz CA. This is also referred to as a "key pair". ===Creating the CA root certificate key pair=== To generate the CA's public and private root certificate, as root, execute /usr/lib/ssl/misc/CA.sh -newca With the defaults set as given above, you still get some questions. One is "CA certificate filename". This actually requests from you another certificate with which to sign the one we're creating. However, we're generating our root certificate, so we leave this empty and just hit &lt;enter>. Next question is for the PEM passphrase. Make that a strong passphrase or password, keep it very secret, and '''don't forget it!''' (and DON'T write it on a piece of paper; use something like [http://keepass.info keepass] to store your secret passwords). For the next set of questions, you probably have filled in some of the defaults. If you want to leave some entry blank, fill in a period ('''.'''). You'll have to provide the country code, province or state, locality (like city; Saruman.biz leaves this empty), Organization Name, Organizational Unit name (again, empty), and finally the Common Name. This last question is pretty important: the name you put in here is the name under which your CA will go for the next 15 years!! So don't put in a "funny" name, a bland name, or whatever. We put in "Saruman.biz Root CA", somewhat like official root CA's like "Equifax Secure Global eBusiness CA-1" or "Macao Post eSignTrust Root Certification Authority". The script also asks for an email address, which you may or may not provide, a challenge password, and an "optional company name", both of which you can leave blank because we're not sending a certificate signing request out to someone else, but signing it ourselves.<br> Having provided this information, we've actually already created one half of the key pair, namely the private key. It'll be ''/etc/openssl/ca/private/ca.pem'', and is protected by our chosen very strong password. However, we now need the public key, self-signed with the private key. The next step in our CA creation process thus ''again'' asks for the passphrase. Since this is the second step in a two-step process, we again put in the passphrase we've already provided. However, now the shellscript uses this to unlock the private key we've (already) created, and then use it to sign the public key we're now creating. However, the passphrase is ''all'' that it asks. It now generates a signing request (''/etc/openssl/ca/careq.pem''), then uses the private key to sign it, and then generate the public key, to be found in ''/etc/openssl/ca/cacert.pem''. You can remove ''careq.pem'' after you've inspected the ''cacert.pem''. So now we've got two root certificates, namely * '''private''' key ''/etc/openssl/ca/private/cakey.pem'', and * '''public''' key ''/etc/openssl/ca/cacert.pem''. NEVER send your private key out to ANYONE! Protect that key, and its passphrase, with your life. If you lose the file, lose the passphrase, or the key gets compromised (lost to an unknown party) then you've got to replace your root certificates AND you'll have to re-issue ALL certificates that you've ever signed (we're not going into certificate revocation here). You can inspect your certificates (when you're in directory ''/etc/openssl/ca'') with commands like this: openssl x509 -in cacert.pem -noout -text openssl x509 -in cacert.pem -noout -dates openssl x509 -in cacert.pem -noout -purpose Note from the last command above, that this certificate is obviously a root certificate: it can verify the signature of everything but the kitchen sink. In the same manner you can inspect your private key: openssl rsa -in private/cakey.pem -noout -text Note that this can be used to check if the private key and certificate belong together: the `modulus' and the `public exponent' portions in the private key and the certificate must match. But since the public exponent is usually 65537 and it's bothering comparing long modulus you can use the following approach: openssl x509 -in cacert.pem -noout -modulus | openssl md5 openssl rsa -in private/cakey.pem -noout -modulus | openssl md5 And then compare these really shorter numbers. Both commands will output something like: (stdin)= 96a281eca852b794a907186a9703ddf4 With overwhelming probability they will differ if the keys are different. ===We've got the CA certificate, now what?=== With the root CA certificates available to us, we've got two things to do: * guard very carefully the public and (especially) the private key file * sign certificates for our own use The first means we've got to keep a copy of the private key file in some other, safe location, and we've got to secure the private key on the server where it sits - both the machine and the file. It might even be wise to remove the private key, and keep it on a USB stick, and only read it when signing certificates. The second thing means we've got to generate keys for SSL and TLS connections, just as we need them. This is covered in our [[Creating digital certificates with our root certificate | creating digital certificates]] section. 9ba601697a99e7d310667959078c9fec5693631b 3091 3090 2016-10-29T20:06:52Z Saruman! 2 /* We've got the CA certificate, now what? */ added crt conversion wikitext text/x-wiki ==Certificates, an introduction== Digital certificates are an extremely important means to identify identities (of users, as well as of servers) on the Internet, or indeed on most any network. For instance, we use them to encrypt network traffic when we use the HTTPS protocol. Thus, we really need certificates. Now, as [http://www.debian-administration.org/articles/618 this article] explains, you can either buy your certificates from a certificate authority like [http://www.verisign.com/ VeriSign], [http://www.thawte.com/ Thawte] or [http://www.equifaxsecure.co.uk/index.html Equifax Secure], but these certificates cost more than a couple of Euro's, and also need to be renewed (usually every year). So the other route, the one we'll be taking, is to create our own Certificate Authority (CA), and use that to sign certificates for our needs (secure webserver, secure mailserver etcetera). Now, "creating a CA" sounds like grave installation and configuration work, but in fact a CA does not have to be an actual service, demon or program. A CA is more like a concept, at the heart of which lies the CA "root certificate". So if we obtain a little set of tools and generate our own root certificate, then we're in business. ==Creating the Certificate Authority (CA) - preparations== To generate the root CA for our own little organization, we first need tools. These tools under Debian come with the OpenSSL software - which you'll usually find already installed (if not, run ''apt-get install openssl''). Now to generate the CA root certificate, we'll use a shell script from the OpenSSL package: ''/usr/lib/ssl/misc/CA.sh'', which together with the configuration file ''/etc/ssl/openssl.cnf'' can create our CA root certificate. To that end, we'll first need to decide on some parameters. ===Deciding on CA parameters=== '''How strong''' do we want our root certificate? 1024 bits is the default, but the stronger, the better. We suggest 4096 bits - not because 2048 isn't sufficient (even 1024 is still very very good, even in the year 2016), but because it's not necessary to keep a CA's key length very low, and 4096 can be expected to remain pretty secure until after 2030 (see [http://danielpocock.com/rsa-key-sizes-2048-or-4096-bits here]). How long should our '''CA root certificate remain valid'''? The longer, the more convenient - but maybe some day in the future, you feel you don't want certificates issued ten years ago to just lie around, expired but otherwise valid. Expiry of the root certificate that goes along with that certificate might help you. So what's an appropriate time for your root CA? That depends. For our home CA, we use 15 years. For a business, the cost of providing new root certificates to all computers, employees, and maybe customers, can be so high that you'd rather have 25 years - or maybe security is paramount, and 5 years is long enough for you. We can't say - but our home CA's use 15 years, because we feel that that's a nice intermediate value. 15 years, including about 4 leap days, comes to 5479 days. '''Where do we want to store''' our CA root certificate? By default, the ''CA.sh'' script feels it must store all generated certificates in ''./demoCA''. That's not very handy for us. We rather have a central location like ''/etc/ssl/ca'' on our home server. Yes, it's sound advice to keep the root certificate on an offline machine and all that, but this is for a self-signed certificate, and if this particular directory gets compromised, then so is the whole home server, and we've got greater issues than the loss of a self-signed private key. How long should '''any generated certificate be valid'''? The default value that the ''CA.sh'' script provides is one year. We find that enough - although we add 7 days to accommodate some overlap when having to regenerate the certificate upon nearing the expiry date (note: we really want to replace certificates ''prior'' to expiry :-) '''What "company" data''' will we enter in the certificate? Several fields must be entered, some of which you could fill out at will. However, it's not exactly clear why you would want to confuse people trying to authenticate you, your webserver or some other connection by filling out, for example, the country with an incorrect or even non-existent code. On the other hand, you can keep your own privacy in mind, and not fill in your full name, but rather your website's name, at the "common name" section of your CA root certificate. Again, this depends on what you're going to use your CA for. We at [https://www.saruman.biz saruman.biz] decided to use the following values: * Organization name: Saruman.biz. We're private persons, not companies, but we want to maintain a minimum of privacy, so we've put this fake entity name here. * Country: NL (that's the Netherlands) * Province: Utrecht. Yep, that's a province in the Netherlands, and I happen to live in it. Maybe you want to provide more default information to your CA setup; just look further down on how to. So the information we've decided upon is like this: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Parameter !style="background:#ffdead;"|value |- |root certificate encryption |4096 bits |- |root certificate validity |5479 days (15 years) |- |certificate store |''/etc/ssl/ca'' |- |default certificate validity |370 days (1 year) |- |Organization name |Saruman.biz |- |Certificate province/county name (default) |Utrecht |- |Certificate country name (default) |NL |- |} === Editing the ''openssl.cnf'' configuration file=== When generating certificates, the OpenSSL tools check the configuration file ''/etc/ssl/openssl.cnf''. It is necessary to match the parameters in there with the choices and changes of the previous sections, and also it's handy to change some of the default parameters that certificates require upon generation. It's important to remember that these parameters will be asked every time you generate a certificate, but it's ofcourse pretty handy if the default value is set for your situation, so you can just hit that big &lt;enter> key. First up, we'll change the ''dir'' variable in section ''[ CA_default ]'' to match the dir from the ''CA.sh'' script. Then we find ''default_days'' and change it to our default certificate lifetime: 370 days. Furthermore, we find the certificate strengt in the ''[ req ]'' section; we can change it to our preferred value of 2048 bits. Now we can put in the optional bits: the default values. Not necessary, but handy. We go to section ''[ req_distinguished_name ]'' and fill them in. For this, we again use the table we've previously compounded. So the changes we've made will amount to something like this: [ CA_default ] dir = /etc/ssl/ca ... default_days = 370 ... [ req ] default_bits = 2048 ... [ req_distinguished_name ] 0.organizationName_default = Saruman.biz stateOrProvinceName_default = Utrecht countryName_default = NL Especially the last section is, again, a pretty arbitrary choice. You could choose not to provide customized default answers (in which case you're stuck with Internet Widgets Pty from Some-State, AU as the default answers). There are more default values in that section of the ''openssl.cnf'' configuration file; go in there and decide what you want. === Editing the ''CA.sh'' script === Unfortunately, not everything we want to change is actually set from the ''openssl.conf'' file: we'll need to alter some parameters for the root certificate that are hard-coded in the setup scripts. We find the scripts in ''/usr/lib/ssl/misc/''. Note that there are two different scripts: ''CA.sh'', a shell script, and ''CA.pl'', a perl script. Since we're more into shell scripting than perl programming, we go for the shell script. So we edit ''/usr/lib/ssl/misc/CA.sh''; find the two lines near the top that define the variables ''DAYS'' and ''CADAYS'', and set these to what we want them to be. Then, a lot further down, we find the line that's responsible for creating the CA root certificate itself, it's the line that goes ''$REQ -new -keyout ${CATOP}/private/$CAKEY -out ${CATOP}/$CAREQ'' (well actually it's split out over two lines). Here, right after ''-new'' we add ''-newkey rsa:4096''. With all these changes, the three relevant sections in ''CA.sh'' will be changed to something like this: DAYS="-days 370" # 1 year CADAYS="-days 5479" # 15 years ... echo "Making CA certificate ..." $REQ -new -newkey rsa:4096 -keyout ${CATOP}/private/$CAKEY \ -out ${CATOP}/$CAREQ ==the Certificate Authority root certificate== Now with the basic information in place, we can go about generating the certificate itself, and putting it to use. Well, actually we're not going to generate ''one'' certificate, but ''two'': the public one, that we give out to anyone that might want to check the validity of any certificate that claims to have been issued by the Saruman.biz CA, and the private one, with which we can digitally sign certificates so as to prove that they're really issued by said Saruman.biz CA. This is also referred to as a "key pair". ===Creating the CA root certificate key pair=== To generate the CA's public and private root certificate, as root, execute /usr/lib/ssl/misc/CA.sh -newca With the defaults set as given above, you still get some questions. One is "CA certificate filename". This actually requests from you another certificate with which to sign the one we're creating. However, we're generating our root certificate, so we leave this empty and just hit &lt;enter>. Next question is for the PEM passphrase. Make that a strong passphrase or password, keep it very secret, and '''don't forget it!''' (and DON'T write it on a piece of paper; use something like [http://keepass.info keepass] to store your secret passwords). For the next set of questions, you probably have filled in some of the defaults. If you want to leave some entry blank, fill in a period ('''.'''). You'll have to provide the country code, province or state, locality (like city; Saruman.biz leaves this empty), Organization Name, Organizational Unit name (again, empty), and finally the Common Name. This last question is pretty important: the name you put in here is the name under which your CA will go for the next 15 years!! So don't put in a "funny" name, a bland name, or whatever. We put in "Saruman.biz Root CA", somewhat like official root CA's like "Equifax Secure Global eBusiness CA-1" or "Macao Post eSignTrust Root Certification Authority". The script also asks for an email address, which you may or may not provide, a challenge password, and an "optional company name", both of which you can leave blank because we're not sending a certificate signing request out to someone else, but signing it ourselves.<br> Having provided this information, we've actually already created one half of the key pair, namely the private key. It'll be ''/etc/openssl/ca/private/ca.pem'', and is protected by our chosen very strong password. However, we now need the public key, self-signed with the private key. The next step in our CA creation process thus ''again'' asks for the passphrase. Since this is the second step in a two-step process, we again put in the passphrase we've already provided. However, now the shellscript uses this to unlock the private key we've (already) created, and then use it to sign the public key we're now creating. However, the passphrase is ''all'' that it asks. It now generates a signing request (''/etc/openssl/ca/careq.pem''), then uses the private key to sign it, and then generate the public key, to be found in ''/etc/openssl/ca/cacert.pem''. You can remove ''careq.pem'' after you've inspected the ''cacert.pem''. So now we've got two root certificates, namely * '''private''' key ''/etc/openssl/ca/private/cakey.pem'', and * '''public''' key ''/etc/openssl/ca/cacert.pem''. NEVER send your private key out to ANYONE! Protect that key, and its passphrase, with your life. If you lose the file, lose the passphrase, or the key gets compromised (lost to an unknown party) then you've got to replace your root certificates AND you'll have to re-issue ALL certificates that you've ever signed (we're not going into certificate revocation here). You can inspect your certificates (when you're in directory ''/etc/openssl/ca'') with commands like this: openssl x509 -in cacert.pem -noout -text openssl x509 -in cacert.pem -noout -dates openssl x509 -in cacert.pem -noout -purpose Note from the last command above, that this certificate is obviously a root certificate: it can verify the signature of everything but the kitchen sink. In the same manner you can inspect your private key: openssl rsa -in private/cakey.pem -noout -text Note that this can be used to check if the private key and certificate belong together: the `modulus' and the `public exponent' portions in the private key and the certificate must match. But since the public exponent is usually 65537 and it's bothering comparing long modulus you can use the following approach: openssl x509 -in cacert.pem -noout -modulus | openssl md5 openssl rsa -in private/cakey.pem -noout -modulus | openssl md5 And then compare these really shorter numbers. Both commands will output something like: (stdin)= 96a281eca852b794a907186a9703ddf4 With overwhelming probability they will differ if the keys are different. ===We've got the CA certificate, now what?=== With the root CA certificates available to us, we've got the following things to do: * guard very carefully the public and (especially) the private key file; * sign certificates for our own use; * distribute the public CA certificate to every machine/person that may need to verify certificates that we've signed. The first means we've got to keep a copy of the private key file in some other, safe location, and we've got to secure the private key on the server where it sits - both the machine and the file. It might even be wise to remove the private key, and keep it on a USB stick, and only read it when signing certificates. The second thing means we've got to generate keys for SSL and TLS connections, just as we need them. This is covered in our [[Creating digital certificates with our root certificate | creating digital certificates]] section. The last point means we need to send out our public CA certificate. In some cases, you can provide others with your ''.pem'' file, but in other cases you're better off providing a simpler ''.crt'' file. The difference is explained nicely at the [http://info.ssl.com/article.aspx?id=12149 ssl.com site] To create a public CA certificate in .crt format you can issue the following command: openssl x509 -outform der -in cacert.pem -out cacert.crt By the way, it's usually better to distribute the public certificate with a more recognizable file name, such as ''saruman.biz.crt'' 5fd0d72700ea7950c75251a86843062e6868f33b 3092 3091 2016-10-29T20:12:05Z Saruman! 2 corrected directory name - /etc/ssl not /etc/openssl wikitext text/x-wiki ==Certificates, an introduction== Digital certificates are an extremely important means to identify identities (of users, as well as of servers) on the Internet, or indeed on most any network. For instance, we use them to encrypt network traffic when we use the HTTPS protocol. Thus, we really need certificates. Now, as [http://www.debian-administration.org/articles/618 this article] explains, you can either buy your certificates from a certificate authority like [http://www.verisign.com/ VeriSign], [http://www.thawte.com/ Thawte] or [http://www.equifaxsecure.co.uk/index.html Equifax Secure], but these certificates cost more than a couple of Euro's, and also need to be renewed (usually every year). So the other route, the one we'll be taking, is to create our own Certificate Authority (CA), and use that to sign certificates for our needs (secure webserver, secure mailserver etcetera). Now, "creating a CA" sounds like grave installation and configuration work, but in fact a CA does not have to be an actual service, demon or program. A CA is more like a concept, at the heart of which lies the CA "root certificate". So if we obtain a little set of tools and generate our own root certificate, then we're in business. ==Creating the Certificate Authority (CA) - preparations== To generate the root CA for our own little organization, we first need tools. These tools under Debian come with the OpenSSL software - which you'll usually find already installed (if not, run ''apt-get install openssl''). Now to generate the CA root certificate, we'll use a shell script from the OpenSSL package: ''/usr/lib/ssl/misc/CA.sh'', which together with the configuration file ''/etc/ssl/openssl.cnf'' can create our CA root certificate. To that end, we'll first need to decide on some parameters. ===Deciding on CA parameters=== '''How strong''' do we want our root certificate? 1024 bits is the default, but the stronger, the better. We suggest 4096 bits - not because 2048 isn't sufficient (even 1024 is still very very good, even in the year 2016), but because it's not necessary to keep a CA's key length very low, and 4096 can be expected to remain pretty secure until after 2030 (see [http://danielpocock.com/rsa-key-sizes-2048-or-4096-bits here]). How long should our '''CA root certificate remain valid'''? The longer, the more convenient - but maybe some day in the future, you feel you don't want certificates issued ten years ago to just lie around, expired but otherwise valid. Expiry of the root certificate that goes along with that certificate might help you. So what's an appropriate time for your root CA? That depends. For our home CA, we use 15 years. For a business, the cost of providing new root certificates to all computers, employees, and maybe customers, can be so high that you'd rather have 25 years - or maybe security is paramount, and 5 years is long enough for you. We can't say - but our home CA's use 15 years, because we feel that that's a nice intermediate value. 15 years, including about 4 leap days, comes to 5479 days. '''Where do we want to store''' our CA root certificate? By default, the ''CA.sh'' script feels it must store all generated certificates in ''./demoCA''. That's not very handy for us. We rather have a central location like ''/etc/ssl/ca'' on our home server. Yes, it's sound advice to keep the root certificate on an offline machine and all that, but this is for a self-signed certificate, and if this particular directory gets compromised, then so is the whole home server, and we've got greater issues than the loss of a self-signed private key. How long should '''any generated certificate be valid'''? The default value that the ''CA.sh'' script provides is one year. We find that enough - although we add 7 days to accommodate some overlap when having to regenerate the certificate upon nearing the expiry date (note: we really want to replace certificates ''prior'' to expiry :-) '''What "company" data''' will we enter in the certificate? Several fields must be entered, some of which you could fill out at will. However, it's not exactly clear why you would want to confuse people trying to authenticate you, your webserver or some other connection by filling out, for example, the country with an incorrect or even non-existent code. On the other hand, you can keep your own privacy in mind, and not fill in your full name, but rather your website's name, at the "common name" section of your CA root certificate. Again, this depends on what you're going to use your CA for. We at [https://www.saruman.biz saruman.biz] decided to use the following values: * Organization name: Saruman.biz. We're private persons, not companies, but we want to maintain a minimum of privacy, so we've put this fake entity name here. * Country: NL (that's the Netherlands) * Province: Utrecht. Yep, that's a province in the Netherlands, and I happen to live in it. Maybe you want to provide more default information to your CA setup; just look further down on how to. So the information we've decided upon is like this: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Parameter !style="background:#ffdead;"|value |- |root certificate encryption |4096 bits |- |root certificate validity |5479 days (15 years) |- |certificate store |''/etc/ssl/ca'' |- |default certificate validity |370 days (1 year) |- |Organization name |Saruman.biz |- |Certificate province/county name (default) |Utrecht |- |Certificate country name (default) |NL |- |} === Editing the ''openssl.cnf'' configuration file=== When generating certificates, the OpenSSL tools check the configuration file ''/etc/ssl/openssl.cnf''. It is necessary to match the parameters in there with the choices and changes of the previous sections, and also it's handy to change some of the default parameters that certificates require upon generation. It's important to remember that these parameters will be asked every time you generate a certificate, but it's ofcourse pretty handy if the default value is set for your situation, so you can just hit that big &lt;enter> key. First up, we'll change the ''dir'' variable in section ''[ CA_default ]'' to match the dir from the ''CA.sh'' script. Then we find ''default_days'' and change it to our default certificate lifetime: 370 days. Furthermore, we find the certificate strengt in the ''[ req ]'' section; we can change it to our preferred value of 2048 bits. Now we can put in the optional bits: the default values. Not necessary, but handy. We go to section ''[ req_distinguished_name ]'' and fill them in. For this, we again use the table we've previously compounded. So the changes we've made will amount to something like this: [ CA_default ] dir = /etc/ssl/ca ... default_days = 370 ... [ req ] default_bits = 2048 ... [ req_distinguished_name ] 0.organizationName_default = Saruman.biz stateOrProvinceName_default = Utrecht countryName_default = NL Especially the last section is, again, a pretty arbitrary choice. You could choose not to provide customized default answers (in which case you're stuck with Internet Widgets Pty from Some-State, AU as the default answers). There are more default values in that section of the ''openssl.cnf'' configuration file; go in there and decide what you want. === Editing the ''CA.sh'' script === Unfortunately, not everything we want to change is actually set from the ''openssl.conf'' file: we'll need to alter some parameters for the root certificate that are hard-coded in the setup scripts. We find the scripts in ''/usr/lib/ssl/misc/''. Note that there are two different scripts: ''CA.sh'', a shell script, and ''CA.pl'', a perl script. Since we're more into shell scripting than perl programming, we go for the shell script. So we edit ''/usr/lib/ssl/misc/CA.sh''; find the two lines near the top that define the variables ''DAYS'' and ''CADAYS'', and set these to what we want them to be. Then, a lot further down, we find the line that's responsible for creating the CA root certificate itself, it's the line that goes ''$REQ -new -keyout ${CATOP}/private/$CAKEY -out ${CATOP}/$CAREQ'' (well actually it's split out over two lines). Here, right after ''-new'' we add ''-newkey rsa:4096''. With all these changes, the three relevant sections in ''CA.sh'' will be changed to something like this: DAYS="-days 370" # 1 year CADAYS="-days 5479" # 15 years ... echo "Making CA certificate ..." $REQ -new -newkey rsa:4096 -keyout ${CATOP}/private/$CAKEY \ -out ${CATOP}/$CAREQ ==the Certificate Authority root certificate== Now with the basic information in place, we can go about generating the certificate itself, and putting it to use. Well, actually we're not going to generate ''one'' certificate, but ''two'': the public one, that we give out to anyone that might want to check the validity of any certificate that claims to have been issued by the Saruman.biz CA, and the private one, with which we can digitally sign certificates so as to prove that they're really issued by said Saruman.biz CA. This is also referred to as a "key pair". ===Creating the CA root certificate key pair=== To generate the CA's public and private root certificate, as root, execute /usr/lib/ssl/misc/CA.sh -newca With the defaults set as given above, you still get some questions. One is "CA certificate filename". This actually requests from you another certificate with which to sign the one we're creating. However, we're generating our root certificate, so we leave this empty and just hit &lt;enter>. Next question is for the PEM passphrase. Make that a strong passphrase or password, keep it very secret, and '''don't forget it!''' (and DON'T write it on a piece of paper; use something like [http://keepass.info keepass] to store your secret passwords). For the next set of questions, you probably have filled in some of the defaults. If you want to leave some entry blank, fill in a period ('''.'''). You'll have to provide the country code, province or state, locality (like city; Saruman.biz leaves this empty), Organization Name, Organizational Unit name (again, empty), and finally the Common Name. This last question is pretty important: the name you put in here is the name under which your CA will go for the next 15 years!! So don't put in a "funny" name, a bland name, or whatever. We put in "Saruman.biz Root CA", somewhat like official root CA's like "Equifax Secure Global eBusiness CA-1" or "Macao Post eSignTrust Root Certification Authority". The script also asks for an email address, which you may or may not provide, a challenge password, and an "optional company name", both of which you can leave blank because we're not sending a certificate signing request out to someone else, but signing it ourselves.<br> Having provided this information, we've actually already created one half of the key pair, namely the private key. It'll be ''/etc/ssl/ca/private/ca.pem'', and is protected by our chosen very strong password. However, we now need the public key, self-signed with the private key. The next step in our CA creation process thus ''again'' asks for the passphrase. Since this is the second step in a two-step process, we again put in the passphrase we've already provided. However, now the shellscript uses this to unlock the private key we've (already) created, and then use it to sign the public key we're now creating. However, the passphrase is ''all'' that it asks. It now generates a signing request (''/etc/ssl/ca/careq.pem''), then uses the private key to sign it, and then generate the public key, to be found in ''/etc/ssl/ca/cacert.pem''. You can remove ''careq.pem'' after you've inspected the ''cacert.pem''. So now we've got two root certificates, namely * '''private''' key ''/etc/ssl/ca/private/cakey.pem'', and * '''public''' key ''/etc/ssl/ca/cacert.pem''. NEVER send your private key out to ANYONE! Protect that key, and its passphrase, with your life. If you lose the file, lose the passphrase, or the key gets compromised (lost to an unknown party) then you've got to replace your root certificates AND you'll have to re-issue ALL certificates that you've ever signed (we're not going into certificate revocation here). You can inspect your certificates (when you're in directory ''/etc/ssl/ca'') with commands like this: openssl x509 -in cacert.pem -noout -text openssl x509 -in cacert.pem -noout -dates openssl x509 -in cacert.pem -noout -purpose Note from the last command above, that this certificate is obviously a root certificate: it can verify the signature of everything but the kitchen sink. In the same manner you can inspect your private key: openssl rsa -in private/cakey.pem -noout -text Note that this can be used to check if the private key and certificate belong together: the `modulus' and the `public exponent' portions in the private key and the certificate must match. But since the public exponent is usually 65537 and it's bothering comparing long modulus you can use the following approach: openssl x509 -in cacert.pem -noout -modulus | openssl md5 openssl rsa -in private/cakey.pem -noout -modulus | openssl md5 And then compare these really shorter numbers. Both commands will output something like: (stdin)= 96a281eca852b794a907186a9703ddf4 With overwhelming probability they will differ if the keys are different. ===We've got the CA certificate, now what?=== With the root CA certificates available to us, we've got the following things to do: * guard very carefully the public and (especially) the private key file; * sign certificates for our own use; * distribute the public CA certificate to every machine/person that may need to verify certificates that we've signed. The first means we've got to keep a copy of the private key file in some other, safe location, and we've got to secure the private key on the server where it sits - both the machine and the file. It might even be wise to remove the private key, and keep it on a USB stick, and only read it when signing certificates. The second thing means we've got to generate keys for SSL and TLS connections, just as we need them. This is covered in our [[Creating digital certificates with our root certificate | creating digital certificates]] section. The last point means we need to send out our public CA certificate. In some cases, you can provide others with your ''.pem'' file, but in other cases you're better off providing a simpler ''.crt'' file. The difference is explained nicely at the [http://info.ssl.com/article.aspx?id=12149 ssl.com site] To create a public CA certificate in .crt format you can issue the following command: openssl x509 -outform der -in cacert.pem -out cacert.crt By the way, it's usually better to distribute the public certificate with a more recognizable file name, such as ''saruman.biz.crt'' 3b237dc784b2c04243d4af4ee2725992641443e9 3093 3092 2016-10-29T20:21:48Z Saruman! 2 /* We've got the CA certificate, now what? */ wikitext text/x-wiki ==Certificates, an introduction== Digital certificates are an extremely important means to identify identities (of users, as well as of servers) on the Internet, or indeed on most any network. For instance, we use them to encrypt network traffic when we use the HTTPS protocol. Thus, we really need certificates. Now, as [http://www.debian-administration.org/articles/618 this article] explains, you can either buy your certificates from a certificate authority like [http://www.verisign.com/ VeriSign], [http://www.thawte.com/ Thawte] or [http://www.equifaxsecure.co.uk/index.html Equifax Secure], but these certificates cost more than a couple of Euro's, and also need to be renewed (usually every year). So the other route, the one we'll be taking, is to create our own Certificate Authority (CA), and use that to sign certificates for our needs (secure webserver, secure mailserver etcetera). Now, "creating a CA" sounds like grave installation and configuration work, but in fact a CA does not have to be an actual service, demon or program. A CA is more like a concept, at the heart of which lies the CA "root certificate". So if we obtain a little set of tools and generate our own root certificate, then we're in business. ==Creating the Certificate Authority (CA) - preparations== To generate the root CA for our own little organization, we first need tools. These tools under Debian come with the OpenSSL software - which you'll usually find already installed (if not, run ''apt-get install openssl''). Now to generate the CA root certificate, we'll use a shell script from the OpenSSL package: ''/usr/lib/ssl/misc/CA.sh'', which together with the configuration file ''/etc/ssl/openssl.cnf'' can create our CA root certificate. To that end, we'll first need to decide on some parameters. ===Deciding on CA parameters=== '''How strong''' do we want our root certificate? 1024 bits is the default, but the stronger, the better. We suggest 4096 bits - not because 2048 isn't sufficient (even 1024 is still very very good, even in the year 2016), but because it's not necessary to keep a CA's key length very low, and 4096 can be expected to remain pretty secure until after 2030 (see [http://danielpocock.com/rsa-key-sizes-2048-or-4096-bits here]). How long should our '''CA root certificate remain valid'''? The longer, the more convenient - but maybe some day in the future, you feel you don't want certificates issued ten years ago to just lie around, expired but otherwise valid. Expiry of the root certificate that goes along with that certificate might help you. So what's an appropriate time for your root CA? That depends. For our home CA, we use 15 years. For a business, the cost of providing new root certificates to all computers, employees, and maybe customers, can be so high that you'd rather have 25 years - or maybe security is paramount, and 5 years is long enough for you. We can't say - but our home CA's use 15 years, because we feel that that's a nice intermediate value. 15 years, including about 4 leap days, comes to 5479 days. '''Where do we want to store''' our CA root certificate? By default, the ''CA.sh'' script feels it must store all generated certificates in ''./demoCA''. That's not very handy for us. We rather have a central location like ''/etc/ssl/ca'' on our home server. Yes, it's sound advice to keep the root certificate on an offline machine and all that, but this is for a self-signed certificate, and if this particular directory gets compromised, then so is the whole home server, and we've got greater issues than the loss of a self-signed private key. How long should '''any generated certificate be valid'''? The default value that the ''CA.sh'' script provides is one year. We find that enough - although we add 7 days to accommodate some overlap when having to regenerate the certificate upon nearing the expiry date (note: we really want to replace certificates ''prior'' to expiry :-) '''What "company" data''' will we enter in the certificate? Several fields must be entered, some of which you could fill out at will. However, it's not exactly clear why you would want to confuse people trying to authenticate you, your webserver or some other connection by filling out, for example, the country with an incorrect or even non-existent code. On the other hand, you can keep your own privacy in mind, and not fill in your full name, but rather your website's name, at the "common name" section of your CA root certificate. Again, this depends on what you're going to use your CA for. We at [https://www.saruman.biz saruman.biz] decided to use the following values: * Organization name: Saruman.biz. We're private persons, not companies, but we want to maintain a minimum of privacy, so we've put this fake entity name here. * Country: NL (that's the Netherlands) * Province: Utrecht. Yep, that's a province in the Netherlands, and I happen to live in it. Maybe you want to provide more default information to your CA setup; just look further down on how to. So the information we've decided upon is like this: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Parameter !style="background:#ffdead;"|value |- |root certificate encryption |4096 bits |- |root certificate validity |5479 days (15 years) |- |certificate store |''/etc/ssl/ca'' |- |default certificate validity |370 days (1 year) |- |Organization name |Saruman.biz |- |Certificate province/county name (default) |Utrecht |- |Certificate country name (default) |NL |- |} === Editing the ''openssl.cnf'' configuration file=== When generating certificates, the OpenSSL tools check the configuration file ''/etc/ssl/openssl.cnf''. It is necessary to match the parameters in there with the choices and changes of the previous sections, and also it's handy to change some of the default parameters that certificates require upon generation. It's important to remember that these parameters will be asked every time you generate a certificate, but it's ofcourse pretty handy if the default value is set for your situation, so you can just hit that big &lt;enter> key. First up, we'll change the ''dir'' variable in section ''[ CA_default ]'' to match the dir from the ''CA.sh'' script. Then we find ''default_days'' and change it to our default certificate lifetime: 370 days. Furthermore, we find the certificate strengt in the ''[ req ]'' section; we can change it to our preferred value of 2048 bits. Now we can put in the optional bits: the default values. Not necessary, but handy. We go to section ''[ req_distinguished_name ]'' and fill them in. For this, we again use the table we've previously compounded. So the changes we've made will amount to something like this: [ CA_default ] dir = /etc/ssl/ca ... default_days = 370 ... [ req ] default_bits = 2048 ... [ req_distinguished_name ] 0.organizationName_default = Saruman.biz stateOrProvinceName_default = Utrecht countryName_default = NL Especially the last section is, again, a pretty arbitrary choice. You could choose not to provide customized default answers (in which case you're stuck with Internet Widgets Pty from Some-State, AU as the default answers). There are more default values in that section of the ''openssl.cnf'' configuration file; go in there and decide what you want. === Editing the ''CA.sh'' script === Unfortunately, not everything we want to change is actually set from the ''openssl.conf'' file: we'll need to alter some parameters for the root certificate that are hard-coded in the setup scripts. We find the scripts in ''/usr/lib/ssl/misc/''. Note that there are two different scripts: ''CA.sh'', a shell script, and ''CA.pl'', a perl script. Since we're more into shell scripting than perl programming, we go for the shell script. So we edit ''/usr/lib/ssl/misc/CA.sh''; find the two lines near the top that define the variables ''DAYS'' and ''CADAYS'', and set these to what we want them to be. Then, a lot further down, we find the line that's responsible for creating the CA root certificate itself, it's the line that goes ''$REQ -new -keyout ${CATOP}/private/$CAKEY -out ${CATOP}/$CAREQ'' (well actually it's split out over two lines). Here, right after ''-new'' we add ''-newkey rsa:4096''. With all these changes, the three relevant sections in ''CA.sh'' will be changed to something like this: DAYS="-days 370" # 1 year CADAYS="-days 5479" # 15 years ... echo "Making CA certificate ..." $REQ -new -newkey rsa:4096 -keyout ${CATOP}/private/$CAKEY \ -out ${CATOP}/$CAREQ ==the Certificate Authority root certificate== Now with the basic information in place, we can go about generating the certificate itself, and putting it to use. Well, actually we're not going to generate ''one'' certificate, but ''two'': the public one, that we give out to anyone that might want to check the validity of any certificate that claims to have been issued by the Saruman.biz CA, and the private one, with which we can digitally sign certificates so as to prove that they're really issued by said Saruman.biz CA. This is also referred to as a "key pair". ===Creating the CA root certificate key pair=== To generate the CA's public and private root certificate, as root, execute /usr/lib/ssl/misc/CA.sh -newca With the defaults set as given above, you still get some questions. One is "CA certificate filename". This actually requests from you another certificate with which to sign the one we're creating. However, we're generating our root certificate, so we leave this empty and just hit &lt;enter>. Next question is for the PEM passphrase. Make that a strong passphrase or password, keep it very secret, and '''don't forget it!''' (and DON'T write it on a piece of paper; use something like [http://keepass.info keepass] to store your secret passwords). For the next set of questions, you probably have filled in some of the defaults. If you want to leave some entry blank, fill in a period ('''.'''). You'll have to provide the country code, province or state, locality (like city; Saruman.biz leaves this empty), Organization Name, Organizational Unit name (again, empty), and finally the Common Name. This last question is pretty important: the name you put in here is the name under which your CA will go for the next 15 years!! So don't put in a "funny" name, a bland name, or whatever. We put in "Saruman.biz Root CA", somewhat like official root CA's like "Equifax Secure Global eBusiness CA-1" or "Macao Post eSignTrust Root Certification Authority". The script also asks for an email address, which you may or may not provide, a challenge password, and an "optional company name", both of which you can leave blank because we're not sending a certificate signing request out to someone else, but signing it ourselves.<br> Having provided this information, we've actually already created one half of the key pair, namely the private key. It'll be ''/etc/ssl/ca/private/ca.pem'', and is protected by our chosen very strong password. However, we now need the public key, self-signed with the private key. The next step in our CA creation process thus ''again'' asks for the passphrase. Since this is the second step in a two-step process, we again put in the passphrase we've already provided. However, now the shellscript uses this to unlock the private key we've (already) created, and then use it to sign the public key we're now creating. However, the passphrase is ''all'' that it asks. It now generates a signing request (''/etc/ssl/ca/careq.pem''), then uses the private key to sign it, and then generate the public key, to be found in ''/etc/ssl/ca/cacert.pem''. You can remove ''careq.pem'' after you've inspected the ''cacert.pem''. So now we've got two root certificates, namely * '''private''' key ''/etc/ssl/ca/private/cakey.pem'', and * '''public''' key ''/etc/ssl/ca/cacert.pem''. NEVER send your private key out to ANYONE! Protect that key, and its passphrase, with your life. If you lose the file, lose the passphrase, or the key gets compromised (lost to an unknown party) then you've got to replace your root certificates AND you'll have to re-issue ALL certificates that you've ever signed (we're not going into certificate revocation here). You can inspect your certificates (when you're in directory ''/etc/ssl/ca'') with commands like this: openssl x509 -in cacert.pem -noout -text openssl x509 -in cacert.pem -noout -dates openssl x509 -in cacert.pem -noout -purpose Note from the last command above, that this certificate is obviously a root certificate: it can verify the signature of everything but the kitchen sink. In the same manner you can inspect your private key: openssl rsa -in private/cakey.pem -noout -text Note that this can be used to check if the private key and certificate belong together: the `modulus' and the `public exponent' portions in the private key and the certificate must match. But since the public exponent is usually 65537 and it's bothering comparing long modulus you can use the following approach: openssl x509 -in cacert.pem -noout -modulus | openssl md5 openssl rsa -in private/cakey.pem -noout -modulus | openssl md5 And then compare these really shorter numbers. Both commands will output something like: (stdin)= 96a281eca852b794a907186a9703ddf4 With overwhelming probability they will differ if the keys are different. ===We've got the CA certificate, now what?=== With the root CA certificates available to us, we've got the following things to do: * guard very carefully the public and (especially) the private key file; * sign certificates for our own use; * distribute the public CA certificate to every machine/person that may need to verify certificates that we've signed. The first means we've got to keep a copy of the private key file in some other, safe location, and we've got to secure the private key on the server where it sits - both the machine and the file. At the very least, you have to make sure the private key is owned by root or an administrative account, and is ''not'' world-readable. It might even be wise to remove the private key altogether, and keep it on a USB stick, and only read it when signing certificates. The second thing means we've got to generate keys for SSL and TLS connections, just as we need them. This is covered in our [[Creating digital certificates with our root certificate | creating digital certificates]] section. The last point means we need to send out our public CA certificate. In some cases, you can provide others with your ''.pem'' file, but in other cases you're better off providing a simpler ''.crt'' file. The difference is explained nicely at the [http://info.ssl.com/article.aspx?id=12149 ssl.com site] To create a public CA certificate in .crt format you can issue the following command: openssl x509 -outform der -in cacert.pem -out cacert.crt By the way, it's usually better to distribute the public certificate with a more recognizable file name, such as ''saruman.biz.crt'' 0eb18aad478147e7d8e95e8899c391307caf06eb 3094 3093 2016-10-29T20:23:57Z Saruman! 2 /* Creating the CA root certificate key pair */ added passphrase wikitext text/x-wiki ==Certificates, an introduction== Digital certificates are an extremely important means to identify identities (of users, as well as of servers) on the Internet, or indeed on most any network. For instance, we use them to encrypt network traffic when we use the HTTPS protocol. Thus, we really need certificates. Now, as [http://www.debian-administration.org/articles/618 this article] explains, you can either buy your certificates from a certificate authority like [http://www.verisign.com/ VeriSign], [http://www.thawte.com/ Thawte] or [http://www.equifaxsecure.co.uk/index.html Equifax Secure], but these certificates cost more than a couple of Euro's, and also need to be renewed (usually every year). So the other route, the one we'll be taking, is to create our own Certificate Authority (CA), and use that to sign certificates for our needs (secure webserver, secure mailserver etcetera). Now, "creating a CA" sounds like grave installation and configuration work, but in fact a CA does not have to be an actual service, demon or program. A CA is more like a concept, at the heart of which lies the CA "root certificate". So if we obtain a little set of tools and generate our own root certificate, then we're in business. ==Creating the Certificate Authority (CA) - preparations== To generate the root CA for our own little organization, we first need tools. These tools under Debian come with the OpenSSL software - which you'll usually find already installed (if not, run ''apt-get install openssl''). Now to generate the CA root certificate, we'll use a shell script from the OpenSSL package: ''/usr/lib/ssl/misc/CA.sh'', which together with the configuration file ''/etc/ssl/openssl.cnf'' can create our CA root certificate. To that end, we'll first need to decide on some parameters. ===Deciding on CA parameters=== '''How strong''' do we want our root certificate? 1024 bits is the default, but the stronger, the better. We suggest 4096 bits - not because 2048 isn't sufficient (even 1024 is still very very good, even in the year 2016), but because it's not necessary to keep a CA's key length very low, and 4096 can be expected to remain pretty secure until after 2030 (see [http://danielpocock.com/rsa-key-sizes-2048-or-4096-bits here]). How long should our '''CA root certificate remain valid'''? The longer, the more convenient - but maybe some day in the future, you feel you don't want certificates issued ten years ago to just lie around, expired but otherwise valid. Expiry of the root certificate that goes along with that certificate might help you. So what's an appropriate time for your root CA? That depends. For our home CA, we use 15 years. For a business, the cost of providing new root certificates to all computers, employees, and maybe customers, can be so high that you'd rather have 25 years - or maybe security is paramount, and 5 years is long enough for you. We can't say - but our home CA's use 15 years, because we feel that that's a nice intermediate value. 15 years, including about 4 leap days, comes to 5479 days. '''Where do we want to store''' our CA root certificate? By default, the ''CA.sh'' script feels it must store all generated certificates in ''./demoCA''. That's not very handy for us. We rather have a central location like ''/etc/ssl/ca'' on our home server. Yes, it's sound advice to keep the root certificate on an offline machine and all that, but this is for a self-signed certificate, and if this particular directory gets compromised, then so is the whole home server, and we've got greater issues than the loss of a self-signed private key. How long should '''any generated certificate be valid'''? The default value that the ''CA.sh'' script provides is one year. We find that enough - although we add 7 days to accommodate some overlap when having to regenerate the certificate upon nearing the expiry date (note: we really want to replace certificates ''prior'' to expiry :-) '''What "company" data''' will we enter in the certificate? Several fields must be entered, some of which you could fill out at will. However, it's not exactly clear why you would want to confuse people trying to authenticate you, your webserver or some other connection by filling out, for example, the country with an incorrect or even non-existent code. On the other hand, you can keep your own privacy in mind, and not fill in your full name, but rather your website's name, at the "common name" section of your CA root certificate. Again, this depends on what you're going to use your CA for. We at [https://www.saruman.biz saruman.biz] decided to use the following values: * Organization name: Saruman.biz. We're private persons, not companies, but we want to maintain a minimum of privacy, so we've put this fake entity name here. * Country: NL (that's the Netherlands) * Province: Utrecht. Yep, that's a province in the Netherlands, and I happen to live in it. Maybe you want to provide more default information to your CA setup; just look further down on how to. So the information we've decided upon is like this: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Parameter !style="background:#ffdead;"|value |- |root certificate encryption |4096 bits |- |root certificate validity |5479 days (15 years) |- |certificate store |''/etc/ssl/ca'' |- |default certificate validity |370 days (1 year) |- |Organization name |Saruman.biz |- |Certificate province/county name (default) |Utrecht |- |Certificate country name (default) |NL |- |} === Editing the ''openssl.cnf'' configuration file=== When generating certificates, the OpenSSL tools check the configuration file ''/etc/ssl/openssl.cnf''. It is necessary to match the parameters in there with the choices and changes of the previous sections, and also it's handy to change some of the default parameters that certificates require upon generation. It's important to remember that these parameters will be asked every time you generate a certificate, but it's ofcourse pretty handy if the default value is set for your situation, so you can just hit that big &lt;enter> key. First up, we'll change the ''dir'' variable in section ''[ CA_default ]'' to match the dir from the ''CA.sh'' script. Then we find ''default_days'' and change it to our default certificate lifetime: 370 days. Furthermore, we find the certificate strengt in the ''[ req ]'' section; we can change it to our preferred value of 2048 bits. Now we can put in the optional bits: the default values. Not necessary, but handy. We go to section ''[ req_distinguished_name ]'' and fill them in. For this, we again use the table we've previously compounded. So the changes we've made will amount to something like this: [ CA_default ] dir = /etc/ssl/ca ... default_days = 370 ... [ req ] default_bits = 2048 ... [ req_distinguished_name ] 0.organizationName_default = Saruman.biz stateOrProvinceName_default = Utrecht countryName_default = NL Especially the last section is, again, a pretty arbitrary choice. You could choose not to provide customized default answers (in which case you're stuck with Internet Widgets Pty from Some-State, AU as the default answers). There are more default values in that section of the ''openssl.cnf'' configuration file; go in there and decide what you want. === Editing the ''CA.sh'' script === Unfortunately, not everything we want to change is actually set from the ''openssl.conf'' file: we'll need to alter some parameters for the root certificate that are hard-coded in the setup scripts. We find the scripts in ''/usr/lib/ssl/misc/''. Note that there are two different scripts: ''CA.sh'', a shell script, and ''CA.pl'', a perl script. Since we're more into shell scripting than perl programming, we go for the shell script. So we edit ''/usr/lib/ssl/misc/CA.sh''; find the two lines near the top that define the variables ''DAYS'' and ''CADAYS'', and set these to what we want them to be. Then, a lot further down, we find the line that's responsible for creating the CA root certificate itself, it's the line that goes ''$REQ -new -keyout ${CATOP}/private/$CAKEY -out ${CATOP}/$CAREQ'' (well actually it's split out over two lines). Here, right after ''-new'' we add ''-newkey rsa:4096''. With all these changes, the three relevant sections in ''CA.sh'' will be changed to something like this: DAYS="-days 370" # 1 year CADAYS="-days 5479" # 15 years ... echo "Making CA certificate ..." $REQ -new -newkey rsa:4096 -keyout ${CATOP}/private/$CAKEY \ -out ${CATOP}/$CAREQ ==the Certificate Authority root certificate== Now with the basic information in place, we can go about generating the certificate itself, and putting it to use. Well, actually we're not going to generate ''one'' certificate, but ''two'': the public one, that we give out to anyone that might want to check the validity of any certificate that claims to have been issued by the Saruman.biz CA, and the private one, with which we can digitally sign certificates so as to prove that they're really issued by said Saruman.biz CA. This is also referred to as a "key pair". ===Creating the CA root certificate key pair=== To generate the CA's public and private root certificate, as root, execute /usr/lib/ssl/misc/CA.sh -newca With the defaults set as given above, you still get some questions. One is "CA certificate filename". This actually requests from you another certificate with which to sign the one we're creating. However, we're generating our root certificate, so we leave this empty and just hit &lt;enter>. Next question is for the PEM passphrase. Make that a strong passphrase or password, keep it very secret, and '''don't forget it!''' (and DON'T write it on a piece of paper; use something like [http://keepass.info keepass] to store your secret passwords). For the next set of questions, you probably have filled in some of the defaults. If you want to leave some entry blank, fill in a period ('''.'''). You'll have to provide the country code, province or state, locality (like city; Saruman.biz leaves this empty), Organization Name, Organizational Unit name (again, empty), and finally the Common Name. This last question is pretty important: the name you put in here is the name under which your CA will go for the next 15 years!! So don't put in a "funny" name, a bland name, or whatever. We put in "Saruman.biz Root CA", somewhat like official root CA's like "Equifax Secure Global eBusiness CA-1" or "Macao Post eSignTrust Root Certification Authority". The script also asks for an email address, which you may or may not provide, a challenge password, and an "optional company name", both of which you can leave blank because we're not sending a certificate signing request out to someone else, but signing it ourselves.<br> Having provided this information, we've actually already created one half of the key pair, namely the private key. It'll be ''/etc/ssl/ca/private/ca.pem'', and is protected by our chosen very strong password. However, we now need the public key, self-signed with the private key. The next step in our CA creation process thus ''again'' asks for the passphrase. Since this is the second step in a two-step process, we again put in the passphrase we've already provided. However, now the shellscript uses this to unlock the private key we've (already) created, and then use it to sign the public key we're now creating. However, the passphrase is ''all'' that it asks. It now generates a signing request (''/etc/ssl/ca/careq.pem''), then uses the private key to sign it, and then generate the public key, to be found in ''/etc/ssl/ca/cacert.pem''. You can remove ''careq.pem'' after you've inspected the ''cacert.pem''. So now we've got two root certificates, namely * '''private''' key ''/etc/ssl/ca/private/cakey.pem'', and * '''public''' key ''/etc/ssl/ca/cacert.pem''. NEVER send your private key out to ANYONE! Protect that key, and its passphrase, with your life. If you lose the file, lose the passphrase, or the key gets compromised (lost to an unknown party) then you've got to replace your root certificates AND you'll have to re-issue ALL certificates that you've ever signed (we're not going into certificate revocation here). You can inspect your certificates (when you're in directory ''/etc/ssl/ca'') with commands like this: openssl x509 -in cacert.pem -noout -text openssl x509 -in cacert.pem -noout -dates openssl x509 -in cacert.pem -noout -purpose Note from the last command above, that this certificate is obviously a root certificate: it can verify the signature of everything but the kitchen sink. In the same manner you can inspect your private key - note that you'll have to provide the passphrase to complete this command: openssl rsa -in private/cakey.pem -noout -text Note that this can be used to check if the private key and certificate belong together: the `modulus' and the `public exponent' portions in the private key and the certificate must match. But since the public exponent is usually 65537 and it's bothering comparing long modulus you can use the following approach: openssl x509 -in cacert.pem -noout -modulus | openssl md5 openssl rsa -in private/cakey.pem -noout -modulus | openssl md5 And then compare these really shorter numbers (and again, you'll have to provide the passphrase to read the private key). Both commands will output something like: (stdin)= 96a281eca852b794a907186a9703ddf4 With overwhelming probability they will differ if the keys are different. ===We've got the CA certificate, now what?=== With the root CA certificates available to us, we've got the following things to do: * guard very carefully the public and (especially) the private key file; * sign certificates for our own use; * distribute the public CA certificate to every machine/person that may need to verify certificates that we've signed. The first means we've got to keep a copy of the private key file in some other, safe location, and we've got to secure the private key on the server where it sits - both the machine and the file. At the very least, you have to make sure the private key is owned by root or an administrative account, and is ''not'' world-readable. It might even be wise to remove the private key altogether, and keep it on a USB stick, and only read it when signing certificates. The second thing means we've got to generate keys for SSL and TLS connections, just as we need them. This is covered in our [[Creating digital certificates with our root certificate | creating digital certificates]] section. The last point means we need to send out our public CA certificate. In some cases, you can provide others with your ''.pem'' file, but in other cases you're better off providing a simpler ''.crt'' file. The difference is explained nicely at the [http://info.ssl.com/article.aspx?id=12149 ssl.com site] To create a public CA certificate in .crt format you can issue the following command: openssl x509 -outform der -in cacert.pem -out cacert.crt By the way, it's usually better to distribute the public certificate with a more recognizable file name, such as ''saruman.biz.crt'' 418d9f62f5b43a3cb104697b522394c289d64b0c 3095 3094 2016-10-29T20:25:09Z Saruman! 2 /* We've got the CA certificate, now what? */ wikitext text/x-wiki ==Certificates, an introduction== Digital certificates are an extremely important means to identify identities (of users, as well as of servers) on the Internet, or indeed on most any network. For instance, we use them to encrypt network traffic when we use the HTTPS protocol. Thus, we really need certificates. Now, as [http://www.debian-administration.org/articles/618 this article] explains, you can either buy your certificates from a certificate authority like [http://www.verisign.com/ VeriSign], [http://www.thawte.com/ Thawte] or [http://www.equifaxsecure.co.uk/index.html Equifax Secure], but these certificates cost more than a couple of Euro's, and also need to be renewed (usually every year). So the other route, the one we'll be taking, is to create our own Certificate Authority (CA), and use that to sign certificates for our needs (secure webserver, secure mailserver etcetera). Now, "creating a CA" sounds like grave installation and configuration work, but in fact a CA does not have to be an actual service, demon or program. A CA is more like a concept, at the heart of which lies the CA "root certificate". So if we obtain a little set of tools and generate our own root certificate, then we're in business. ==Creating the Certificate Authority (CA) - preparations== To generate the root CA for our own little organization, we first need tools. These tools under Debian come with the OpenSSL software - which you'll usually find already installed (if not, run ''apt-get install openssl''). Now to generate the CA root certificate, we'll use a shell script from the OpenSSL package: ''/usr/lib/ssl/misc/CA.sh'', which together with the configuration file ''/etc/ssl/openssl.cnf'' can create our CA root certificate. To that end, we'll first need to decide on some parameters. ===Deciding on CA parameters=== '''How strong''' do we want our root certificate? 1024 bits is the default, but the stronger, the better. We suggest 4096 bits - not because 2048 isn't sufficient (even 1024 is still very very good, even in the year 2016), but because it's not necessary to keep a CA's key length very low, and 4096 can be expected to remain pretty secure until after 2030 (see [http://danielpocock.com/rsa-key-sizes-2048-or-4096-bits here]). How long should our '''CA root certificate remain valid'''? The longer, the more convenient - but maybe some day in the future, you feel you don't want certificates issued ten years ago to just lie around, expired but otherwise valid. Expiry of the root certificate that goes along with that certificate might help you. So what's an appropriate time for your root CA? That depends. For our home CA, we use 15 years. For a business, the cost of providing new root certificates to all computers, employees, and maybe customers, can be so high that you'd rather have 25 years - or maybe security is paramount, and 5 years is long enough for you. We can't say - but our home CA's use 15 years, because we feel that that's a nice intermediate value. 15 years, including about 4 leap days, comes to 5479 days. '''Where do we want to store''' our CA root certificate? By default, the ''CA.sh'' script feels it must store all generated certificates in ''./demoCA''. That's not very handy for us. We rather have a central location like ''/etc/ssl/ca'' on our home server. Yes, it's sound advice to keep the root certificate on an offline machine and all that, but this is for a self-signed certificate, and if this particular directory gets compromised, then so is the whole home server, and we've got greater issues than the loss of a self-signed private key. How long should '''any generated certificate be valid'''? The default value that the ''CA.sh'' script provides is one year. We find that enough - although we add 7 days to accommodate some overlap when having to regenerate the certificate upon nearing the expiry date (note: we really want to replace certificates ''prior'' to expiry :-) '''What "company" data''' will we enter in the certificate? Several fields must be entered, some of which you could fill out at will. However, it's not exactly clear why you would want to confuse people trying to authenticate you, your webserver or some other connection by filling out, for example, the country with an incorrect or even non-existent code. On the other hand, you can keep your own privacy in mind, and not fill in your full name, but rather your website's name, at the "common name" section of your CA root certificate. Again, this depends on what you're going to use your CA for. We at [https://www.saruman.biz saruman.biz] decided to use the following values: * Organization name: Saruman.biz. We're private persons, not companies, but we want to maintain a minimum of privacy, so we've put this fake entity name here. * Country: NL (that's the Netherlands) * Province: Utrecht. Yep, that's a province in the Netherlands, and I happen to live in it. Maybe you want to provide more default information to your CA setup; just look further down on how to. So the information we've decided upon is like this: {| class="wikitable" style="text-align:center" border="1" cellspacing="0" cellpadding="5" !style="background:#ffdead;"|Parameter !style="background:#ffdead;"|value |- |root certificate encryption |4096 bits |- |root certificate validity |5479 days (15 years) |- |certificate store |''/etc/ssl/ca'' |- |default certificate validity |370 days (1 year) |- |Organization name |Saruman.biz |- |Certificate province/county name (default) |Utrecht |- |Certificate country name (default) |NL |- |} === Editing the ''openssl.cnf'' configuration file=== When generating certificates, the OpenSSL tools check the configuration file ''/etc/ssl/openssl.cnf''. It is necessary to match the parameters in there with the choices and changes of the previous sections, and also it's handy to change some of the default parameters that certificates require upon generation. It's important to remember that these parameters will be asked every time you generate a certificate, but it's ofcourse pretty handy if the default value is set for your situation, so you can just hit that big &lt;enter> key. First up, we'll change the ''dir'' variable in section ''[ CA_default ]'' to match the dir from the ''CA.sh'' script. Then we find ''default_days'' and change it to our default certificate lifetime: 370 days. Furthermore, we find the certificate strengt in the ''[ req ]'' section; we can change it to our preferred value of 2048 bits. Now we can put in the optional bits: the default values. Not necessary, but handy. We go to section ''[ req_distinguished_name ]'' and fill them in. For this, we again use the table we've previously compounded. So the changes we've made will amount to something like this: [ CA_default ] dir = /etc/ssl/ca ... default_days = 370 ... [ req ] default_bits = 2048 ... [ req_distinguished_name ] 0.organizationName_default = Saruman.biz stateOrProvinceName_default = Utrecht countryName_default = NL Especially the last section is, again, a pretty arbitrary choice. You could choose not to provide customized default answers (in which case you're stuck with Internet Widgets Pty from Some-State, AU as the default answers). There are more default values in that section of the ''openssl.cnf'' configuration file; go in there and decide what you want. === Editing the ''CA.sh'' script === Unfortunately, not everything we want to change is actually set from the ''openssl.conf'' file: we'll need to alter some parameters for the root certificate that are hard-coded in the setup scripts. We find the scripts in ''/usr/lib/ssl/misc/''. Note that there are two different scripts: ''CA.sh'', a shell script, and ''CA.pl'', a perl script. Since we're more into shell scripting than perl programming, we go for the shell script. So we edit ''/usr/lib/ssl/misc/CA.sh''; find the two lines near the top that define the variables ''DAYS'' and ''CADAYS'', and set these to what we want them to be. Then, a lot further down, we find the line that's responsible for creating the CA root certificate itself, it's the line that goes ''$REQ -new -keyout ${CATOP}/private/$CAKEY -out ${CATOP}/$CAREQ'' (well actually it's split out over two lines). Here, right after ''-new'' we add ''-newkey rsa:4096''. With all these changes, the three relevant sections in ''CA.sh'' will be changed to something like this: DAYS="-days 370" # 1 year CADAYS="-days 5479" # 15 years ... echo "Making CA certificate ..." $REQ -new -newkey rsa:4096 -keyout ${CATOP}/private/$CAKEY \ -out ${CATOP}/$CAREQ ==the Certificate Authority root certificate== Now with the basic information in place, we can go about generating the certificate itself, and putting it to use. Well, actually we're not going to generate ''one'' certificate, but ''two'': the public one, that we give out to anyone that might want to check the validity of any certificate that claims to have been issued by the Saruman.biz CA, and the private one, with which we can digitally sign certificates so as to prove that they're really issued by said Saruman.biz CA. This is also referred to as a "key pair". ===Creating the CA root certificate key pair=== To generate the CA's public and private root certificate, as root, execute /usr/lib/ssl/misc/CA.sh -newca With the defaults set as given above, you still get some questions. One is "CA certificate filename". This actually requests from you another certificate with which to sign the one we're creating. However, we're generating our root certificate, so we leave this empty and just hit &lt;enter>. Next question is for the PEM passphrase. Make that a strong passphrase or password, keep it very secret, and '''don't forget it!''' (and DON'T write it on a piece of paper; use something like [http://keepass.info keepass] to store your secret passwords). For the next set of questions, you probably have filled in some of the defaults. If you want to leave some entry blank, fill in a period ('''.'''). You'll have to provide the country code, province or state, locality (like city; Saruman.biz leaves this empty), Organization Name, Organizational Unit name (again, empty), and finally the Common Name. This last question is pretty important: the name you put in here is the name under which your CA will go for the next 15 years!! So don't put in a "funny" name, a bland name, or whatever. We put in "Saruman.biz Root CA", somewhat like official root CA's like "Equifax Secure Global eBusiness CA-1" or "Macao Post eSignTrust Root Certification Authority". The script also asks for an email address, which you may or may not provide, a challenge password, and an "optional company name", both of which you can leave blank because we're not sending a certificate signing request out to someone else, but signing it ourselves.<br> Having provided this information, we've actually already created one half of the key pair, namely the private key. It'll be ''/etc/ssl/ca/private/ca.pem'', and is protected by our chosen very strong password. However, we now need the public key, self-signed with the private key. The next step in our CA creation process thus ''again'' asks for the passphrase. Since this is the second step in a two-step process, we again put in the passphrase we've already provided. However, now the shellscript uses this to unlock the private key we've (already) created, and then use it to sign the public key we're now creating. However, the passphrase is ''all'' that it asks. It now generates a signing request (''/etc/ssl/ca/careq.pem''), then uses the private key to sign it, and then generate the public key, to be found in ''/etc/ssl/ca/cacert.pem''. You can remove ''careq.pem'' after you've inspected the ''cacert.pem''. So now we've got two root certificates, namely * '''private''' key ''/etc/ssl/ca/private/cakey.pem'', and * '''public''' key ''/etc/ssl/ca/cacert.pem''. NEVER send your private key out to ANYONE! Protect that key, and its passphrase, with your life. If you lose the file, lose the passphrase, or the key gets compromised (lost to an unknown party) then you've got to replace your root certificates AND you'll have to re-issue ALL certificates that you've ever signed (we're not going into certificate revocation here). You can inspect your certificates (when you're in directory ''/etc/ssl/ca'') with commands like this: openssl x509 -in cacert.pem -noout -text openssl x509 -in cacert.pem -noout -dates openssl x509 -in cacert.pem -noout -purpose Note from the last command above, that this certificate is obviously a root certificate: it can verify the signature of everything but the kitchen sink. In the same manner you can inspect your private key - note that you'll have to provide the passphrase to complete this command: openssl rsa -in private/cakey.pem -noout -text Note that this can be used to check if the private key and certificate belong together: the `modulus' and the `public exponent' portions in the private key and the certificate must match. But since the public exponent is usually 65537 and it's bothering comparing long modulus you can use the following approach: openssl x509 -in cacert.pem -noout -modulus | openssl md5 openssl rsa -in private/cakey.pem -noout -modulus | openssl md5 And then compare these really shorter numbers (and again, you'll have to provide the passphrase to read the private key). Both commands will output something like: (stdin)= 96a281eca852b794a907186a9703ddf4 With overwhelming probability they will differ if the keys are different. ===We've got the CA certificate, now what?=== With the root CA certificates available to us, we've got the following things to do: * guard very carefully the public and (especially) the private key file; * sign certificates for our own use; * distribute the public CA certificate to every machine/person that may need to verify certificates that we've signed. The first means we've got to keep a copy of the private key file in some other, safe location, and we've got to secure the private key on the server where it sits - both the machine and the file. At the very least, you have to make sure the private key is owned by root or an administrative account, and is ''not'' world-readable. It might even be wise to remove the private key altogether, and keep it on a USB stick, and only read it when signing certificates. The second thing means we've got to generate keys for SSL and TLS connections, just as we need them. This is covered in our [[Creating digital certificates with our root certificate | creating digital certificates]] section. The last point means we need to send out our public CA certificate. In some cases, you can provide others with your ''.pem'' file, but in other cases you're better off providing a simpler ''.crt'' file. The difference is explained nicely at the [http://info.ssl.com/article.aspx?id=12149 ssl.com site] To create a public CA certificate in .crt format you can issue the following command: openssl x509 -outform der -in cacert.pem -out cacert.crt By the way, it's usually better to distribute the public certificate with a more recognizable file name, such as ''saruman.bizRootCA.crt'' 97c26c042d5cf4b3571b5bf911a4505478a9ef13 8 1794 3096 2018-08-04T10:03:24Z 127.0.0.1 0 Semantic MediaWiki default vocabulary import wikitext text/x-wiki http://www.w3.org/2004/02/skos/core#|[http://www.w3.org/TR/skos-reference/skos.rdf Simple Knowledge Organization System (SKOS)] altLabel|Type:Monolingual text broader|Type:Annotation URI broaderTransitive|Type:Annotation URI broadMatch|Type:Annotation URI changeNote|Type:Text closeMatch|Type:Annotation URI Collection|Class Concept|Class ConceptScheme|Class definition|Type:Text editorialNote|Type:Text exactMatch|Type:Annotation URI example|Type:Text hasTopConcept|Type:Page hiddenLabel|Type:String historyNote|Type:Text inScheme|Type:Page mappingRelation|Type:Page member|Type:Page memberList|Type:Page narrower|Type:Annotation URI narrowerTransitive|Type:Annotation URI narrowMatch|Type:Annotation URI notation|Type:Text note|Type:Text OrderedCollection|Class prefLabel|Type:String related|Type:Annotation URI relatedMatch|Type:Annotation URI scopeNote|Type:Text semanticRelation|Type:Page topConceptOf|Type:Page [[Category:Imported vocabulary]] 4327e3118f75f756b955108e04693a361d19c2cb 8 1795 3097 2018-08-04T10:03:24Z 127.0.0.1 0 Semantic MediaWiki default vocabulary import wikitext text/x-wiki http://xmlns.com/foaf/0.1/|[http://www.foaf-project.org/ Friend Of A Friend] name|Type:Text homepage|Type:URL mbox|Type:Email mbox_sha1sum|Type:Text depiction|Type:URL phone|Type:Text Person|Category Organization|Category knows|Type:Page member|Type:Page [[Category:Imported vocabulary]] 2be18fc91e334e0c7f23bea734cdc2a301fd86e8 8 1796 3098 2018-08-04T10:03:25Z 127.0.0.1 0 Semantic MediaWiki default vocabulary import wikitext text/x-wiki http://www.w3.org/2002/07/owl#|[http://www.w3.org/2002/07/owl Web Ontology Language (OWL)] AllDifferent|Category allValuesFrom|Type:Page AnnotationProperty|Category backwardCompatibleWith|Type:Page cardinality|Type:Number Class|Category comment|Type:Page complementOf|Type:Page DataRange|Category DatatypeProperty|Category DeprecatedClass|Category DeprecatedProperty|Category differentFrom|Type:Page disjointWith|Type:Page distinctMembers|Type:Page equivalentClass|Type:Page equivalentProperty|Type:Page FunctionalProperty|Category hasValue|Type:Page imports|Type:Page incompatibleWith|Type:Page intersectionOf|Type:Page InverseFunctionalProperty|Category inverseOf|Type:Page isDefinedBy|Type:Page label|Type:Page maxCardinality|Type:Number minCardinality|Type:Number Nothing|Category ObjectProperty|Category oneOf|Type:Page onProperty|Type:Page Ontology|Category OntologyProperty|Category owl|Type:Page priorVersion|Type:Page Restriction|Category sameAs|Type:Page seeAlso|Type:Page someValuesFrom|Type:Page SymmetricProperty|Category Thing|Category TransitiveProperty|Category unionOf|Type:Page versionInfo|Type:Page [[Category:Imported vocabulary]] c109cc4c667590611dc35b3d06655129c572809a 102 1797 3099 2018-08-04T10:03:25Z 127.0.0.1 0 Semantic MediaWiki default vocabulary import wikitext text/x-wiki * [[Imported from::foaf:knows]] * [[Has property description::A person known by this person (indicating some level of reciprocated interaction between the parties).@en]] [[Category:Imported vocabulary]] {{DISPLAYTITLE:foaf:knows}} 2e89ed95e185b4c58a7a5447384e5849a1e3c7f3 102 1798 3100 2018-08-04T10:03:25Z 127.0.0.1 0 Semantic MediaWiki default vocabulary import wikitext text/x-wiki * [[Imported from::foaf:name]] * [[Has property description::A name for some thing or agent.@en]] [[Category:Imported vocabulary]]{{DISPLAYTITLE:foaf:name}} c7ea16f5cc0a25bd5d35c418f8590635e1a59104 102 1799 3101 2018-08-04T10:03:25Z 127.0.0.1 0 Semantic MediaWiki default vocabulary import wikitext text/x-wiki * [[Imported from::foaf:homepage]] * [[Has property description::URL of the homepage of something, which is a general web resource.@en]] [[Category:Imported vocabulary]] {{DISPLAYTITLE:foaf:homepage}} 196c572bc4f2be88cd6d3ed8d07b37fa1549930b 102 1800 3102 2018-08-04T10:03:25Z 127.0.0.1 0 Semantic MediaWiki default vocabulary import wikitext text/x-wiki * [[Imported from::owl:differentFrom]] * [[Has property description::The property that determines that two given individuals are different.@en]] [[Category:Imported vocabulary]] {{DISPLAYTITLE:owl:differentFrom}} 1c0d6ecdafcfea48f8f2200a81155a64419fa055 112 1801 3108 2019-12-02T12:12:39Z 127.0.0.1 0 Semantic MediaWiki group import smw/schema application/json { "type": "PROPERTY_GROUP_SCHEMA", "groups": [ { "group_name": "Schema properties", "message_key": "smw-property-group-label-schema-group", "properties": [ "_SCHEMA_TYPE", "_SCHEMA_DEF", "_SCHEMA_DESC", "_SCHEMA_TAG", "_SCHEMA_LINK", "_FORMAT_SCHEMA", "_CONSTRAINT_SCHEMA", "_PROFILE_SCHEMA" ] } ], "tags": [ "group", "property group" ] } db1874786764ef6634ddfc9cb10c19ed78708dc7 112 1802 3109 2021-09-23T14:59:57Z 127.0.0.1 0 Semantic MediaWiki group import smw/schema application/json { "type": "PROPERTY_GROUP_SCHEMA", "groups": { "administrative_group": { "canonical_name": "Adminstrative properties", "message_key": "smw-property-group-label-administrative-properties", "property_keys": [ "_MDAT", "_CDAT", "_NEWP", "_LEDT", "_DTITLE", "_CHGPRO", "_EDIP", "_ERRC" ] }, "classification_group": { "canonical_name": "Classification properties", "message_key": "smw-property-group-label-classification-properties", "property_keys": [ "_INST", "_PPGR", "_SUBP", "_SUBC" ] }, "content_group": { "canonical_name": "Content properties", "message_key": "smw-property-group-label-content-properties", "property_keys": [ "_SOBJ", "_ASK", "_MEDIA", "_MIME", "_ATTCH_LINK", "_FILE_ATTCH", "_CONT_TYPE", "_CONT_AUTHOR", "_CONT_LEN", "_CONT_LANG", "_CONT_TITLE", "_CONT_DATE", "_CONT_KEYW", "_TRANS", "_TRANS_SOURCE", "_TRANS_GROUP" ] }, "declarative_group": { "canonical_name": "Declarative properties", "message_key": "smw-property-group-label-declarative-properties", "property_keys": [ "_TYPE", "_UNIT", "_IMPO", "_CONV", "_SERV", "_PVAL", "_LIST", "_PREC", "_PDESC", "_PPLB", "_PVAP", "_PVALI", "_PVUC", "_PEID", "_PEFU" ] } }, "tags": [ "group", "property group" ] } 8536eb8767d6dc5a87a0b4f7791b9cd791acbd75